Onboarding

New users complete a mandatory setup flow before reaching the home screen.

Who Goes Through This

Any user with status: onboarding. All new accounts start in this state. A user who has already completed onboarding skips this flow and lands directly on the home screen on every subsequent launch.

Subscription Restore at Onboarding Start

Before the first onboarding step is shown, the app silently calls RevenueCat's restorePurchases. This detects whether the device's store account has an active subscription that belongs to a different 95octane account (Signal 2 of the account merge detection flow).

No subscription found — onboarding continues normally. The new account starts as free.
Subscription found on the same account — onboarding continues. The account will gain subscriber access once onboarding completes.
Subscription found on a different account — the merge prompt is shown before onboarding steps begin. See Account Merge Detection.
User confirms merge — the current onboarding account is the redundant one and is discarded. The user is signed into the surviving (older) account, which is already active. Onboarding does not continue.
User declines merge — the subscription is transferred to the current account via RevenueCat. Onboarding continues and the new account will have subscriber access on completion.

Steps

Profile review — The app shows the display name and photo supplied by the sign-in provider. These are read-only — provider-supplied fields cannot be edited in 95octane. If the provider did not supply a photo, a default avatar is generated from the user's initials and the user can optionally set a custom photo. If the provider did not supply a name, the user can enter one (5–100 characters); if left blank, the name defaults to "Rider". Custom name and photo can also be changed later from profile settings.
Permissions — The app requests the following device permissions:
Precise location — enables automatic city detection and is required later to start a ride.
Bluetooth — required for intercom during rides.
Push notifications — required for buddy requests, ride updates, ban appeals, group alerts, and other notifications. All permissions can be granted or denied individually. Features that depend on a denied permission will prompt for it again at the relevant point in the app.
Recovery phone (optional) — The user can add a phone number verified via OTP. This links Mobile/OTP as an additional auth provider and enables account recovery if the user ever loses access to Google or Apple. The step can be skipped — the user can add a recovery phone later from profile settings. If the user completes this step, Mobile/OTP is linked immediately; it is available for account recovery even if the user abandons onboarding before finishing. See Add Authentication Provider.

Merge detection via phone number (Signal 1): After the OTP is successfully verified, the app checks whether the phone number is already registered on an existing 95octane account. If it is, a merge prompt is shown before the user advances to the next onboarding step. See Account Merge Detection. - User confirms merge — the onboarding account is the redundant one and is discarded. The user is signed into the surviving (older) account. If that account is active, onboarding does not continue. If it is itself in onboarding, the user resumes that account's incomplete onboarding flow. - User declines merge — both accounts remain separate. Onboarding continues on the current account with the phone number linked. 4. City confirmation — The app detects the user's city using GPS first, then IP address as a fallback (used in rare cases such as VPN usage or a geolocation service outage). The user sees the detected city and either confirms it or selects a different one from a searchable list of cities in supported countries (India only to start). City selection is mandatory and cannot be left blank. Unlike a post-onboarding city change, GPS confirmation is not required here — IP detection is sufficient to complete this step. 5. Done — Account status changes to active. The user lands on the home screen with full feature access for their account type.

City is stored as a three-part identifier: country (ISO 3166-1 alpha-2, e.g. IN), state (ISO 3166-2, e.g. IN-MH), and city name (e.g. Pune). This combination uniquely identifies the city.

Rules

Onboarding is mandatory. No app features are accessible until all steps are complete.

Known edge case: A user who completes the recovery phone step during onboarding but then abandons the flow has Mobile/OTP linked on an onboarding-status account. If they later use /recover to replace a sign-in provider, recovery succeeds — but the app routes them back into the incomplete onboarding flow, which they must complete before accessing any features. This is the correct behavior; it is noted here because the sequence (recovery before onboarding completion) is non-obvious.

A user in onboarding cannot be banned. Bans require evidence of platform misuse, which can only occur after onboarding is complete.
Accounts that never complete onboarding remain in status: onboarding indefinitely — there is no automatic expiry or cleanup. Operators can act on such accounts on a case-by-case basis.
Each step is committed server-side when completed before the user advances to the next. If the app is closed mid-onboarding, the user resumes from the next incomplete step — completed steps are not repeated and their effects persist.

Known edge case: If the same account advances onboarding steps simultaneously on two devices, the outcome is undefined — the last write to reach the server wins. In practice this is rare, as onboarding is a one-time linear flow.

City is required. The user cannot proceed without selecting or confirming a city.
Completing onboarding transitions the account from onboarding to active. This transition is also used for any future mandatory setup requirements.

What Happens Next

Account status becomes active. The user lands on the home screen as a free user. All features available to their account type are immediately accessible. Profile name and photo can be updated at any time from settings.

Failure Cases

Situation	What the user sees	What the user does
Photo upload failed	Error shown on profile review step	Retry the upload or skip — onboarding continues with the default avatar
OTP not received or expired (recovery phone step)	Error shown on recovery phone step	Retry the OTP or skip the step — onboarding continues without Mobile/OTP linked
GPS unavailable or times out	City is not auto-detected; IP used as fallback	Select city manually from a searchable list of supported cities
Location permission denied	City is not auto-detected; IP used as fallback	Select city manually from a searchable list of supported cities
Both GPS and IP detection fail	No city auto-detected	Select city manually from a searchable list of supported cities — manual selection is always available during onboarding
GPS or IP detects an unsupported country	Notice shown: "95octane is not yet available in your country"	Select city manually from the supported countries list — the app is distributed only in supported countries, but a user from a supported country may be physically abroad
App closed mid-onboarding	App restarts	Onboarding resumes from the last incomplete step
Resumed on a different device	Onboarding screen opens	Resumes from the last incomplete step

If location permission is denied during onboarding, the user can still complete setup and use the app. However, starting a ride requires precise location permission. The app will prompt for that permission at ride start time.

Status: partially-live. A 5-slide marketing carousel and a permission request screen at splash time are built. The functional onboarding steps are not yet implemented: profile review (step 1), recovery phone / OTP (step 3), city confirmation with GPS/IP detection (step 4), the RevenueCat restorePurchases check at start, and the backend call to set status: active on completion.