Onboarding v2: Mixpanel events

The Mixpanel event tracking spec for the onboarding-v2 flow. Product calls this flow "Onboarding v1.5"; the code lives at cur8-mob/src/screens/onboarding-v2/. They are the same thing.

This doc covers Mixpanel events and people-profile traits only. Customer.io, Avo, Google Ads, session replay and compliance are out of scope here. The older cur8-mob/ANALYTICS_ARCHITECTURE.md (v3.2) is kept as a reference for the wider design, including the deferred navigation-listener and abandonment-tracking work.

onboarding-v2 currently ships with no analytics calls. This doc is the spec for what to add, screen by screen. The screen inventory is taken from cur8-mob/src/navigation/onboardingV2.tsx (the OnboardingV2StackParamList), which is the source of truth.

1. What the events answer

Note: profile traits (section 5) attach to every event automatically as Mixpanel "User properties". Any funnel or report can be sliced by them without the event carrying the value itself.

2. How events are wired

Every event goes through the shared @ifgengineering/client-analytics package, the same path every other cur8-mob event already uses. Screens never call mixpanel.track directly.

A screen gets a fire function from the useAnalytics hook and invokes it. The hook returns a promise, so callers await it. Wrap the call so a failure never blocks the user, matching existing screens such as home.tsx.

There are two shapes.

2.1 Page views

Page views reuse the generic pageView event key. Add the event-name string to the cur8PageViewEvents union in packages/client-analytics/src/types.ts, then fire it. The pageView handler attaches app and channel for you, so the call site only passes eventName.

const firePageView = useAnalytics("pageView");
// fire on screen focus:
(await firePageView)({ eventName: "cur8:onboardingPersonalInfo_pageViewed" });

For the three paginated routes (MandatoryQuestion, AccreditationQuestionnaire, QuizQuestion) one route instance serves every question, so the screen does not re-focus per question. Fire those _pageViewed events from a useEffect([questionIndex]), not from focus.

2.2 Action and outcome events

Action and outcome events get their own entry:

1. In types.ts, add the key to the Event union and a <Name>Props interface.
2. In packages/client-analytics/src/index.ts, add a case that calls track("cur8:onboarding…_…", { ...args, app: APP_NAME }).
3. Fire it from the screen:

const fireCertificationSelected = useAnalytics("onboardingCertificationSelected");
(await fireCertificationSelected)({ certification: "HIGH_NET_WORTH" });

People-profile traits are set inside the same case via mixpanel.people?.set, the way the nps_set case already does it (note the optional chaining, the codebase uses it). The fire function is the only thing a screen imports.

track also forwards every event to Customer.io. That fan-out is unconditional in the current package code. It is out of scope for this doc, but be aware new onboarding events reach Customer.io too.

3. Naming

• Events: cur8:onboarding<Screen>_<action>. cur8: is the team namespace, <Screen> is PascalCase, <action> is a past-tense lowerCamelCase verb (_pageViewed, _completed, _passed, _failed, _documentUploaded, _answered). Module-level events drop the screen: cur8:onboarding_completed.
• This matches the existing onboarding events already in Mixpanel (cur8:onboardingQuiz_pageViewed, cur8:onboardingBasicInfoPersonal_pageViewed).
• Event properties: snake_case. Booleans prefix is_ / has_. Counts suffix _count. Timestamps suffix _at (ISO 8601). Banded values suffix _band.

Note: cur8:onboardingQuiz_pageViewed already exists as a v1 event. This spec assumes v2 replaces v1, so it reuses the clean names. If v1 and v2 ever run side by side, reusing a name merges the two in Mixpanel. Namespace the v2 events in that case.

4. Event taxonomy

Re-derived from the registered routes in onboardingV2.tsx. Every screen fires one _pageViewed on focus. Each module fires one _completed on its final screen, carrying that module's captured outputs as properties. No raw PII goes on any event (age_band, not date of birth; source_of_funds option keys, not free text).

_pageViewed events tell you where a user stalled, not why. Within the lean event set there is no "saw the screen but did not act" signal except where an explicit action event exists (_answered, _certificationSelected).

4.1 Entry and Mandatory Questionnaire

email_preference: cur8_capital / cur8_and_ifg / none. attribution_source: google / instagram / tiktok / youtube / friend_family / podcast / ifg / other.

Note: the questionnaire is server-driven (GET /investor/mandatory-questionnaire), so question_id and answer_id are server identifiers. The three questions are investment goals, portfolio size and investment timeframe, but the mapping from question_id to which one is resolved analysis-side from the stable IDs. The question count is not guaranteed to be three.

4.2 Basic Info

Seven screens: one explainer, six single-purpose data screens.

age_band: 18-24 / 25-34 / 35-44 / 45-54 / 55-64 / 65+. Derived from the date of birth held in OnboardingV2Context (captured back on PersonalInfo); the raw DOB never leaves the client. source_of_funds is an array of selected option keys. occupation is the option key, not the display label. is_address_autocompleted is true when the user picked a Google Places suggestion on the address screen rather than typing the address by hand; the flag is carried through OnboardingV2Context from ResidentialInfo.

4.3 Accreditation

Code folder: eligibility/. The flow branches on the chosen certification: self-certified and high-net-worth users continue through the questionnaire and declaration. US residents are offered a US-accredited option instead. Users who pick "none apply" (NONE_APPLY) route to the not-eligible screen.

certification: SELF_CERTIFIED / HIGH_NET_WORTH / US_ACCREDITED / NONE_APPLY. NONE_APPLY appears only on _certificationSelected; those users route to the not-eligible screen and never reach _completed. profile_type: SELF_CERTIFIED / HIGH_NET_WORTH / US_ACCREDITED. yes_answer_count is how many questionnaire questions were answered Yes (the questionnaire content itself is not captured).

4.4 Quiz

FCA appropriateness check. On submit the quiz navigates to a dedicated QuizResult screen, which receives failed and an optional blockedUntil and shows a live countdown when the user is rate-limited.

blocked_until is the ISO 8601 rate-limit timestamp, or omitted when the user is not rate-limited (the quiz API returns { failed, blockedUntil? }). attempt_band is first_fail / second_or_third_fail / fourth_plus_fail, derived client-side from blocked_until against the server's fixed block ladder (fail 1 = no block, fails 2 to 3 = 1-day block, fails 4+ = 7-day block). It separates first-time failures from hard-stuck repeat users.

Note: the quiz API returns only pass/fail and the rate-limit window, not a score, and the client cannot grade the answers. attempt_band is the closest available proxy. The clean fix is for the backend to return attemptCount on the quiz response (it already computes it); track that as a follow-up.

4.5 Verification (KYC)

The verification flow branches on the user's identity status: most users go straight to document upload, some are routed to an identity scan, blacklisted users hit the blocked screen.

doc_type: proof_of_address / source_of_funds. identity_status: needs_scan / grey_list. The client-side KYC branch hint; it is never sent to the backend, so this event is the only place the grey-list versus standard-KYC split is observable. failure_reason: file_too_large / unsupported_format / network_error / server_error / other. Map the upload pipeline's real error to this closed set at emission; never pass a raw exception string.

4.6 Completion and cross-flow

5. People-profile traits

User state lives on the Mixpanel people-profile, not on events. Each trait is set with mixpanel.people?.set inside the event handler named below, alongside the track call.

Note: onboarding-v2 runs post-signup. The user is already identified at signup (email-keyed, via safeMixpanelIdentify in the analytics package). onboarding-v2 fires no identify, alias or reset calls. Mixpanel's mobile SDK auto-properties ($os, $app_version_string, $device, and so on) are free; do not duplicate them.

6. Headline funnel

Slice by profile properties country, attribution_source, investor_certification, email_preference. Per-screen _pageViewed events give the within-module drop-off.

Caution: the funnel hides quiz failure. A user who fails the quiz and never passes simply does not reach step 5, with no signal distinguishing a failed quiz from an abandoned explainer. Track quiz fail rate separately as cur8:onboardingQuiz_failed count against cur8:onboardingQuiz_passed. The restricted-investor branch (step 4) is similar: UNACCREDITED users who stop at the ineligible screen need cur8:onboardingAccreditationIneligible_pageViewed, not the funnel, to be counted.

7. Not covered here

Deliberately cut from the v3.2 architecture doc for this simplified spec:

• Abandonment events (_screenAbandoned, _abandoned, _attemptAbandoned, _docAbandoned) and the navigation-state listener / onboarding_session_id subsystem they need. Drop-off is read from where users stop in the _pageViewed funnel.
• active_*_ms timing properties. Mixpanel derives time-between-steps from event timestamps; foreground-pause timing has no precedent in the codebase.
• Per-event metadata ($insert_id, experiment_variant, flag_resolution) and the experiment_exposed event.
• Customer.io, Avo, Google Ads, session replay, PII rules and compliance.

See cur8-mob/ANALYTICS_ARCHITECTURE.md for the fuller v3.2 design if any of the above is revived.