Introduction

The DayOneMart Customer App is a cross-platform mobile application built with Flutter for Android and iOS. It provides customers with an end-to-end shopping experience β€” browsing products, placing orders, real-time tracking, live chat, wallet management, loyalty points, and more.

The app connects exclusively to the OneMart Admin & Web backend via the REST API at /api/v1/customer/*. Real-time features (chat, notifications) are powered by Firebase Cloud Messaging.

Technology Stack

LayerPackage / TechnologyVersion
FrameworkFlutterSDK (stable)
LanguageDart^3.10.0
State Managementflutter_bloc + BLoC^9.1 / ^9.2
Persisted Statehydrated_bloc^11.0
Navigationgo_router^17.2
Dependency Injectionget_it + injectable^9.2 / ^2.7
Code Generationfreezed + json_serializable^3.2 / ^6.13
Networkinghttp^1.6
FirebaseCore, Messaging, Crashlytics, Analytics^4.7 / ^16.2
Maps & Locationgoogle_maps_flutter + geolocator + geocoding^2.17 / ^14.0 / ^4.0
Social Authgoogle_sign_in, flutter_facebook_auth, sign_in_with_apple^7.2 / ^7.1 / ^7.0
Imagescached_network_image + flutter_image_compress^3.4 / ^2.4
Animationslottie^3.3
Localizationflutter_localizations + intlSDK / ^0.20
Notificationsflutter_local_notifications + timezone^21.0 / ^0.11
Secure Storageflutter_secure_storage^10.0
PDF / Filesflutter_html_to_pdf_plus + open_filexLatest
Crash Reportingfirebase_crashlytics^5.2

Architecture Overview

The app follows a feature-first clean architecture pattern:

App Features

πŸš€
Splash & Onboarding Animated splash screen, first-run onboarding flow
πŸ”
Authentication Email, phone OTP, Google, Facebook, Apple login
🏠
Home / Dashboard Banners, featured items, categories, recommendations
πŸ”
Search Autocomplete search, voice search (speech_to_text)
πŸ“¦
Product Browsing Categories, sub-categories, menu types, labels
πŸ›’
Cart Add/edit/remove items, quantity control, add-to-cart animation
πŸ’³
Checkout Address selection, delivery charge, coupon, payment
🏷️
Offers Coupons, flash sales with countdown timers
πŸ“
Order Tracking Real-time order status + Google Maps live tracking
πŸ’°
Wallet View balance, add money, transaction history
🎁
Loyalty Points Earn on orders, view history, redeem at checkout
πŸ”—
Referral Referral program with share integration
❀️
Wishlist Save and manage favourite products
⭐
Reviews Rate and review products after delivery
πŸ’¬
Live Chat Chat with support, emoji keyboard, file attachments
πŸ””
Notifications Push (Firebase), local, in-app notification list
πŸ‘€
Profile Edit profile, change password, settings, delete account
πŸ“
Address Book CRUD delivery addresses with Google Maps picker
🌐
Multi-language English, Spanish, Arabic, Hindi, Bangla
πŸ“„
Invoice Download Generate and download order invoices as PDF
Flash Sales Time-limited flash sale campaigns with countdown
🏷
Brands Browse products by popular brands
🌐
In-App Webview Payment gateways and external links in secure webview

Key Screens (Annotated)

Capture these core screens on a device or emulator and annotate the numbered areas below with arrows or callouts before resubmission. Save each image with the exact file name shown.

Customer App Home screen β€” delivery location, module tabs, promo banners, popular categories, and flash deals 1 2 3 4

Key areas of this screen

  1. Delivery location β€” the customer's address selector, plus the gift and wallet shortcuts.
  2. Module tabs β€” switch between Grocery, Pharmacy, and Shop.
  3. Promotional banners β€” the swipeable carousel managed from the admin panel.
  4. Popular Categories & Flash Deals β€” quick category access and time-limited offers; the bottom bar navigates Home, Search, Categories, Cart, and Account.
Home / Dashboard. The first screen customers see after launch. Numbered markers highlight the four key areas.
Customer App Checkout β€” personal info, delivery info, delivery schedule, payment, receipt, and Place Order 1 2 3 4

Key areas of this screen

  1. Personal & Delivery Info β€” the customer's email and the selected drop-off address (editable).
  2. Delivery Schedule β€” pick a delivery date and time slot.
  3. Select Payment β€” choose a payment method / gateway.
  4. Receipt & Place Order β€” subtotal, discount, shipping fee, VAT-inclusive total, and the Place Order button.
Checkout. The conversion flow from cart to placed order. Numbered markers highlight the four key areas.
Customer App Order Details β€” order status, delivery info, ordered item, delivery schedule, delivery hub, and Cancel Order 1 2 3 4

Key areas of this screen

  1. Order status β€” the order number and current stage (e.g. Pending β†’ Confirmed β†’ On the Way β†’ Delivered).
  2. Delivery Info β€” recipient name, phone, and delivery address.
  3. Ordered items & schedule β€” the products with variation/quantity/price and the chosen delivery date and slot.
  4. Delivery Hub & actions β€” the fulfilling hub, the floating call/support buttons, and Cancel Order.
Order Details / Tracking. Post-purchase status and delivery information; a live map appears once the order is out for delivery. Numbered markers highlight the four key areas.

Prerequisites

Development Machine Requirements

ToolMinimum VersionNotes
Flutter SDK3.x (stable channel)Run flutter --version to check
Dart SDK^3.10.0Bundled with Flutter
Android StudioHedgehog (2023.1+)Required for Android builds
Xcode15+macOS only β€” required for iOS builds
CocoaPodsLatestmacOS only β€” sudo gem install cocoapods
Java JDK17For Android Gradle builds
Node.js18+ (optional)Needed for Firebase CLI (flutterfire)

External Services Required

Flutter Environment Check

flutter doctor -v

Resolve all errors before proceeding. Warnings for unneeded platforms (e.g. Linux, Windows) can be ignored if you only target Android/iOS.

Project Structure

lib/
β”œβ”€β”€ main.dart                       ← App entry point
β”œβ”€β”€ firebase_options.dart           ← Generated by FlutterFire CLI
β”‚
β”œβ”€β”€ config/
β”‚   β”œβ”€β”€ route/
β”‚   β”‚   └── route_config.dart       ← GoRouter route definitions
β”‚   β”œβ”€β”€ theme/                      ← App theme (colors, typography)
β”‚   └── util/
β”‚       β”œβ”€β”€ app_constants.dart      ← API base URL + all endpoints
β”‚       β”œβ”€β”€ assets.gen.dart         ← Generated asset references
β”‚       β”œβ”€β”€ dimensions.dart         ← Spacing / size constants
β”‚       β”œβ”€β”€ instance_names.dart     ← GetIt named instance keys
β”‚       └── styles.dart             ← Reusable TextStyles
β”‚
β”œβ”€β”€ core/
β”‚   β”œβ”€β”€ data/                       ← Base network client, interceptors, enums
β”‚   β”œβ”€β”€ dependency_injection/       ← GetIt setup + injectable module
β”‚   └── helper/                     ← Utility helpers (notifications, extensions)
β”‚
β”œβ”€β”€ features/                       ← Feature-first modules
β”‚   β”œβ”€β”€ splash/
β”‚   β”œβ”€β”€ onboarding/
β”‚   β”œβ”€β”€ login/                      ← Auth BLoC, repo, screens
β”‚   β”œβ”€β”€ home/
β”‚   β”œβ”€β”€ dashboard/
β”‚   β”œβ”€β”€ category/
β”‚   β”œβ”€β”€ menu/
β”‚   β”œβ”€β”€ search/
β”‚   β”œβ”€β”€ cart/
β”‚   β”œβ”€β”€ checkout/
β”‚   β”œβ”€β”€ offers/
β”‚   β”œβ”€β”€ order/
β”‚   β”œβ”€β”€ payment/
β”‚   β”œβ”€β”€ wallet/
β”‚   β”œβ”€β”€ loyalty_point/
β”‚   β”œβ”€β”€ referral/
β”‚   β”œβ”€β”€ wishlist/
β”‚   β”œβ”€β”€ review/
β”‚   β”œβ”€β”€ notification/
β”‚   β”œβ”€β”€ chat/
β”‚   β”œβ”€β”€ account/
β”‚   β”œβ”€β”€ address/
β”‚   β”œβ”€β”€ settings/
β”‚   β”œβ”€β”€ about_us/
β”‚   β”œβ”€β”€ contact_us/
β”‚   β”œβ”€β”€ faq/
β”‚   β”œβ”€β”€ privacy_policy/
β”‚   β”œβ”€β”€ terms_and_condition/
β”‚   β”œβ”€β”€ refund_policy/
β”‚   β”œβ”€β”€ common_condition/
β”‚   β”œβ”€β”€ html/
β”‚   β”œβ”€β”€ webview/
β”‚   └── file_viewer/
β”‚
└── l10n/
    β”œβ”€β”€ arb/                        ← ARB localization source files
    β”‚   β”œβ”€β”€ app_en.arb
    β”‚   β”œβ”€β”€ app_es.arb
    β”‚   β”œβ”€β”€ app_ar.arb
    β”‚   β”œβ”€β”€ app_hi.arb
    β”‚   └── app_bn.arb
    └── gen/                        ← Generated localization classes
        └── app_localizations.dart

assets/
β”œβ”€β”€ images/                         ← PNG / JPG images
β”‚   β”œβ”€β”€ svg/                        ← SVG icons
β”‚   β”‚   └── flags/                  ← Country flag SVGs
β”‚   └── gif/                        ← Animated GIFs
└── json/                           ← Lottie animation JSON files

Feature Module Structure

Each feature follows the same internal layout:

features/order/
β”œβ”€β”€ data/
β”‚   β”œβ”€β”€ datasource/         ← Remote data source (API calls)
β”‚   β”œβ”€β”€ model/              ← Freezed + JSON serializable DTOs
β”‚   └── repository/         ← Repository implementation
β”œβ”€β”€ domain/
β”‚   β”œβ”€β”€ entity/             ← Clean domain entities
β”‚   └── repository/         ← Repository abstract interface
└── presentation/
    β”œβ”€β”€ bloc/               ← BLoC / Cubit + States + Events
    β”œβ”€β”€ screen/             ← Full-screen widgets
    └── widget/             ← Reusable widgets for this feature

Installation Guide (Step-by-Step)

Follow these steps in order to go from the downloaded ZIP to the app running on a device. Steps 6–8 point to their own detailed sections further down this page.

Before You Start β€” Checklist

  1. Extract the project Unzip the package and open the Customer App folder in your editor (VS Code / Android Studio). All commands below are run from this folder.
  2. Verify your Flutter environment
    flutter doctor -v
    
    Fix any reported errors before continuing (missing Android SDK, unaccepted licenses, no Xcode). Warnings about platforms you don't target can be ignored.
  3. Install dependencies
    flutter pub get
    
  4. Generate code The project uses code generation for models, dependency injection, assets, and translations β€” the app will not compile without this step:
    dart run build_runner build --delete-conflicting-outputs
    flutter gen-l10n
    
  5. Point the app at your backend Open lib/config/util/app_constants.dart and set baseUrl to your deployed Admin & Web instance (always https:// in production):
    static const String baseUrl = 'https://yourdomain.com';
    
    Details in Configuration.
  6. Connect Firebase Register the Android and iOS apps in your Firebase project, then place google-services.json in android/app/ and GoogleService-Info.plist in ios/Runner/ (or run flutterfire configure). Full walkthrough: Firebase Setup.
  7. Add your Google Maps API key Copy secrets.xml.example to android/app/src/main/res/values/secrets.xml and fill in the key; add the iOS key to Info.plist. Full walkthrough: Google Maps Setup.
  8. (Optional) Configure social login Google works out of the box once Firebase is connected; Facebook and Apple need provider setup β€” see Social Auth Setup.
  9. Run the app
    flutter devices                  # list connected devices
    flutter run -d <device-id>      # debug build on a device
    flutter run --release            # production-like build
    
    Log in with a customer account created on your storefront, browse products, and place a test order to confirm the backend connection.
  10. Rebrand and release Rename the app, set your bundle ID, icon, splash, and colors using the Branding & Customization Guide, then produce store builds following Build & Release.

Configuration

API Base URL

Open lib/config/util/app_constants.dart and update the baseUrl to point to your deployed OneMart Admin & Web instance:

// lib/config/util/app_constants.dart

class AppConstants {
  static const String baseUrl = 'https://yourdomain.com';
  // All endpoint paths are defined as constants below...
}
⚠️
Always use HTTPS for the base URL in production. Android 9+ and iOS block plaintext HTTP connections by default (Network Security Config / ATS).

App Module

The app supports multiple business modules. The default is set in lib/config/util/app_constants.dart:

// lib/config/util/app_constants.dart
static const AppModule defaultModule = AppModule.grocery;

Change this enum value to match your business type if needed.

Customer App in-app Settings screen β€” Language, Setup Password, offer preferences, and Notification / Location / Microphone permission toggles

Annotate on the Settings screen

  1. Language selector β€” switch the app's display language.
  2. Set up password β€” for accounts created via OTP/social login.
  3. Offer preferences β€” email/SMS marketing opt-in toggles.
  4. Permission toggles β€” notification, location, and microphone access.
Customer App β†’ Settings. The in-app Settings screen lets users switch language, set up a password, opt in to email/SMS offers, and toggle notification, location, and microphone permissions. The backend URL the app connects to is set separately in lib/config/util/app_constants.dart (see above).

App Name & Bundle ID

PlatformFileKey
Android android/app/build.gradle applicationId
Android android/app/src/main/AndroidManifest.xml android:label
iOS ios/Runner/Info.plist CFBundleName, CFBundleIdentifier

Firebase Setup

Step 1 β€” Create a Firebase Project

  1. Go to the Firebase Console and create a new project (or use an existing one shared with the backend).
  2. Register Android app β€” use the package name from android/app/build.gradle (default: com.dayonesoft.onemartcustomer). Download google-services.json and place it at android/app/google-services.json.
  3. Register iOS app β€” use the bundle ID from Xcode. Download GoogleService-Info.plist and add it to Xcode at ios/Runner/GoogleService-Info.plist.

Step 2 β€” Generate firebase_options.dart (Recommended)

Use the FlutterFire CLI for a clean, automated setup:

# Install FlutterFire CLI
dart pub global activate flutterfire_cli

# Configure β€” follow the interactive prompts
flutterfire configure

This generates/updates lib/firebase_options.dart automatically.

ℹ️
The firebase_options.dart file already exists in the project with sample values. Replace its contents with the output from flutterfire configure.

Step 3 β€” Enable Firebase Services

In the Firebase Console, enable the following services:

FCM Topics

The app subscribes to the following FCM topics on launch:

customer-group    // All customer-specific broadcast messages
all-general       // Platform-wide announcements

Google Maps Setup

Step 1 β€” Enable APIs in Google Cloud Console

Step 2 β€” Add API Key to secrets.xml (Android)

Copy the template and fill in your key:

cp secrets.xml.example android/app/src/main/res/values/secrets.xml
<!-- android/app/src/main/res/values/secrets.xml -->
<resources>
  <string name="google_maps_api_key">YOUR_GOOGLE_MAPS_API_KEY</string>
  <string name="facebook_app_id">YOUR_FACEBOOK_APP_ID</string>
  <string name="fb_login_protocol_scheme">fbYOUR_FACEBOOK_APP_ID</string>
  <string name="facebook_client_token">YOUR_FACEBOOK_CLIENT_TOKEN</string>
</resources>

Step 3 β€” Add API Key for iOS

In ios/Runner/AppDelegate.swift, the Maps key is read from the Info.plist. Add it to ios/Runner/Info.plist:

<key>GoogleMapsApiKey</key>
<string>YOUR_GOOGLE_MAPS_API_KEY</string>

Social Auth Setup

Google Sign-In

Facebook Login

  1. Create a Facebook App at developers.facebook.com. Add "Facebook Login" as a product. Note the App ID and client token.
  2. Add credentials to secrets.xml (Android) as shown in the Google Maps section above.
  3. iOS: Add FacebookAppID, FacebookClientToken, and FacebookDisplayName keys to ios/Runner/Info.plist. Also add the URL scheme fb{YOUR_APP_ID} to the CFBundleURLSchemes array.

Sign in with Apple

Localization

The app supports 5 languages out of the box:

LanguageCodeARB File
Englishenlib/l10n/arb/app_en.arb
Spanisheslib/l10n/arb/app_es.arb
Arabicarlib/l10n/arb/app_ar.arb
Hindihilib/l10n/arb/app_hi.arb
Banglabnlib/l10n/arb/app_bn.arb

Localization Config

The localization configuration is defined in l10n.yaml:

arb-dir: lib/l10n/arb
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart
output-dir: lib/l10n/gen
nullable-getter: false

Adding a New Language

  1. Create a new ARB file, e.g. lib/l10n/arb/app_fr.arb. Copy the structure from app_en.arb and translate all strings.
  2. Add the language to the languages list in app_constants.dart:
    LanguageModel(code: 'fr', name: 'French', nativeName: 'FranΓ§ais'),
    
  3. Regenerate localization files:
    flutter gen-l10n
    
ℹ️
Arabic (ar) is an RTL language. Flutter handles layout mirroring automatically when the ar locale is active. Untranslated strings are tracked in untranslated.txt at the project root.

Mobile App Build Requirements

Before you can produce a store-ready build of the app, both platforms require their own code-signing setup. This section walks through Android keystore generation and iOS code signing end to end. Complete these once per app; the signing material is then reused for every future release and update.

PlatformYou needWhere it is used
AndroidAn upload/release keystore (.jks) + key.propertiesSigns the .aab / .apk for Google Play
iOSApple Developer Program membership, a Distribution certificate, an App ID, and a provisioning profileSigns the .ipa for the App Store / TestFlight

Android β€” Keystore Generation

Google Play requires every release build to be digitally signed with a keystore you own. Generate one with the JDK's keytool utility:

keytool -genkey -v \
  -keystore upload-keystore.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias upload

You will be prompted for a keystore password, a key password, and your organisation details. This produces an upload-keystore.jks file. Move it into the Android app module (for example android/app/upload-keystore.jks), then create android/key.properties so Gradle can locate and use it:

# android/key.properties
storePassword=<your-store-password>
keyPassword=<your-key-password>
keyAlias=upload
storeFile=upload-keystore.jks

The app's android/app/build.gradle.kts is already wired to read key.properties and apply the release signing config automatically β€” no further Gradle edits are needed. Once the file is in place, flutter build appbundle --release produces a signed, upload-ready bundle.

⚠️
Store the .jks keystore and its passwords somewhere safe and backed up, and keep key.properties out of version control. If you lose the keystore you can never publish an update to the same Google Play listing again.

iOS β€” Code Signing

iOS builds must be signed with credentials issued by Apple. You need a paid Apple Developer Program membership before you can create a distributable build.

  1. Register an App ID (Bundle Identifier) In the Apple Developer portal β†’ Certificates, Identifiers & Profiles β†’ Identifiers, register a unique bundle ID (e.g. com.yourcompany.onemartcustomer). Enable the capabilities the app uses (Push Notifications, Sign in with Apple).
  2. Create a Distribution certificate Under Certificates, create an Apple Distribution certificate and install it into your Mac's login Keychain. This is the identity that signs release builds.
  3. Create a provisioning profile Create an App Store distribution provisioning profile that links your App ID to your distribution certificate, then download and double-click it to install.
  4. Configure signing in Xcode Open ios/Runner.xcworkspace β†’ select the Runner target β†’ Signing & Capabilities. Set your Team and the Bundle Identifier to match the App ID above. For most users, Automatically manage signing is the simplest option; choose manual signing only if you manage profiles yourself.
  5. Create the app record in App Store Connect In App Store Connect, create a new app using the same bundle ID so you can upload builds to TestFlight and the App Store.
ℹ️
You only need a Mac with Xcode to build and sign iOS apps. Android keystore generation works on any platform (Windows, macOS, or Linux) as long as the JDK is installed. Concrete build commands for both platforms follow in the next section.

Build & Release

Android β€” Debug Build

flutter build apk --debug
# Output: build/app/outputs/flutter-apk/app-debug.apk

Android β€” Release APK

flutter build apk --release
# Output: build/app/outputs/flutter-apk/app-release.apk

Android β€” App Bundle (Google Play)

flutter build appbundle --release \
  --obfuscate \
  --split-debug-info=build/app/outputs/symbols
# Output: build/app/outputs/bundle/release/app-release.aab
ℹ️
--obfuscate shrinks and obfuscates Dart code. --split-debug-info separates debug symbols needed for deobfuscating stack traces in Crashlytics. Save the symbols directory alongside your release.

Android β€” Signing

The app is already configured to automatically sign release builds when you provide a key.properties file.

  1. Create a release keystore:
    keytool -genkey -v -keystore android/app/upload-keystore.jks \
      -keyalg RSA -keysize 2048 -validity 10000 -alias upload
    
  2. Create android/key.properties:
    storePassword=<your-store-password>
    keyPassword=<your-key-password>
    keyAlias=upload
    storeFile=upload-keystore.jks
    
⚠️
Keep the keystore (.jks) and key.properties file safe. You need them for every future app update on Google Play. Losing the keystore means you cannot publish updates to the same listing.

iOS β€” Debug

flutter build ios --debug --simulator

iOS β€” Release (App Store)

flutter build ipa --release \
  --obfuscate \
  --split-debug-info=build/ios/symbols

Then open build/ios/ipa in Xcode Organizer or use Transporter to upload to App Store Connect.

Publishing to Google Play β€” Step by Step

With the signed .aab from the previous section, here is the complete path from build to a live Google Play listing:

  1. Create a Google Play developer account Register at play.google.com/console (one-time $25 fee). Identity verification can take a day or two for new accounts.
  2. Create the app In the Play Console: All apps β†’ Create app. Enter your app name, default language, select App (not Game) and Free, and accept the declarations.
  3. Complete the "Set up your app" checklist On the app's Dashboard, work through every task before your first release: privacy policy URL (the storefront's Privacy Policy page works), App access (provide a working demo login so Google's reviewers can sign in), Ads declaration, Content rating questionnaire, Target audience, and the Data safety form β€” declare that the app collects location, name, email, and phone number for order delivery.
  4. Build the signed bundle Confirm android/key.properties is in place, then run flutter build appbundle --release. The signed bundle is written to build/app/outputs/bundle/release/app-release.aab.
  5. Test with an Internal testing release first Go to Testing β†’ Internal testing β†’ Create new release, upload the .aab, add your email as a tester, and install the app on a real device via the opt-in link. Verify login, browsing, checkout, and push notifications against your live backend before going public.
  6. Roll out to Production Once the internal build works, go to Production β†’ Create new release (or promote the internal release), add release notes, review, and Start rollout.
  7. Wait for review First-time reviews typically take from a few hours up to about 7 days. Subsequent updates are usually much faster.

Publishing to the App Store β€” Step by Step

  1. Prerequisites Complete the iOS code-signing setup above: Apple Developer membership, App ID, signing configured in Xcode, and the app record created in App Store Connect.
  2. Build the signed archive Run flutter build ipa --release. The signed .ipa is written to build/ios/ipa/.
  3. Upload the build Open Apple's free Transporter app (Mac App Store), sign in with your Apple ID, drag the .ipa in, and click Deliver. (Alternative: open the archive in Xcode Organizer and click Distribute App.)
  4. Wait for processing, then test via TestFlight In App Store Connect the build appears under TestFlight after 15–60 minutes of processing. Install it on a real device with the TestFlight app and verify login, checkout, and push notifications.
  5. Complete the App Store listing In App Store Connect fill in: screenshots for the required device sizes, description, keywords, support URL, privacy policy URL, and the App Privacy questionnaire (declare location, contact info, and identifiers collected for order delivery).
  6. Submit for review Select the build, add review notes with a working demo account (Apple rejects apps it cannot log in to), and submit. Reviews typically complete within 24–48 hours.
ℹ️
Common App Store rejection traps β€” both are already handled by this app, just don't remove them: Apple requires Sign in with Apple whenever other social logins are offered, and requires an in-app account deletion option (Profile β†’ Delete Account).

Versioning App Updates

The app version lives in pubspec.yaml:

# pubspec.yaml
version: 4.0.0+40
#        β”‚     └─ build number β†’ Android versionCode / iOS build number
#        └─────── display version β†’ Android versionName / iOS version

Every upload to Google Play or App Store Connect must have a higher build number (the part after +) than the previous upload. Bump it, rebuild, and re-upload β€” e.g. 4.0.0+40 β†’ 4.0.1+41.

Common Build & Signing Errors

ErrorCauseFix
Keystore was tampered with, or password was incorrect Wrong storePassword / keyPassword in key.properties Re-check both passwords; they must match what you entered in keytool.
Release build is signed with debug keys / Play rejects the upload android/key.properties missing, or storeFile path wrong The storeFile path is relative to android/app/. Place the .jks at android/app/upload-keystore.jks and use storeFile=upload-keystore.jks.
Android sdkmanager licences not accepted SDK licences never accepted on this machine Run flutter doctor --android-licenses and accept all.
CocoaPods errors during iOS build Stale or missing pods cd ios && pod repo update && pod install, then rebuild.
No signing certificate "iOS Distribution" found Distribution certificate not installed in this Mac's Keychain Enable Automatically manage signing with your Team selected in Xcode, or download and double-click your distribution certificate.
Version code X has already been used (Play Console) Uploading a build with the same or lower build number Increase the +N build number in pubspec.yaml and rebuild.

Code Generation (after model changes)

# One-time build
dart run build_runner build --delete-conflicting-outputs

# Watch mode (during development)
dart run build_runner watch --delete-conflicting-outputs

Secure Storage

Auth tokens are stored securely via flutter_secure_storage (Android Keystore / iOS Keychain) instead of SharedPreferences.

Android

iOS

Crash Reporting

The app uses Firebase Crashlytics for crash reporting in production builds.

Build ModeBehavior
DebugErrors print to the console (Flutter default). No remote reporting.
ReleaseUncaught errors are reported to Firebase Crashlytics automatically via FlutterError.onError and PlatformDispatcher.instance.onError in lib/main.dart.

Setup

API Integration

All API endpoints consumed by the app are declared as constants in lib/config/util/app_constants.dart. The base URL is prepended at runtime by the core HTTP client in lib/core/data/.

πŸ”Œ
The full endpoint-by-endpoint technical reference β€” methods, paths, auth requirements, response envelope, payment callbacks, and third-party integration points β€” is on the dedicated API Reference page.

Authentication Flow

POST /api/v1/customer/auth/check-user-exists  ← Check if user exists
POST /api/v1/customer/auth/login              ← Email/phone + password
POST /api/v1/customer/auth/send-login-otp     ← Request login OTP
POST /api/v1/customer/auth/verify-login-otp   ← Verify OTP β†’ returns JWT
POST /api/v1/customer/auth/forgot-password     ← Initiate password reset
POST /api/v1/customer/auth/verify-otp          ← Verify reset OTP
POST /api/v1/customer/auth/reset-password      ← Set new password
POST /api/v1/customer/auth/google             ← Google ID token
POST /api/v1/customer/auth/facebook           ← Facebook access token
POST /api/v1/customer/auth/apple              ← Apple identity token
POST /api/v1/customer/auth/refresh            ← Refresh JWT
POST /api/v1/customer/auth/logout

Request Headers

Authorization: Bearer {jwt_token}
Accept: application/json
Content-Type: application/json
X-localization: en         ← Current language code (en, ar, hi, es, bn)

Core Endpoints Summary

FeatureBase Path
App Config / Home Screen/api/v1/customer/app-screen/*
Products/api/v1/customer/items
Categories/api/v1/customer/categories
Cart/api/v1/customer/cart
Checkout / Place Order/api/v1/customer/checkout/*
Coupons/api/v1/customer/coupons
Orders/api/v1/customer/orders
Wallet/api/v1/customer/wallet/*
Loyalty Points/api/v1/customer/loyalty-points/*
Notifications/api/v1/customer/notifications
Chat/api/v1/customer/chats
Profile/api/v1/customer/profile
Addresses/api/v1/customer/addresses
Wishlist/api/v1/customer/wishlist
Reviews/api/v1/customer/reviews
Refund Requests/api/v1/customer/refund-requests
Brands (Popular)/api/v1/customer/brands/popular
Labels/api/v1/customer/labels
Common Conditions/api/v1/customer/common-conditions
Flash Sales/api/v1/customer/flash-sales
Special Offers/api/v1/customer/app-screen/special-offer
FAQ & Categories/api/v1/customer/faqs, .../faqs/categories
Item Content/api/v1/customer/app-screen/item-content

Troubleshooting

Build Runner Conflicts

dart run build_runner clean
dart run build_runner build --delete-conflicting-outputs

Gradle Build Failures (Android)

CocoaPods Issues (iOS)

cd ios
pod deintegrate
pod install --repo-update
cd ..
flutter build ios

Google Maps Not Showing

Push Notifications Not Received

Network / API Errors

Localization Not Updating

flutter gen-l10n
flutter clean
flutter pub get

facebook_auth Login Fails on iOS

General Reset

flutter clean
flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter gen-l10n
flutter run

FAQ & Environment-Specific Issues

Common environment-specific hurdles when setting up and building the Flutter app.

API requests time out or fail to connect

Gradle / Android build fails on a fresh machine

CocoaPods / iOS build fails

cd ios
pod repo update
pod install --repo-update
cd ..
flutter build ios

On Apple Silicon, if pods fail to install, retry under Rosetta: arch -x86_64 pod install.

build_runner or code generation errors

dart run build_runner clean
dart run build_runner build --delete-conflicting-outputs
flutter gen-l10n

Firebase / Google Maps features do nothing at runtime

Customization

🎨
For the complete white-label walkthrough β€” app rename, bundle ID, icon, splash, colors, onboarding content, and translations for both apps plus the web platform β€” see the dedicated Branding & Customization Guide. The essentials for this app are summarized below.

App Theme & Colors

The global theme is defined in lib/config/theme/. Update color seeds, typography, and component themes there. All UI components reference the theme via Flutter's Theme.of(context) β€” changes propagate automatically.

App Icon

# Replace the source image:
# android: android/app/src/main/res/mipmap-*/ic_launcher.png
# ios: ios/Runner/Assets.xcassets/AppIcon.appiconset/

# Or use flutter_launcher_icons package:
dart pub global activate flutter_launcher_icons
flutter_launcher_icons

Splash Screen

Update the native splash assets:

Adding a New Feature

  1. Create the feature folder under lib/features/<feature_name>/ with data/, domain/, and presentation/ sub-directories.
  2. Define Freezed models in data/model/ and run dart run build_runner build.
  3. Create the BLoC/Cubit in presentation/bloc/ and register it with GetIt using the @injectable annotation.
  4. Add routes in lib/config/route/route_config.dart.

Updating Lottie Animations

Replace or add .json files in assets/json/. Reference them via the generated Assets class in lib/config/util/assets.gen.dart (regenerated automatically by flutter_gen on next build).


Need help? Reach us via the item’s Support tab on CodeCanyon or dayonesoft.com or visit our website for support.