[georgeweiler]

Explanation

Mobile needs KYC analytics (schema: Consensys/segment-schema#785) in two shapes. The controller calls an optional trackKycAnalytics constructor callback after the state write (a crash can lose a call but never duplicates one). Clients that do not track omit the option. Nothing is added to KycControllerEvents.

trackKycAnalytics.verificationOutcome, payload { status, kycStatus, providerFlowStatus, vendor }: one per SumSub launch attempt in #launchSumsubFlow (submitted, abandoned, failed), even if it repeats the previous outcome. The two failed returns that never write state (session id changed while the SDK was open) also call it.

trackKycAnalytics.statusChanged, payload { previousKycStatus?, kycStatus, providerFlowStatus, vendor }: called after any session-replacing write that changes the analytics KYC status (new to pending, pending to approved, rejected, retry, ...). A submitted launch also calls this (new to pending). previousKycStatus is absent when the session was just created.

• The analytics KYC status is the session's finalStatus (new, pending, approved, rejected, retry), or none when there is no session or the value is unknown, exposed as getKycAnalyticsStatus. It deliberately ignores the relay kycStatus and the provider flow, unlike RampsController's VBA KYC resolution, which I did not change.
• Loading a session into an empty slot (startSession lookup fill, e.g. after a reinstall) calls neither callback, so an already-approved session is not reported as a new decision.
• started (SumSub webview opened) and retry_started (user pressed retry) are UI moments the controller never sees, so mobile fires those itself.
• Payloads carry no session id, email, disclaimer or token data.

Mobile passes the callbacks from kycControllerInit (MetaMask/metamask-mobile#38160). That PR still subscribes to the previous messenger events and needs to pass trackKycAnalytics instead.

References

• Analytics schema: Consensys/segment-schema#785

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

---

Note

Low Risk
Additive optional constructor callbacks with try/catch isolation; core KYC state machine behavior is covered by extensive tests and unchanged when trackers are omitted.

Overview
Adds optional KYC analytics hooks on KycController via a new trackKycAnalytics constructor option (no new messenger events). Hosts pass verificationOutcome and statusChanged callbacks that run after the relevant state write.

verificationOutcome fires once per SumSub launch attempt (submitted, abandoned, failed), including repeats and failures that do not mutate state. statusChanged fires when the analytics KYC status (derived from session finalStatus via getKycAnalyticsStatus, with none for missing/unknown) actually changes—e.g. session creation, submit → pending, poll/refetch → approved/rejected/retry. Restoring a session into empty state after reinstall uses a plain state update and does not invoke either callback.

Payloads include kycStatus, providerFlowStatus, and vendor only (no session id, email, or tokens). Throwing callbacks are swallowed so KYC outcomes and polling behavior stay unchanged. The package exports analytics.ts types, KYC_ANALYTICS_STATUSES, and getKycAnalyticsStatus.

^{Reviewed by Cursor Bugbot for commit 785d248. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jiexi]

My main concern right now is that these changes need to be very clearly Analytics namespaced otherwise they make it difficult to discern from the business logic types and methods

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fe01319. Configure here.}