@unifold/connect-react 0.1.77 → 0.1.79

package/README.md

@@ -373,7 +373,13 @@ Pass `onEvent` to `beginDeposit` / `beginWithdraw` to receive lifecycle events.
 
 ### 2. Telemetry (funnel analytics)
 
-Independently, the SDK forwards funnel events (`widget_opened`, `screen_viewed`, `payment_method_selected`, `token_selected`, `wallet_selected`, `provider_selected`, `payment_method_type_selected`, `verification_started`, `verification_submitted`, `verification_completed`, `verification_failed` (funnel only — only the failure reaches `onEvent`), `account_connection_started`, `account_connected`, `account_connection_failed`, `wallet_connection_started`, `wallet_connected`, `wallet_connection_failed`, `flow_started`, `flow_completed`, `flow_failed`, `back_clicked`, `widget_closed`) to the Unifold backend. Each carries `session_id` (`asess_…`) and, once deposit-addresses returns, the internal `user_id` — so drop-off funnels can be grouped per journey and per user. Early events in a session (before addresses resolve) may omit `user_id`. Abandonment is derived from the funnel (`widget_opened` − `flow_completed`).
+Independently, the SDK forwards funnel events (`widget_opened`, `screen_viewed`, `payment_method_selected`, `token_selected`, `wallet_selected`, `provider_selected`, `payment_method_type_selected`, `verification_started`, `verification_submitted`, `verification_completed`, `verification_failed` (funnel only — only the failure reaches `onEvent`), `account_connection_started`, `account_connected`, `account_connection_failed`, `wallet_connection_started`, `wallet_connected`, `wallet_connection_failed`, `flow_started`, `flow_completed`, `flow_failed`, `back_clicked`, `widget_closed`) to the Unifold backend. Each carries `session_id` (`asess_…`) and the internal `user_id` — so drop-off funnels can be grouped per journey and per user. Abandonment is derived from the funnel (`widget_opened` − `flow_completed`).
+
+The internal id comes from the API — deposit addresses, the execution query, a payment intent — so it lands on the journey's events from the moment the first of those responses names the user, whichever screen the user is on. Nothing is needed on your side beyond the `externalUserId` you already pass. The events that fire before that response, `widget_opened` and possibly the first `screen_viewed`, carry `session_id` and no `user_id`; join them to the rest of the journey on `session_id`, which every event in it shares. A journey never carries a *different* user's id: each one starts from a clean slate rather than inheriting what the last flow resolved.
+
+The terminal flow events carry the id of the record they produced: `flow_completed` and `flow_failed` on a deposit or withdrawal carry `execution_id` (`exec_…`, the direct execution the poll resolved), and a checkout's `flow_completed` carries `payment_intent_id` (`pi_…`). They are the only high-cardinality properties in the funnel — join keys back to the execution or the intent, not breakdown dimensions. `execution_id` is absent when a flow completes without one (a provider reporting success before any execution row exists).
+
+`flow_started` can't carry `execution_id`, because at that point there is no execution: one is created when funds land on the deposit wallet, which is after the user has paid, sent, or been handed off to a provider. It carries `deposit_wallet_id` (`wallet_…`) instead — the wallet the flow is funding, and the same id the execution carries when it appears. That's what joins a journey that started and never completed to whatever did (or didn't) follow. A deposit wallet is reused across a user's deposits to the same destination, so pair it with the journey's time window rather than treating it as unique per execution.
 
 Events that name an asset carry `currency` and `network` next to the raw `token` and `chain`. Those are the slugs the API serves on every token and chain — lowercase, with non-alphanumerics collapsed to `_` (`USDC.e` → `usdc_e`, `USDC (Perp)` → `usdc_perp`, `Base Sepolia` → `base_sepolia`) — and they are the same identifiers the payment-intents API takes as `destination_currency` / `destination_network`. Group funnels on those; read `token`/`chain` when you want the symbol as displayed or the exact chain id. A currency is not unique per network (Polygon carries both `usdc` and `usdc_e`, HyperCore both `usdc` and `usdc_perp`), so the pair is the key, never the currency alone.