@wireai/activation 0.12.0 → 0.12.2

package/src/session-analytics/useLifecycleEvents.ts

@@ -10,7 +10,10 @@
  *
  * Firing moments mirror {@link useSessionStart} exactly:
  *   • ON MOUNT — the app opened (cold start / provider first render). `app.first_open` fires here
- *     too (once ever, gated by the persisted flag in `reportFirstOpen`).
+ *     too (once ever, gated by the persisted flag in `reportFirstOpen`). When the kit's AUTO device
+ *     key is the one in play (no host `deviceKey`, `config.storage` present) the mount fire waits on
+ *     one storage read so both events carry the PERSISTED key, not a freshly minted one — see the
+ *     `hydrateAutoDeviceKey` note below.
  *   • ON FOREGROUND after a real background of at least {@link BACKGROUND_SESSION_MS} (30 min) — a
  *     new app-open, so a fresh `app.session_started` fires. A quick app-switch does NOT count.
  *
@@ -29,7 +32,7 @@ import { AppState, Platform, type AppStateStatus } from "react-native";
 
 import { createEventQueue, type EnvelopeSource, type EventQueue } from "../analytics/eventQueue";
 import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
-import { resolveAutoDeviceKey } from "../context/deviceId";
+import { hydrateAutoDeviceKey, resolveAutoDeviceKey } from "../context/deviceId";
 import { collectDeviceContext } from "../device/deviceContext";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import { reportFirstOpen } from "./lifecycle";
@@ -173,33 +176,58 @@ export const useLifecycleEvents = (
       });
     };
 
-    // 1) session_start FIRST (mount = an app-open), so the server has ingested `session_started`
-    //    for `mountOpenSessionId` before first_open references the same id.
-    fireSession(mountOpenSessionId);
+    // The mount open: session_start FIRST (mount = an app-open), so the server has ingested
+    // `session_started` for `mountOpenSessionId` before first_open references the same id; then
+    // first_open — once ever (persisted flag + in-memory latch inside reportFirstOpen), pinned to the
+    // SAME per-open id so it is never a phantom session.
+    const fireMountOpen = () => {
+      fireSession(mountOpenSessionId);
 
-    // 2) first_open — once ever (persisted flag + in-memory latch inside reportFirstOpen), pinned to
-    //    the SAME per-open id so it is never a phantom session.
-    {
       const { config: cfg, options: opts } = latest.current;
-      if (opts.enabled !== false) {
-        const device = collectDeviceContext();
-        // `device.appVersion` is auto-detected best-effort; an explicit host version always wins.
-        if (cfg?.appVersion) device.appVersion = cfg.appVersion;
-        reportFirstOpen({
-          target: targetOf(cfg),
-          sink: resolveSink(),
-          sessionId: mountOpenSessionId,
-          storage: cfg?.storage,
-          appId: cfg?.appId,
-          userId: opts.userId,
-          deviceKey: resolveDeviceKey(cfg, opts),
-          sessionCount: opts.sessionCount,
-          appVersion: cfg?.appVersion ?? device.appVersion,
-          platform: Platform.OS,
-          device,
-          meta: opts.meta,
-        });
-      }
+      if (opts.enabled === false) return;
+      const device = collectDeviceContext();
+      // `device.appVersion` is auto-detected best-effort; an explicit host version always wins.
+      if (cfg?.appVersion) device.appVersion = cfg.appVersion;
+      reportFirstOpen({
+        target: targetOf(cfg),
+        sink: resolveSink(),
+        sessionId: mountOpenSessionId,
+        storage: cfg?.storage,
+        appId: cfg?.appId,
+        userId: opts.userId,
+        deviceKey: resolveDeviceKey(cfg, opts),
+        sessionCount: opts.sessionCount,
+        appVersion: cfg?.appVersion ?? device.appVersion,
+        platform: Platform.OS,
+        device,
+        meta: opts.meta,
+      });
+    };
+
+    // WAIT FOR THE PERSISTED DEVICE KEY, but ONLY when the auto fallback is the one in play.
+    //
+    // `resolveAutoDeviceKey` is synchronous by contract: it returns a freshly minted id and adopts the
+    // PERSISTED one a storage read later. Firing at mount therefore stamped a brand-new `wdev_*` on
+    // BOTH lifecycle events on every launch, while every other surface adopted the persisted id
+    // milliseconds afterwards. Those two events are exactly the ones the server counts `min_sessions`
+    // from (distinct `app.session_started` grouped by `device_key`), so the counter could never exceed
+    // 1 — and `first_open`, fired once ever, ended up under a key no later event shares, which breaks
+    // `first_open` → `activated` cohorting too. One storage read at mount buys both back.
+    //
+    // A host-supplied `deviceKey` needs no read, and with no `storage` there is nothing to read (and
+    // `resolveDeviceKey` deliberately does not fall back), so both keep firing synchronously at mount.
+    let cancelled = false;
+    const { config: mountCfg, options: mountOpts } = latest.current;
+    const hostKey =
+      typeof mountOpts.deviceKey === "string" && mountOpts.deviceKey.trim()
+        ? mountOpts.deviceKey
+        : undefined;
+    if (!hostKey && mountCfg?.storage) {
+      void hydrateAutoDeviceKey({ appId: mountCfg.appId, storage: mountCfg.storage }).then(() => {
+        if (!cancelled) fireMountOpen();
+      });
+    } else {
+      fireMountOpen();
     }
 
     // Foreground after a real background = a new app-open.
@@ -217,6 +245,8 @@ export const useLifecycleEvents = (
     };
     const sub = AppState.addEventListener("change", onChange);
     return () => {
+      // A pending hydration must not fire an app-open for a mount that is already gone.
+      cancelled = true;
       // RN >= 0.65 returns a subscription with remove(); guard for older shims.
       if (sub && typeof (sub as { remove?: () => void }).remove === "function") sub.remove();
     };

package/src/session-analytics/useSessionStart.ts

@@ -10,6 +10,11 @@
  * Each firing mints its OWN per-open `session_id` (held in a ref so a re-render never re-fires),
  * so grouping over time is by `deviceKey`/`userId`, never by session_id (see reportSessionStart).
  *
+ * NOT THE DEFAULT WIRING. `useLifecycleEvents` is: this hook emits `app.session_started` ONLY, so a
+ * host on this path has a permanently empty `app.first_open` and no top of funnel. Use it when you
+ * already own an open counter and deliberately want session starts alone; otherwise mount
+ * `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` once at the app root.
+ *
  * The hook is OPTIONAL. A host that already owns a session counter (most hosts do) can skip
  * the hook and call `reportSessionStart(...)` directly from its own "app opened" path — BOTH
  * paths are first-class. This hook is the batteries-included option for a host that has none.
@@ -21,7 +26,9 @@ import { useEffect, useRef } from "react";
 import { AppState, Platform, type AppStateStatus } from "react-native";
 
 import type { ClientEventTarget } from "../analytics/reportClientEvent";
+import { resolveAutoDeviceKey } from "../context/deviceId";
 import { collectDeviceContext } from "../device/deviceContext";
+import type { WireOnboardingStorage } from "../session/persistedSession";
 import { reportSessionStart } from "./reportSessionStart";
 
 /** A foreground after at least this long in the background counts as a NEW app-open (30 min). */
@@ -35,6 +42,11 @@ export interface SessionStartConfig {
   apiKey?: string;
   /** Host app version (e.g. "1.4.2"), forwarded for release segmentation. Optional. */
   appVersion?: string;
+  /** Tenant/app id — namespaces the auto `device_key` fallback below. */
+  appId?: string;
+  /** Host storage (AsyncStorage subset). Present → `app.session_started` falls back to the kit's
+   *  persisted auto `device_key` when the host passes none. Absent → no fallback (see below). */
+  storage?: WireOnboardingStorage;
 }
 
 /** Per-open identity the host supplies. All optional: a pre-auth open is device-only. */
@@ -66,6 +78,30 @@ export const useSessionStart = (
   latest.current = { config, options };
 
   useEffect(() => {
+    /**
+     * The `device_key` this open rides under. A host-supplied id always wins.
+     *
+     * BACKPORTED FROM `useLifecycleEvents` (which had this and this hook did not): `min_sessions` is
+     * computed server-side by counting distinct `app.session_started` grouped by
+     * `user_context.device_key`, so a host that passed no `deviceKey` emitted the counted event with
+     * NO key while its facade / activation events carried an auto-minted one — two disjoint identity
+     * spaces, and a counter that could never increase. The two session-start paths must not diverge
+     * on the thing the firing rule reads.
+     *
+     * ONLY WITH `storage`, for the same reason as the sibling hook: without persistence the auto id
+     * is per-LAUNCH, and a per-launch key makes every open look like a new device, corrupting
+     * `min_sessions` in the other direction.
+     */
+    const resolveDeviceKey = (
+      cfg: SessionStartConfig | undefined,
+      opts: UseSessionStartOptions,
+    ): string | undefined => {
+      const host = typeof opts.deviceKey === "string" && opts.deviceKey.trim() ? opts.deviceKey : undefined;
+      if (host) return host;
+      if (!cfg?.storage) return undefined;
+      return resolveAutoDeviceKey({ appId: cfg.appId, storage: cfg.storage });
+    };
+
     const fire = () => {
       const { config: cfg, options: opts } = latest.current;
       if (!cfg?.serverUrl) return;
@@ -78,7 +114,7 @@ export const useSessionStart = (
         target,
         // A fresh per-open id each fire; the emitter's once-guard dedupes within the open.
         userId: opts.userId,
-        deviceKey: opts.deviceKey,
+        deviceKey: resolveDeviceKey(cfg, opts),
         sessionCount: opts.sessionCount,
         appVersion: cfg.appVersion ?? device.appVersion,
         platform: Platform.OS,

package/src/types.ts

@@ -148,16 +148,53 @@ export type WireOnboardingProps = {
   /** Lifecycle hook for host-side analytics (started / per-turn / error). */
   onEvent?: (event: OnboardingEvent) => void;
   /**
-   * Host-injected, non-PII context the app already knows about the user — signup method,
-   * referral source, plan tier, a HASHED user id, etc. Same host-injection philosophy as
-   * `storage`: the kit collects nothing here; the host passes what it wants. Forwarded to the
-   * backend on the session metadata AND on client events so analytics can segment the funnel.
+   * **THIS IS WHERE THE JOIN KEY GOES.** `user_context.device_key` is the ONLY thing that joins an
+   * onboarding session to everything the app reports later (analytics, purchases, gate decisions).
+   * Build the value with the helper so the wire spelling is decided in one place:
+   *
+   * ```tsx
+   * <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
+   * // no device id of your own? read the kit's:
+   * <WireOnboarding userContext={activationJoinContext(resolveAutoDeviceKey({ appId, storage }))} ... />
+   * ```
+   *
+   * SINCE 0.12.2, leaving it out no longer silently empties the funnel: when you pass `storage` and
+   * this prop carries no `device_key`, the kit injects its OWN per-install key — the same one the
+   * analytics surfaces mint and persist — so the default wiring joins. Anything you DO pass wins
+   * verbatim and is never touched. See `autoJoinKey` for the opt-out and the two cases where the kit
+   * still cannot fill the gap (no `storage`, or you opted out), which keep warning in dev.
+   *
+   * Never hand-write `userContext={{ deviceKey }}`: the server's device lookup reads `device_key`,
+   * so a misspelled bucket produces a silently empty funnel rather than an error. And never join on
+   * `session_id` — an onboarding session id is the A2A `contextId` while an app-event session id is
+   * the per-open id, so intersecting those two id spaces returns zero rows every time.
+   *
+   * SECOND JOB, segmentation: anything else non-PII the app already knows — signup method, referral
+   * source, plan tier, a HASHED user id. Same host-injection philosophy as `storage`: the kit
+   * collects nothing here; the host passes what it wants. Forwarded to the backend on the session
+   * metadata AND on client events so analytics can segment the funnel.
    *
    * MUST NOT contain PII such as raw emails, names, or phone numbers — pass a hash if you need
    * a user key. Values are limited to primitives (`string | number | boolean`); the server caps
    * key count / size and drops deep nesting. Old servers ignore it (backward compatible).
    */
   userContext?: Record<string, string | number | boolean>;
+  /**
+   * OPT OUT of the automatic join key. Default `true`.
+   *
+   * By default (0.12.2+), an onboarding session that was given no `userContext.device_key` gets the
+   * kit's own per-install key injected — the SAME id `createAnalytics` / `createWireActivation` mint
+   * and persist — so the `activated` funnel joins without the host wiring anything. Pass
+   * `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session; that restores the
+   * pre-0.12.2 behavior exactly (nothing injected) and the dev warning fires again.
+   *
+   * Two things this flag does NOT do. It never overrides a `device_key` you passed — a host-supplied
+   * key always wins, whatever this is set to. And it cannot conjure a key without `storage`: with no
+   * persistence the kit's id is minted fresh every launch, and a per-launch key corrupts
+   * `min_sessions` instead of merely leaving the join empty, so the kit declines to inject and warns
+   * in dev instead.
+   */
+  autoJoinKey?: boolean;
   /**
    * The host's own user id, so onboarding sessions can be reconciled to real users later
    * (console sessions ↔ your user table / GA4 users). First-class alongside `userContext`.