@wireai/activation 0.12.0 → 0.12.2

package/AGENTS.md

@@ -31,16 +31,14 @@ Use it whenever someone wants "AI / dynamic / personalized onboarding" in a Reac
 Everything an integration needs lives on the ROOT import (`@wireai/activation`). The other
 subpaths are optional secondary feature modules; import one only if you use it.
 
-- `@wireai/activation` (root): `WireOnboarding`, the helpers/types below, and the app-event/analytics reporters.
+- `@wireai/activation` (root): `WireOnboarding`, the helpers/types below, and the device-only event reporters (`reportClientEvent`, `makeSessionId`, `WIRE_ONBOARDING_EVENTS`, see "App events" below).
+- `@wireai/activation/analytics`: the analytics FACADE and its queue: `createAnalytics`, `useAnalytics`, `createScreenTracker`, `reportAppEvent`, `createEventQueue`, `clearUserContext`. These are NOT root exports; importing them from the root does not compile.
 - `@wireai/activation/coachmarks`: in-app coachmark tour (`CoachmarkProvider`, `useCoachmarkTour`).
 - `@wireai/activation/showcase`: post-onboarding feature showcase (`FeatureShowcase`).
 - `@wireai/activation/reviews`: store-review gating (`ReviewGate`, `ReviewModal`, `useReviewGate`, `fetchReviewDecision`).
 - `@wireai/activation/questionnaire`: in-app questionnaire gating (`QuestionnaireGate`).
 - `@wireai/activation/metro`: the `withWireOnboarding` Metro helper (see step 3).
 
-There is no `analytics` subpath: the app-event / analytics API is exported from the ROOT
-(see "App events / analytics" below).
-
 ## Public API (import from `@wireai/activation`)
 
 - `WireOnboarding`: the component (props below).
@@ -51,7 +49,9 @@ There is no `analytics` subpath: the app-event / analytics API is exported from
 - `mergeTheme`, `defaultOnboardingTheme`, `OnboardingThemeProvider`, `useOnboardingTheme`.
 - `defaultIllustrations`: dependency-free fallback art; spread your own over it.
 - `createRevenueCatBridge({ analytics, entitlementId })`: the RevenueCat purchase funnel (see "RevenueCat" below).
-- `activationJoinContext(deviceKey)`: builds the `userContext` value that joins an onboarding session to the app's later events. Read the RevenueCat section before you use it.
+- `activationJoinContext(deviceKey)`: builds the `userContext` value that joins an onboarding session to the app's later events. Every `<WireOnboarding>` needs it (see step 7).
+- `resolveAutoDeviceKey({ appId, storage })`: the kit's own persisted per-install `device_key`, for a host that owns none.
+- `useLifecycleEvents(config, options)`: the app-root lifecycle hook (see step 8). `useSessionStart` / `reportSessionStart` are the counter-owning alternatives.
 - Types: `OnboardingTheme`, `OnboardingResult`, `OnboardingEvent`, `WireOnboardingConfig`, `WireOnboardingProps`, `StepValidator`, `OnboardingCopy`, `IllustrationRegistry`.
 
 ## `<WireOnboarding>` props
@@ -90,9 +90,10 @@ There is no `analytics` subpath: the app-event / analytics API is exported from
 | `metadata` | `Record<string, unknown>` | no | Merged into every A2A request (e.g. install attribution). The kit reserves `sessionId` + `supportedComponents`; do not override them. |
 | `appVersion` | `string` | no | App version string (e.g. `"1.4.2"`); forwarded to the backend + client events so analytics can segment the funnel by app version. Auto-detected best-effort from `expo-constants`/`expo-application` (dependency-free) when omitted; pass it to override (yours wins). |
 
-## App events / analytics (root export)
+## App events (root export)
 
-The app-event / analytics API is exported from the ROOT (`@wireai/activation`), NOT a subpath.
+These device-only event helpers are exported from the ROOT (`@wireai/activation`). The analytics
+FACADE (`createAnalytics` and friends) is a different surface and lives on `@wireai/activation/analytics`.
 
 - `WIRE_ONBOARDING_EVENTS` + `toAnalyticsEvent(event)`: canonical `wire_onboarding_*` funnel names; log via the app's own analytics.
 - `reportClientEvent(target, event)` / `reportClientEvents(target, events)`: report device-only funnel events. Contract: `POST {serverUrl}/v1/events`, header `Authorization: Bearer {apiKey}`, body `{ "events": [ ... ] }`. `target = { serverUrl, apiKey }` is derived from `WireOnboardingConfig`. Fire-and-forget: never throws into the UI.
@@ -107,8 +108,9 @@ The app-event / analytics API is exported from the ROOT (`@wireai/activation`),
 4. **Config**: set `EXPO_PUBLIC_WIREAI_API_KEY` / `_SERVER_URL` / `_APP_ID`; build via `wireConfigFromEnv({ appId })`.
 5. **Fonts**: host must load the font families named in `theme.fonts.regular/medium/bold` (e.g. `expo-font`), else text falls back to system font.
 6. **Theme**: `themeFromBrand({ primary })` or a full `Partial<OnboardingTheme>`; for dark/light, pick the theme by the app's theme state.
-7. **Render + continuation**: drop `<WireOnboarding>` into the signup flow; `onComplete` → persist + navigate, `onSkip` → navigate.
-8. **Gate**: wrap behind a flag (env for dev, remote config for prod) **AND** `config != null`; fall through to existing onboarding when off/unconfigured. Decide who sees it (e.g. new signups only) in host nav logic.
+7. **Render + continuation**: drop `<WireOnboarding>` into the signup flow; `onComplete` → persist + navigate, `onSkip` → navigate. Pass the join key: `userContext={activationJoinContext(deviceKey)}`, or `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))` when the app owns no device id. Skipping it leaves the `activated` funnel permanently empty and reports no error.
+8. **Lifecycle (do not skip)**: mount `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` ONCE at the app root, before anything else touches analytics. It is the only path that emits `app.first_open`, it registers the per-open session id that `createAnalytics` / `wire.track` / the gates all correlate to, and with `config.storage` it stamps the kit's persisted auto `device_key` on `app.session_started`, which is what the server's `min_sessions` rule counts. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`.
+9. **Gate**: wrap behind a flag (env for dev, remote config for prod) **AND** `config != null`; fall through to existing onboarding when off/unconfigured. Decide who sees it (e.g. new signups only) in host nav logic.
 
 ## Review firing (do not hand-roll the decision fetch)
 
@@ -141,7 +143,8 @@ the kit never forces a rebuild); the adapter types the RevenueCat objects struct
 the real ones you already have.
 
 ```tsx
-import { createAnalytics, createRevenueCatBridge, activationJoinContext } from "@wireai/activation";
+import { createRevenueCatBridge, activationJoinContext } from "@wireai/activation";
+import { createAnalytics } from "@wireai/activation/analytics";
 
 const analytics = createAnalytics({ serverUrl, apiKey, storage, appId, userContext: { deviceKey } });
 const revenuecat = createRevenueCatBridge({ analytics, entitlementId: "pro" });

package/CHANGELOG.md

@@ -3,6 +3,136 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [0.12.2] — 2026-07-27
+
+The auto-join patch. 0.12.1 taught the kit to complain about a missing join key; this one teaches it
+to supply the key. `user_context.device_key` is the only thing that stitches an onboarding session to
+everything the app reports later, the prop that carries it is optional, and two of three production
+integrations shipped without it and read `activated: 0`. A warning fixes that for the next host, not
+for the current one, so the default now produces a joined funnel.
+
+### Changed
+
+- **⚠️ BEHAVIOR CHANGE: `<WireOnboarding>` supplies its own join key when the host supplied none.**
+  With `storage` present and no `device_key` in `userContext`, the kit merges in its own per-install
+  key, and both the A2A session-start metadata and the onboarding client events carry it. That key is
+  the SAME id `createAnalytics` / `createWireActivation` mint and persist, resolved through
+  `hydrateAutoDeviceKey({ appId, storage })` rather than the synchronous
+  `resolveAutoDeviceKey({ appId, storage })`, so it is the persisted id, not a pre-hydration mint.
+  Three limits, all deliberate:
+  - **A host-supplied key always wins**, forwarded verbatim, nothing merged over it. An integration
+    that already passes `activationJoinContext(deviceKey)` sends a byte-identical payload.
+  - **No `storage`, no injection.** Without persistence the id is minted fresh every launch, and the
+    server counts `min_sessions` by distinct app-opens grouped on `device_key`: a per-launch key
+    corrupts that counter instead of merely leaving the join empty. The kit declines and warns in dev.
+  - **The key is resolved BEFORE the provider mounts**, behind the loader gate the persisted-session
+    read already holds. `userContext` feeds the A2A config, and swapping it after mount would rebuild
+    the adapter and drop the server-learned `contextId`. The read is timeout-capped, so a hung storage
+    adapter degrades to no key instead of a stuck loader.
+
+  Who this changes: a host that deliberately wanted an unlinked onboarding session. That host now
+  passes `autoJoinKey={false}`.
+- **The 0.12.1 missing-join-key dev warning is reconciled with the above.** It no longer fires when
+  auto-injection covered the gap. It still fires when the gap is genuinely open, and it now names
+  which of the three reasons applies: no `storage`, `autoJoinKey={false}`, or a storage adapter that
+  did not answer in time.
+- **A hand-written `userContext={{ deviceKey }}` still warns, even though the kit injected.** That
+  host demonstrably owns a device id, and their app-side events carry it, so the two families still
+  land in disjoint id spaces. Injection makes the onboarding side self-consistent; only the host can
+  make it join. Silencing this would have undone the 0.12.1 fix for the most common mis-wiring.
+
+### Added
+
+- **`autoJoinKey` prop on `<WireOnboarding>`,** the documented opt-out. Default `true`. Setting it to
+  `false` restores the pre-0.12.2 behavior exactly: nothing is injected and the dev warning fires.
+  Documented in the `userContext` JSDoc, the README props table, and the README join-key section.
+
+## [0.12.1] — 2026-07-27
+
+The integration-contract patch. 0.12.0's runtime worked; what did not work was everything the package
+let a host leave out. Two of three real integrations went wrong in ways the kit accepted without
+complaint, and the review that produced this release found a third: the ordered integration steps in
+every shipped doc never once said "mount `useLifecycleEvents`", while the kit's own runtime warning
+names that exact symbol as the fix. Nothing here tightens the wire; every new check is `__DEV__`-only
+or a client-side default.
+
+### Added
+
+- **`<WireOnboarding>` warns in dev when it got no join key.** `user_context.device_key` is the only
+  thing that joins an onboarding session to the app's later events, and the prop that carries it is
+  optional and named `userContext`, so forgetting it is the default and the failure is a silent zero
+  in the `activated` funnel. The warning names `activationJoinContext(deviceKey)` and, for a host that
+  owns no device id, `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))`. The
+  `userContext` JSDoc + the README props row now lead with "this is where the join key goes" instead
+  of describing the prop as segmentation context. The prop is NOT renamed (breaking, for no gain), and
+  auto-injection is deliberately held for 0.13.0.
+- **`wireConfigFromEnv` says "Wire is off" out loud in dev.** A missing EAS env var made it return
+  `null`, and then the facade never constructed, `useLifecycleEvents` no-oped, and every gate returned
+  null: three independent silent no-ops from one missing var. It now warns once, naming WHICH var is
+  missing and that the kit is fully disabled. The `null` return is unchanged, and hosts still gate on
+  it. `WIRE_ENV_VARS` is exported so a host preflight can assert the three names itself.
+- **`hydrateAutoDeviceKey({ appId, storage })`,** the awaitable sibling of `resolveAutoDeviceKey`. It
+  joins the same single-flight storage read and resolves once the persisted id is in hand, for the one
+  caller that can afford to wait. Never rejects.
+- **The review / questionnaire gates warn in dev when they have no sync storage.** With no storage the
+  app-open counter is pinned at 1 forever, so the fail-closed `minSessions: 2` default is
+  unsatisfiable and the gate never fires, which is indistinguishable from "the rules said not yet".
+- **The lifecycle mount reached the docs.** `useLifecycleEvents` is now an ordered step in `AGENTS.md`
+  and `INTEGRATION_PROMPT.md`, a README section directly above "Session mapping", and a line in
+  `llms.txt`. `useSessionStart` / `reportSessionStart` are demoted to the "you already own a counter"
+  alternatives, with the fact that neither emits `app.first_open` stated where a reader will hit it.
+
+### Fixed
+
+- **`useLifecycleEvents` stamped a freshly minted `device_key`, not the persisted one.**
+  `resolveAutoDeviceKey` is synchronous by contract, so a mount-time caller got a brand-new `wdev_*`
+  and adopted the persisted id milliseconds later. On every launch, both lifecycle events therefore
+  rode a key nothing else shared. The server computes `min_sessions` by counting distinct
+  `app.session_started` grouped by `device_key`, so that counter could never exceed 1, and
+  `app.first_open` (once ever) landed under a key no later event shares, which broke `first_open` to
+  `activated` cohorting too. The mount fire now awaits `hydrateAutoDeviceKey` — but ONLY when the auto
+  fallback is actually in play. A host-supplied `deviceKey`, or no `storage`, still fires
+  synchronously at mount.
+- **The gate counter's unit could change mid-launch.** The gates call `bumpSessionCount` from a
+  `useState` initializer (render phase) while `useLifecycleEvents` registers the per-open id from a
+  root effect, and React runs every render before any effect. So a cold start counted a process id and
+  then a session id as TWO app-opens, which made `minSessions: 2` — the fail-closed default added
+  after the 2026-07-16 one-star incident — satisfiable inside a single launch. `currentOpenId()` now
+  pins whatever it first resolved for the whole launch. Behavioural, in the fail-closed direction: a
+  gate fires later, never earlier.
+- **The coachmark storage singleton was a plain module `let`, duplicated across four dist bundles.**
+  Under `dist` resolution (node `import`/`require`, SSR, jest, RN-web, anything that is not Metro) a
+  host that mounted `CoachmarkProvider` from `@wireai/activation/coachmarks` wrote the coachmarks copy
+  while `useReviewGate` from `@wireai/activation/reviews` read the reviews copy, which was still
+  `null` — so the gate never fired, the `seen` once-gate never persisted, and a tenant's coachmarks
+  kill switch never reached the reviews bundle. The storage, the QA replay flag and the kill switch now
+  live in one `globalThis` slot keyed by `Symbol.for("@wireai/activation:coachmarkRuntime")`, the same
+  remedy already applied to `currentSession`, the auto device-key registry and activation revalidation.
+- **The analytics facade read the session registry but never registered.** `resolveSessionId` was a
+  pure read with a per-instance fallback, so a `track` before the root lifecycle effect carried an id
+  the server had no `app.session_started` for and the server back-filled a phantom session, while a
+  `wire.track` moments later minted and registered a different one. It is now
+  `config.sessionId ?? ensureCurrentSessionId()`, a strict superset: when an open is registered this is
+  exactly `getCurrentSessionId()`, and the frozen-id opt-out is untouched.
+- **`wireConfigFromEnv` structurally could not carry `appVersion`,** so a host that built its config
+  the documented way forwarded `undefined` everywhere. The facade and lifecycle paths each auto-detect
+  their own fallback; `createWireActivation` did not, so EVERY `wire.track` event shipped with no
+  `app_version` at all. The helper now defaults it to `detectAppVersion()` (an explicit override still
+  wins) and `createWireActivation` gained the same fallback as the facade.
+- **`useSessionStart` had no auto `device_key` fallback,** while its sibling `useLifecycleEvents` did.
+  A host on the documented `useSessionStart` path emitted the very event `min_sessions` counts with no
+  device key while its other events carried an auto-minted one. Backported, storage-gated on the same
+  rule (no storage means no fallback, because a per-launch key corrupts the counter the other way).
+- **`AGENTS.md` shipped an import that cannot resolve, and denied a subpath that exists.**
+  `import { createAnalytics } from "@wireai/activation"` does not compile (it lives on
+  `@wireai/activation/analytics`), and the same file claimed "There is no `analytics` subpath" while
+  `package.json` exports it, `tsup` builds it and `llms.txt` documents it. `README.md` shipped the same
+  broken import. Both are fixed, and `src/docsContract.test.ts` now resolves every documented
+  specifier against the BUILT `dist` through the real `exports` map, so the drift cannot return quietly.
+- **`warnOnSkippedEvents` parsed the response body in release builds.** The `__DEV__` check sat inside
+  the `.then`, after `res.json()`, so every persistent-path POST paid a JSON parse to build a warning
+  nobody would read. The check is now the first statement in the function.
+
 ## [0.12.0] — 2026-07-27
 
 The release Myelino 2.2.0 pins. Ships the RevenueCat path (#52), the identity/counting audit,

package/INTEGRATION_PROMPT.md

@@ -40,10 +40,21 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    - `fallbackFlow` MUST be my existing static onboarding so a backend error/timeout degrades, never
      dead-ends.
    - Forward install attribution if I have it: `wireConfigFromEnv({ appId, metadata: attributionMetadata({...}) })`.
+   - THE JOIN KEY: pass `userContext={activationJoinContext(deviceKey)}`. If my app owns no stable
+     device id, use `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))`, which returns
+     the same id the analytics side stamps. Leaving it out makes the `activated` funnel read zero
+     forever and reports no error.
    - Analytics: log via `toAnalyticsEvent(e)` → my logger, using the canonical `wire_onboarding_*` names.
 7. Navigation: mount the screen in my first-run/signup flow; branch to the static flow when the gate
    is off or config is missing.
-8. Event triggers (only if I asked to fire a review/questionnaire off an in-app action): pick the
+8. Lifecycle (do NOT skip): mount `useLifecycleEvents(config, { deviceKey, sessionCount, userId })`
+   ONCE at my app root, above the navigator, before anything else touches analytics. Pass
+   `config.storage`. It is the only path that emits `app.first_open`, it registers the per-open
+   session id every other surface correlates to, and with storage it stamps the kit's persisted auto
+   `device_key` on `app.session_started`, which is what the server counts `min_sessions` from.
+   `useSessionStart` / `reportSessionStart` are only for a host that already owns an open counter;
+   neither emits `first_open`.
+9. Event triggers (only if I asked to fire a review/questionnaire off an in-app action): pick the
    action that should trigger it (e.g. finishing a task, journaling a win) and its key, e.g.
    `journal_done`. On my home/gate screen call
    `const { track, sessionId, revalidation } = useWireActivation({ serverUrl: WIREAI_SERVER_URL, apiKey: WIREAI_API_KEY, appId: APP_ID, deviceKey })`
@@ -53,7 +64,7 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    `useQuestionnaireGate` the same way), and at the action site call `await track("journal_done")`.
    Do NOT hand-roll the session id or the POST; `wire.track` owns both and revalidates the gate on
    a successful 2xx.
-9. RevenueCat (only if my app sells subscriptions through `react-native-purchases`): wire my paywall
+10. RevenueCat (only if my app sells subscriptions through `react-native-purchases`): wire my paywall
    to the same event stream with `createRevenueCatBridge({ analytics, entitlementId: "<my
    entitlement, e.g. pro>" })` from `@wireai/activation`. Do NOT add or import
    `react-native-purchases` in the kit path; the adapter types the RevenueCat objects structurally,
@@ -65,7 +76,7 @@ STEPS (do them in order, stop and ask if a convention is ambiguous):
    onboarding on `user_context.device_key` and never on `session_id` (those are separate id spaces
    and intersecting them returns zero rows). If my app has no single stable device key yet, say so
    instead of inventing one.
-10. Verify: type-check (and lint the changed files); test the flag-off + backend-error paths.
+11. Verify: type-check (and lint the changed files); test the flag-off + backend-error paths.
 
 Report back: the files you changed (path:line), the typecheck result, and anything you couldn't
 infer about my conventions.

package/README.md

@@ -246,7 +246,8 @@ import { WireOnboarding } from "@wireai/activation";
 | `storage` | `WireOnboardingStorage` | Host-injected storage (AsyncStorage-compatible `getItem/setItem/removeItem`) for **session-id persistence**: an app KILL mid-onboarding resumes the SAME backend session instead of minting a new one, so the funnel's `started` count stays honest (no phantom drops). Pass AsyncStorage as-is, or a 3-line MMKV wrapper. Omit for the previous per-mount behavior. Persists the kit's own correlation seed only — answers stay the host's job via `onComplete`. |
 | `sessionTtlMs` | `number` | How long a persisted session id stays resumable. Default `3600000` (1h, the backend's session TTL). With `storage` only. |
 | `persistKey` | `string` | Override the storage key (default `wireai:session:<appId>`). Scope per-user if one device can onboard multiple accounts mid-flow. With `storage` only. |
-| `userContext` | `Record<string, string \| number \| boolean>` | Host-injected, non-PII context the app already knows (signup method, referral, plan, a HASHED user id). Forwarded on session metadata + client events for funnel segmentation. **No PII on THIS prop** (no raw emails/names); primitives only; the server caps size/keys. See [Device & user context](#device--user-context). ⚠️ Distinct from the analytics/activation **`WireUserContext`** object (`createAnalytics` / `useWireActivation`), which additionally accepts an opt-in raw `userEmail` — see [Rich user context & PII](#rich-user-context--pii). |
+| `userContext` | `Record<string, string \| number \| boolean>` | **This is where the join key goes.** `user_context.device_key` is the only thing that joins this onboarding session to the app's later events, so pass `userContext={activationJoinContext(deviceKey)}` (or `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))` if your app owns no device id). Since 0.12.2, omitting it no longer empties the funnel silently: with `storage`, the kit injects its own key (see [The join key](#the-join-key-device_key-never-session_id) and `autoJoinKey` below). Second job: any other non-PII context the app already knows (signup method, referral, plan, a HASHED user id), forwarded on session metadata + client events for funnel segmentation. **No PII on THIS prop** (no raw emails/names); primitives only; the server caps size/keys. See [Device & user context](#device--user-context). ⚠️ Distinct from the analytics/activation **`WireUserContext`** object (`createAnalytics` / `useWireActivation`), which additionally accepts an opt-in raw `userEmail` — see [Rich user context & PII](#rich-user-context--pii). |
+| `autoJoinKey` | `boolean` | Opt OUT of the automatic join key. Default `true`. When this prop is left alone, `storage` is present, and `userContext` carries no `device_key`, the kit injects its own per-install key (the same id `createAnalytics` / `createWireActivation` mint and persist), so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session: that restores the pre-0.12.2 behavior exactly, and the dev warning fires again. It never overrides a `device_key` you passed, and it cannot inject without `storage` (see [The join key](#the-join-key-device_key-never-session_id)). |
 | `userId` | `string` | Your own OPAQUE user id, so onboarding sessions reconcile to real users later (console sessions to your user table / GA4 users). Optional and supports **late binding**: present at mount it rides the session-start metadata; if it changes mid-session (the user just registered) the kit emits an `identify` event; available only after the flow, use `identifyOnboarding(...)`. **No PII** (not an email/name/phone); trimmed and capped at 128 chars. See [User identity](#user-identity). |
 
 ## Helpers (the reusable substrate)
@@ -388,6 +389,34 @@ Omit it. Pass one only if your host runs its own session lifecycle and owns the
 correlate on. This is a different field from the per-open `sessionId` that `useWireActivation` and
 `reportAppEvent` READ (that one is the live id, and reading it is always fine).
 
+## Lifecycle events (mount this once, before anything else touches analytics)
+
+One hook at your app root wires the whole top of the funnel: `app.first_open` once ever, and
+`app.session_started` on every real app-open, both offline-buffered.
+
+```tsx
+import { useLifecycleEvents } from "@wireai/activation";
+
+// At the app root, above your navigator:
+useLifecycleEvents(
+  { serverUrl, apiKey, appId, storage },      // same creds as onboarding
+  { deviceKey, sessionCount, userId },        // all optional
+);
+```
+
+Mount it first. Three other things read the per-open session it registers: `createAnalytics`,
+`wire.track`, and the review / questionnaire gates. Without it every one of them falls back to an id
+the server has no `app.session_started` for, so the session is thinner than a real open, and the kit
+warns about it once in dev.
+
+Pass `storage`. With it the hook falls back to the kit's persisted auto `device_key` when you supply
+none, and waits for that key to be read back before it fires, so the events the server counts
+`min_sessions` from carry the id this install keeps. Without storage the id would be per-launch, which
+would make every open look like a new device, so the fallback deliberately does not engage.
+
+The two alternatives below are for a host that already owns an open counter. Both emit
+`app.session_started` only, so `app.first_open` stays empty forever on those paths.
+
 ## Session mapping (know when a user opens the app again)
 
 Onboarding runs once, on the first launch. Session mapping is the other half: every time the
@@ -990,7 +1019,8 @@ If you sell subscriptions with [RevenueCat](https://www.revenuecat.com/), the pa
 The kit does **not** depend on `react-native-purchases`, and it never will. That package is a native module, and the kit's whole promise is that it never puts a native rebuild in your way. So the adapter types the RevenueCat objects structurally instead, which means you hand it the real `CustomerInfo` / `PurchasesPackage` / `PurchasesOffering` you already have. Nothing new gets installed.
 
 ```tsx
-import { createAnalytics, createRevenueCatBridge } from "@wireai/activation";
+import { createRevenueCatBridge } from "@wireai/activation";
+import { createAnalytics } from "@wireai/activation/analytics";
 
 const analytics = createAnalytics({ serverUrl, apiKey, storage, appId, userContext: { deviceKey } });
 const revenuecat = createRevenueCatBridge({ analytics, entitlementId: "pro" });
@@ -1038,6 +1068,14 @@ const analytics = createAnalytics({ serverUrl, apiKey, storage, appId, userConte
 
 Skip the onboarding half and the purchase events are still valid on their own, they just cannot be attributed back to an onboarding.
 
+**Since 0.12.2 the kit fills the gap for you.** If `<WireOnboarding>` gets `storage` and a `userContext` with no `device_key`, it injects its own per-install key: the SAME id `createAnalytics` / `createWireActivation` mint and persist, read back from storage rather than minted fresh. So the default wiring joins, and the code block above is now about *overriding* the key rather than about remembering it.
+
+Three rules govern it:
+
+- **Your key always wins.** Any non-empty `device_key` you pass is forwarded verbatim and nothing is merged over it. Existing integrations see a byte-identical payload.
+- **It needs `storage`.** Without persistence the kit's id is minted fresh on every launch, and a per-launch key is worse than no key: the server counts `min_sessions` by distinct app-opens grouped on `device_key`, so it corrupts the counter instead of leaving the join empty. With no `storage` the kit declines to inject and warns in dev.
+- **You can opt out.** `autoJoinKey={false}` restores the pre-0.12.2 behavior for a host that genuinely wants an unlinked session. The dev warning fires again there, naming the opt-out as the reason nothing was injected.
+
 ## Feature controls (per-module kill switches)
 
 Every activation surface has a switch you can flip from the dashboard "in case of something":

package/dist/analytics/index.d.mts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-CF_eHwzC.mjs';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-DsSDHqor.mjs';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-DsSDHqor.mjs';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-BlCeDP0f.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-BlCeDP0f.mjs';
 import '../types-CNUqMK0D.mjs';
 import '../types-BKfpdZzX.mjs';
 import '../types-BcmagF6K.mjs';
@@ -114,8 +114,9 @@ type CreateAnalyticsConfig = {
      * analytics then collapse onto a single device-scoped session — one "first open", forever.
      *
      * OMIT IT — that is the correct default. Without it the kit reuses the live per-open session, and
-     * falls back to a stable per-instance id only until an open has been registered. Pass one ONLY if
-     * your host runs its own session lifecycle and owns the id the server should correlate on.
+     * when no open has been registered yet it mints one AND registers it, so every later surface joins
+     * the same session instead of each inventing its own. Pass one ONLY if your host runs its own
+     * session lifecycle and owns the id the server should correlate on.
      */
     sessionId?: string;
     /** Tenant/app id used to namespace the queue's default storage key (`wireai:evtq:<appId>`). */

package/dist/analytics/index.d.ts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DsRe4epC.js';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-D6RiVtc8.js';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-D6RiVtc8.js';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-BxEB37xt.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-BxEB37xt.js';
 import '../types-Buj9Lw9t.js';
 import '../types-BKfpdZzX.js';
 import '../types-BcmagF6K.js';
@@ -114,8 +114,9 @@ type CreateAnalyticsConfig = {
      * analytics then collapse onto a single device-scoped session — one "first open", forever.
      *
      * OMIT IT — that is the correct default. Without it the kit reuses the live per-open session, and
-     * falls back to a stable per-instance id only until an open has been registered. Pass one ONLY if
-     * your host runs its own session lifecycle and owns the id the server should correlate on.
+     * when no open has been registered yet it mints one AND registers it, so every later surface joins
+     * the same session instead of each inventing its own. Pass one ONLY if your host runs its own
+     * session lifecycle and owns the id the server should correlate on.
      */
     sessionId?: string;
     /** Tenant/app id used to namespace the queue's default storage key (`wireai:evtq:<appId>`). */

package/dist/analytics/index.js

@@ -414,17 +414,17 @@ var buildEventsRequest = (target, events) => {
   }
 };
 var warnOnSkippedEvents = (res) => {
+  if (typeof __DEV__ === "undefined" || !__DEV__) return;
+  if (typeof console === "undefined" || !console.warn) return;
   try {
     const json = res == null ? void 0 : res.json;
     if (typeof json !== "function") return;
     void Promise.resolve(json.call(res)).then((body) => {
       const skipped = body == null ? void 0 : body.skipped;
       if (typeof skipped !== "number" || skipped <= 0) return;
-      if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-        console.warn(
-          `[wireai] the server ACCEPTED the /v1/events POST but DISCARDED ${skipped} event(s) (skipped in the response body) \u2014 they are gone, not retried. The usual cause is an event with a missing or empty session_id.`
-        );
-      }
+      console.warn(
+        `[wireai] the server ACCEPTED the /v1/events POST but DISCARDED ${skipped} event(s) (skipped in the response body) \u2014 they are gone, not retried. The usual cause is an event with a missing or empty session_id.`
+      );
     }).catch(() => {
     });
   } catch {
@@ -1119,6 +1119,31 @@ var autoDeviceKeyRegistry = () => {
   deviceKeyGlobal[AUTO_DEVICE_KEY_SLOT] = created;
   return created;
 };
+var startHydration = (registry, appId, storage, minted) => {
+  if (!registry.pending) registry.pending = /* @__PURE__ */ new Map();
+  const existing = registry.pending.get(appId);
+  if (existing) return existing;
+  const slot = deviceIdStorageKey(appId);
+  const settled = () => {
+    var _a2;
+    return (_a2 = registry.keys.get(appId)) != null ? _a2 : minted;
+  };
+  let run;
+  try {
+    run = Promise.resolve(storage.getItem(slot)).then((saved) => {
+      const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : void 0;
+      if (persisted) {
+        registry.keys.set(appId, persisted);
+        return persisted;
+      }
+      return Promise.resolve(storage.setItem(slot, minted)).then(settled, settled);
+    }).catch(settled);
+  } catch {
+    run = Promise.resolve(settled());
+  }
+  registry.pending.set(appId, run);
+  return run;
+};
 var resolveAutoDeviceKey = (opts = {}) => {
   var _a2, _b;
   const registry = autoDeviceKeyRegistry();
@@ -1131,25 +1156,16 @@ var resolveAutoDeviceKey = (opts = {}) => {
   const storage = opts.storage;
   if (storage && !registry.hydrating.has(appId)) {
     registry.hydrating.add(appId);
-    const slot = deviceIdStorageKey(appId);
-    const minted = id;
-    try {
-      void Promise.resolve(storage.getItem(slot)).then((saved) => {
-        const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : void 0;
-        if (persisted) registry.keys.set(appId, persisted);
-        else void Promise.resolve(storage.setItem(slot, minted)).catch(() => {
-        });
-      }).catch(() => {
-      });
-    } catch {
-    }
+    void startHydration(registry, appId, storage, id);
   }
   return (_b = registry.keys.get(appId)) != null ? _b : id;
 };
 var resetAutoDeviceKeys = () => {
+  var _a2;
   const registry = autoDeviceKeyRegistry();
   registry.keys.clear();
   registry.hydrating.clear();
+  (_a2 = registry.pending) == null ? void 0 : _a2.clear();
 };
 
 // src/analytics/analyticsFacade.ts
@@ -1159,11 +1175,10 @@ var warnInDev2 = (message) => {
   }
 };
 var createAnalytics = (config, options = {}) => {
-  var _a2, _b, _c, _d;
-  const instanceSessionId = (_a2 = config.sessionId) != null ? _a2 : makeSessionId();
+  var _a2, _b, _c;
   const resolveSessionId = () => {
-    var _a3, _b2;
-    return (_b2 = (_a3 = config.sessionId) != null ? _a3 : getCurrentSessionId()) != null ? _b2 : instanceSessionId;
+    var _a3;
+    return (_a3 = config.sessionId) != null ? _a3 : ensureCurrentSessionId();
   };
   if (config.sessionId) {
     warnInDev2(
@@ -1171,8 +1186,8 @@ var createAnalytics = (config, options = {}) => {
     );
   }
   const detectedAppVersion = detectAppVersion();
-  let userContext = { ...(_b = config.userContext) != null ? _b : {} };
-  const hostDeviceKeyAtInit = typeof ((_c = config.userContext) == null ? void 0 : _c.deviceKey) === "string" && config.userContext.deviceKey.trim() ? config.userContext.deviceKey.trim() : void 0;
+  let userContext = { ...(_a2 = config.userContext) != null ? _a2 : {} };
+  const hostDeviceKeyAtInit = typeof ((_b = config.userContext) == null ? void 0 : _b.deviceKey) === "string" && config.userContext.deviceKey.trim() ? config.userContext.deviceKey.trim() : void 0;
   const autoDeviceKeyOptions = {
     appId: config.appId,
     // A host-supplied deviceKey opts out of minting AND persisting (unchanged contract).
@@ -1195,7 +1210,7 @@ var createAnalytics = (config, options = {}) => {
     envelope,
     ...options
   });
-  let boundUserId = sanitizeUserId((_d = config.userContext) == null ? void 0 : _d.userId);
+  let boundUserId = sanitizeUserId((_c = config.userContext) == null ? void 0 : _c.userId);
   const storageKey = analyticsUserIdStorageKey(config.appId);
   if (config.storage) {
     void config.storage.getItem(storageKey).then((saved) => {