Skip to main content
Version: 1.0.0

Routes / Navigation (Android)

Map of deep links, route guards, and navigation graphs for the ARShades Android app and its optional Instant experience.

1) Domains & Link Schemes​

  • Android App Links (installed app & Instant)

    • https://www.webvto.it/?c=<catalogueId>&m=<variantId>

  • Digital Asset Links

    • Domain verification via assetlinks.json hosted on the verified domains (e.g., webvto.it, brand domains).
  • c → catalogueId (the catalog containing the variant)
  • m → variantId (the exact SKU/variant to open on Try-On)

Behavior

  • No app installed → opens Instant experience (if enabled), shows the specified variant.
  • App installed → opens full app, hydrates data for c/m from Firebase, then navigates to Try-On.

When the app launches without a deep link:

  1. Splash → initialization.
  2. Load AppConfig from Firebase → fetch the catalogue IDs allowed for this app build.
  3. Brands → display only the brands/catalogues listed in AppConfig for this app.
  4. On brand selection →
    • Fetch products for that brand’s catalogue.
    • Open Try-On with the initial 30 products preloaded into the carousel (pagination continues as user scrolls).

This ensures each white-label/build shows only the intended brands/catalogues.

When launched via App Link:

  1. Parse c (catalogueId) and m (variantId).
  2. Hydrate from Firebase: catalogue → variant → parent product → sibling variants → carousel (30).
  3. If c is NOT present in AppConfig:
    • Persist c locally (Realm Kotlin / SharedPreferences) as a “learned/seen” catalogue.
    • From the next app session onward, the Brands page will also include this catalogue so users can reach it without a link.
  4. Navigate to Try-On focused on m.

5) Pre-Main Flow (Full App)​

  • Splash
  • PP/T&C Gate (if not yet accepted)
  • Brands (driven by AppConfig + any locally persisted catalogues)

If a valid App Link is present, Brands can be bypassed; brand context is inferred from c.

6) Main Navigation (Drawer / Side Menu)​

  • Try-On (default after brand selection / deep link)
  • 3D Viewer
  • Brands
  • Catalogue
  • Favorites
  • Facial Metrics
  • Choose Skin
  • Notifications
  • Legal
  • Contacts

7) Instant Experience Routing (optional)​

Entry: App Link with c/m.
Flow: Splash → minimal fetch for c + m → Try-On (single-product context) → optional Install app CTA for full catalogue experience.

8) Full App Navigation Graph (Mermaid)​

flowchart TD
  A[Launch] --> B{App Link present?}
  B -- No --> C[Load AppConfig]
  C --> D[Brands (AppConfig + Local-learned)]
  D --> E[Select Brand]
  E --> F[Try-On (carousel 30)]

  B -- Yes --> G[Parse c/m]
  G --> H[Hydrate from Firebase\n(catalogue, variant, product, siblings, carousel 30)]
  H --> I{c in AppConfig?}
  I -- Yes --> J[Try-On]
  I -- No --> K[Persist c locally (Realm/Prefs)\n(add to Brands next sessions)]
  K --> J[Try-On]

  J <-- Drawer --> L[3D Viewer]
  J <-- Drawer --> M[Catalogue]
  J <-- Drawer --> N[Favorites]
  J <-- Drawer --> O[Facial Metrics]
  J <-- Drawer --> P[Choose Skin]
  J <-- Drawer --> Q[Notifications]
  J <-- Drawer --> R[Legal]
  J <-- Drawer --> S[Contacts]

9) Notification Routing (Full App)​

  • Foreground:

    • Notification is displayed (heads-up or banner).
    • On tap, route to the product/variant context defined in the payload (with optional assets from Firebase Storage).

  • Background / Terminated:

    • User taps notification.
    • App launches → Splash → (PP/T&C check) → hydrate context from payload → navigate to Try-On or specified route.

10) Route Guards & Fallbacks​

  • PP/T&C Guard → Must be accepted before main routes are accessible.
  • Device Capability Guard → If ARCore not available or face/object tracking unsupported, show Not Supported view.
  • Invalid / Missing Link Params:
    • Missing m: fallback to Brands → user selects brand → Try-On.
    • Invalid c or m: log error, fallback to Brands (AppConfig + locally learned).
  • Orientation Rules → Standard Android orientation handling; Try-On prefers portrait unless a device/camera capability dictates otherwise.

11) State & Persistence​

  • Local persistence (Realm Kotlin / SharedPreferences):

    • Persists learned catalogues from App Links not listed in AppConfig so they appear in Brands in future sessions.
    • Stores notification data and other UX state.

  • AppConfig (Firebase):

    • Defines official catalogues visible in the app by default.
    • Acts as the baseline for the Brands list.

  • Pagination:

    • Product carousel loads in batches of 30 for performance.

  • Cold vs Warm Start:

    • Cold start: hydrate state from link → Try-On.
    • Warm start: restore last visited route, refresh session, renew tokens.

  • Instant ↔ Installed App:

    • Context is preserved via link parameters and cloud state; after installation, the full app continues seamlessly on the same product/variant.