Skip to main content
Version: 1.0.0

Routes / Navigation

Map of deep links, route guards, and navigation graphs for the ARShades iOS app and its App Clip.

1) Domains & Link Schemes​

  • Universal Links (full app & App Clip)
    • https://www.webvto.it/?c=<catalogueId>&m=<variantId>
  • Associated Domains
    • applinks:safilo.arshades.it
    • applinks:spaarkly.page.link (Firebase Dynamic Links)
    • appclips:safilo.arshades.it
  • c → catalogueId (the catalog containing the variant)
  • m → variantId (the exact SKU/variant to open on Try-On)

Behavior

  • No app installed → opens App Clip, 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 deep 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 to Realm 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 deep 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 Realm-persisted catalogues)

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

6) Main Navigation (Side Menu)​

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

7) App Clip Routing​

Entry: Universal link with c/m.
Flow: Splash → minimal fetch for c + m → Try-On (single-product context) → optional “Open in App”.

8) Full App Navigation Graph (Mermaid)​

flowchart TD
  A[Launch] --> B{Deep link present?}
  B -- No --> C[Load AppConfig]
  C --> D[Brands (AppConfig + Realm-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 to Realm\n(add to Brands next sessions)]
  K --> J[Try-On]

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

9) Notification Routing (Full App)​

  • Foreground:

    • Notification is displayed as a banner.
    • On tap, the user is routed 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 AR face tracking is unsupported, show Not Supported view.
  • Invalid / Missing Deep-Link Params →
    • Missing m: fallback to Brands → user selects brand → Try-On.
    • Invalid c or m: log error, fallback to Brands (AppConfig + Realm-learned).
  • Orientation Rules → Special handling for iPads with landscape cameras; others use portrait/upside-down.

11) State & Persistence​

  • Realm (full app only)

    • Persists learned catalogues from deep 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 deep link → Try-On.
    • Warm start: restore last visited route, refresh session, renew tokens.

  • App Clip ↔ Full App

    • Shared state via App Groups (e.g., consent flags, last viewed variant) for continuity.