H5 Hot Update

Alphio's mobile app embeds an H5 (web) layer whose UI updates can ship without an App Store / Play Store review.

---

1. What the H5 layer is

The native iOS / Android apps are a two-part stack:

• Native shell (Flutter / platform code) — handles plumbing: push tokens, biometric auth, deep links, IAP, hardware integrations.
• H5 layer (apps/h5 — the same Vite + React codebase that serves m.alphio.ai) — renders most user-facing screens inside an embedded web view.

When you tap a tab or open a screen, you're usually looking at the H5 layer rendered inside the native shell. This is invisible to you — it looks and feels native, with native navigation and gestures wrapping it.

---

2. Why hot updates

Pushing updates through the App Store / Play Store has two costs:

• Review delay — typically hours to days.
• User adoption delay — users update on their own schedule; some never update.

By keeping business logic in the H5 layer, Alphio can:

• Ship a bug fix in hours, not days.
• Roll out a feature flag change to everyone immediately.
• Recover from a bad release by rolling back the H5 bundle without forcing a native uninstall / reinstall.

The native shell only needs a store update when something truly native changes — new SDK, new permission, new push integration.

---

3. When updates apply

The update flow runs on every app launch:

1. App opens — native shell fetches the H5 manifest (/v1/dashboard/h5/manifest).
2. Compare versions — if a newer H5 bundle is available, the shell downloads it in the background.
3. Stage — the new bundle is saved locally but not yet active. The current session keeps running on the old bundle.
4. Activate on next launch — the next time you cold-start the app, the new bundle becomes active.

In practice, this means a new H5 version takes effect within ~5 minutes of an app launch — long enough to download, applied on the next launch.

---

4. User experience

Hot updates are designed to be invisible:

• No restart prompt — the app does not interrupt you to apply an update.
• No "downloading update" screen — the bundle fetch happens in the background.
• No data loss — your session state is preserved across the implicit reload.

The only visible signal is that, after relaunching the app, you may see new UI or fixed behavior. There's no notification step.

---

5. Native vs H5 features

Layer	What it owns
Native shell	Push notification registration, biometric auth, deep-link routing, IAP, app-level permissions, the embedded web view itself
H5 layer	All business logic: chat, watchlist, Signals products, trade rails, account pages, settings, alert preferences

A rule of thumb: if you can do it on m.alphio.ai on a phone browser, the same code does it in the native app via the H5 layer. If it requires OS-level integration (Face ID, push permission flow, IAP receipt validation), the native shell handles it and exposes a bridge for H5 to call.

---

6. Force-refresh

If you want to immediately pick up the latest H5 bundle (rather than waiting for the next cold start):

1. Fully kill the app (swipe it away from the recent-apps tray on iOS / Android — not just background it).
2. Reopen it.

On relaunch the manifest check runs again, any staged bundle is activated, and you're on the latest version.

If after a force-refresh you still don't see an expected change, the H5 rollout may not have reached your account yet (gradual rollout via feature flag). See Entitlements.

---