Onboarding v2 — Mixpanel events

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

This document covers Mixpanel events and people-profile traits only. Customer.io, Avo, Google Ads, session replay and compliance are out of scope here. The older 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 document is the spec for what to add, screen by screen.

# 1What the events answer

# 2How 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.

# 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.

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

# 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 nps_set already does it. The fire function is the only thing a screen imports.

# 3Naming

• Events: cur8:onboarding<Module>_<action>. cur8: is the team namespace, <Module> is PascalCase, <action> is a past-tense lowerCamelCase verb (_pageViewed, _completed, _passed, _failed, _documentUploaded).
• 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.
• Paginated screens (one route reused per question) keep one event name and a question_index property. Do not synthesise a name per question.

# 4Event taxonomy

Re-derived from the shipped screens. 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).

# 4.1 Entry & Mandatory Questionnaire

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

# 4.2 Basic Info

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

# 4.3 Accreditation

Code folder: eligibility/. Four screens. UNACCREDITED users skip the questionnaire.

certification: SELF_CERTIFIED / HIGH_NET_WORTH / UNACCREDITED.

# 4.4 Quiz

FCA appropriateness check. There are no cooldown or "blocked" screens in v2; a failed or rate-limited attempt shows a toast on the same screen.

# 4.5 Verification (KYC)

Two document types in v2: proof of address and source of funds. No ID-document scan.

doc_type: proof_of_address / source_of_funds.
file_format: pdf / jpg / png / heic / other.

# 4.6 Completion & cross-flow

# 5People-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.

# 6Headline funnel

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

# 7Not 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.