@advenue/react-native 0.3.1 → 0.5.0

package/src/index.ts

@@ -8,6 +8,7 @@ import {
   type AdvenueConfig,
   type Consent,
   DEFAULT_ENDPOINT,
+  DEVICE_ID_KEY,
   type DeepLink,
   type DeviceInfo,
   MemoryStorage,
@@ -16,7 +17,6 @@ import {
   type TrackOptions,
   resolveDurableDeviceId,
 } from '@advenue/sdk-core';
-import type { TrackingAuthorizationStatus } from '@advenue/sdk-ios';
 import { parseMatchToken } from '@advenue/shared/match-token';
 import { sha256Hex } from '@advenue/signing';
 import { type DeepLinkHandle, setupDeepLinks } from './deep-links';
@@ -27,7 +27,10 @@ import {
   getAppState,
   getIosNative,
   getLinking,
+  getPlatformOS,
 } from './native';
+import { createNativeSecureStore, createNativeStorage } from './native-storage';
+import type { TrackingAuthorizationStatus } from './native-types';
 import { type SecureStoreLike, createSecureStore } from './secure-store';
 
 export { createMMKVStorage } from './mmkv-storage';
@@ -37,7 +40,14 @@ export type { SecureStoreLike } from './secure-store';
 export { parseDirectLink } from './deep-links';
 export type { AdvenueConfig, Consent, DeepLink, TrackOptions } from '@advenue/sdk-core';
 export { getAndroidNative, getIosNative } from './native';
-export type { TrackingAuthorizationStatus } from '@advenue/sdk-ios';
+export type {
+  AdvenueAndroidNativeModule,
+  AdvenueDeviceInfo,
+  AdvenueIosNativeModule,
+  InstallReferrerResult,
+  MetaInstallReferrerResult,
+  TrackingAuthorizationStatus,
+} from './native-types';
 
 /**
  * Resolves the device advertising id (IDFA on iOS, GAID on Android), gates it
@@ -86,7 +96,26 @@ export async function resolveAdvertisingId(): Promise<void> {
         ? await android.getAppSetId()
         : null;
     const adFields = r ? (r.limitAdTracking ? { limitAdTracking: true } : { gaid: r.id }) : {};
-    client.setAdvertisingId({ ...adFields, ...(vendorId ? { vendorId } : {}) });
+    // SSAID fallback (Adjust parity): only when no usable GAID exists (no Play
+    // Services, or ad tracking limited). Play policy forbids linking a
+    // persistent device id to the advertising id, so a device WITH a usable
+    // GAID never reports its SSAID — the SSAID's job is reinstall detection
+    // and device dedup where GAID can't do it (first-party fraud use).
+    const hasUsableGaid = !!r && !r.limitAdTracking;
+    const rawAndroidId =
+      !hasUsableGaid && typeof (android as { getAndroidId?: unknown }).getAndroidId === 'function'
+        ? (android as { getAndroidId(): string | null }).getAndroidId()
+        : null;
+    // Mirror the server schema (events.ts androidIdSchema): a non-conforming
+    // OEM value attached to every event would 400 the whole batch and poison
+    // the queue — a malformed SSAID must degrade to "absent", never to loss.
+    const androidId =
+      rawAndroidId && /^[0-9a-fA-F]{8,32}$/.test(rawAndroidId) ? rawAndroidId : null;
+    client.setAdvertisingId({
+      ...adFields,
+      ...(vendorId ? { vendorId } : {}),
+      ...(androidId ? { androidId } : {}),
+    });
     return;
   }
   client.setAdvertisingId({});
@@ -136,25 +165,40 @@ export async function resolveClipboardMatch(): Promise<DeepLink | null> {
   ) {
     return null;
   }
-  const matchId = parseMatchToken(ios.getPasteboardMatchToken());
+  let token: string | null;
+  try {
+    token = ios.getPasteboardMatchToken();
+  } catch (err) {
+    // Native pasteboard read failed (bridge error, MDM restriction) — deferred
+    // resolution falls through to the server-side conversion poll.
+    reportError('enrich.clipboardMatch', err);
+    return null;
+  }
+  const matchId = parseMatchToken(token);
   if (!matchId) return null;
   return client.exchangeClipboardMatch(matchId);
 }
 
-export interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage'> {
+export interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage' | 'platform'> {
   /**
-   * An MMKV instance for the durable offline buffer:
-   *   import { MMKV } from 'react-native-mmkv';
-   *   Advenue.initialize({ apiKey, platform: 'ios', mmkv: new MMKV() });
-   * Omit to fall back to in-memory buffering (events lost on cold start).
+   * Auto-detected from React Native's `Platform.OS` — omit it. Pass explicitly
+   * only outside a React Native runtime (tests, custom embeddings); `ios` and
+   * `android` map verbatim, any other RN target (web, desktop) reports as
+   * `web`.
+   */
+  platform?: AdvenueConfig['platform'];
+  /**
+   * @internal Storage override (tests / custom embeddings). The SDK persists
+   * via its own native modules (UserDefaults/SharedPreferences) — apps never
+   * supply storage. When set, it replaces the built-in native storage.
    */
   mmkv?: MMKVLike;
   /**
    * G3.1n — Play Integrity (Android) / App Attest (iOS) attestation.
    *
-   * Your app's Advenue appId (the UUID shown in the dashboard). When set on
-   * Android, `trackInstall()` will obtain a Play Integrity Standard token and
-   * attach it to the install event. The requestHash is computed as
+   * Your app's Advenue appId (the UUID in Settings → API Keys). When set on
+   * Android, the automatic install obtains a Play Integrity Standard token and
+   * attaches it to the install event. The requestHash is computed as
    * `sha256Hex("<appId>:<deviceId>")`, matching the server's verification
    * formula exactly (see `makeDecodeAndroid` in the worker).
    *
@@ -162,10 +206,10 @@ export interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage'> {
    */
   appId?: string;
   /**
-   * An expo-secure-store module for a reinstall-resilient device identity:
-   *   import * as SecureStore from 'expo-secure-store';
-   *   await Advenue.initialize({ apiKey, platform: 'ios', secureStore: SecureStore });
-   * Omit to fall back to sync storage (deviceId is not reinstall-resilient).
+   * @internal Secure-store override (tests / custom embeddings). The SDK uses
+   * its own Keychain-backed native storage on iOS for the reinstall-resilient
+   * device identity — apps never supply a secure store. When set, it replaces
+   * the built-in Keychain adapter.
    */
   secureStore?: SecureStoreLike;
   /**
@@ -176,6 +220,13 @@ export interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage'> {
    * to distinguish the two. Omit to disable deep-link handling entirely.
    */
   onDeepLink?: (link: DeepLink) => void;
+  /**
+   * @internal Test hook — disables the automatic install fired by
+   * `initialize()`. Install tracking is always automatic in production (there
+   * is no public `trackInstall`); tests turn it off to exercise the internal
+   * install path deterministically.
+   */
+  autoTrackInstall?: boolean;
 }
 
 /**
@@ -208,6 +259,14 @@ const INSTALL_SENT_KEY = 'advenue.install_sent';
 // Does NOT replace the durable flag (which guards across process restarts);
 // reset in shutdown() so tests and multi-lifecycle scenarios behave correctly.
 let installInFlight = false;
+// Auto-install deferral: set by initialize() when autoTrackInstall is on but the
+// consent gate (requireConsent without a grant) blocks tracking. Consumed by the
+// consent-granting paths (setTrackingConsent / requestTrackingAuthorization).
+let autoInstallPending = false;
+// Whether the current initialize() opted into auto install. Gates re-arming the
+// deferral when an in-flight install is dropped by a mid-flight consent
+// revocation — manual-mode integrators retry trackInstall() themselves.
+let autoInstallEnabled = true;
 // G3.1n: app-scoped id for attestation requestHash. Set from RNAdvenueConfig.appId
 // in initialize(). Null when the integrator has not configured attestation.
 let configuredAppId: string | null = null;
@@ -239,13 +298,58 @@ function reportError(context: string, cause: unknown): void {
   instance?.report(context, cause);
 }
 
+/**
+ * Fire-and-forget install used by the auto-install paths (initialize and the
+ * consent-granting deferral). Failures surface via diagnostics — auto tracking
+ * must never reject into the host app.
+ */
+function fireAutoInstall(): void {
+  void trackInstall().catch((err) => reportError('install.auto', err));
+}
+
+/**
+ * Resolves the event platform: an explicit config value wins; otherwise React
+ * Native's `Platform.OS` (`ios`/`android` verbatim, any other RN target →
+ * `web`). Throws outside a React Native runtime rather than guessing — a
+ * wrong-platform default would misattribute every event from the device.
+ */
+function resolvePlatform(explicit?: AdvenueConfig['platform']): AdvenueConfig['platform'] {
+  if (explicit) {
+    return explicit;
+  }
+  const os = getPlatformOS();
+  if (os === 'ios' || os === 'android') {
+    return os;
+  }
+  if (os) {
+    return 'web';
+  }
+  throw new Error(
+    "Advenue.initialize(): platform could not be detected (react-native unavailable) — pass platform: 'ios' | 'android' | 'web'.",
+  );
+}
+
+/** Consumes a pending consent-deferred auto install once consent is granted. */
+function fireAutoInstallIfPending(): void {
+  if (!autoInstallPending) {
+    return;
+  }
+  autoInstallPending = false;
+  fireAutoInstall();
+}
+
 /**
  * React Native entry point. Wires MMKV-backed offline buffering automatically
  * and re-exports the same track surface as the core SDK.
  */
 export const Advenue = {
   async initialize(config: RNAdvenueConfig): Promise<AdvenueClient> {
-    const { mmkv, secureStore: secureMod, onDeepLink, appId, ...rest } = config;
+    const { mmkv, secureStore: secureMod, onDeepLink, appId, autoTrackInstall, ...rest } = config;
+    // A deferral armed by a previous initialize() must not leak into this one —
+    // a stale pending would override this config's autoTrackInstall opt-out.
+    autoInstallPending = false;
+    autoInstallEnabled = autoTrackInstall !== false;
+    const platform = resolvePlatform(rest.platform);
     configuredAppId = appId ?? null;
     configuredApiKey = config.apiKey;
     configuredEndpoint = config.endpoint ?? DEFAULT_ENDPOINT;
@@ -254,18 +358,25 @@ export const Advenue = {
     deepLinkSub?.remove();
     deepLinkSub = null;
     instance?.shutdown();
-    const storage = mmkv ? createMMKVStorage(mmkv) : new MemoryStorage();
+    // Built-in storage: the SDK's own native modules persist state
+    // (UserDefaults/SharedPreferences + iOS Keychain, Adjust-style) — the app
+    // supplies nothing. In-memory fallback covers Expo Go / web / old natives.
+    const iosMod = getIosNative();
+    const androidMod = getAndroidNative();
+    const storage = mmkv
+      ? createMMKVStorage(mmkv)
+      : (createNativeStorage(iosMod ?? androidMod) ?? new MemoryStorage());
     installFlagStore = storage;
-    secureStore = secureMod ? createSecureStore(secureMod) : null;
+    secureStore = secureMod ? createSecureStore(secureMod) : createNativeSecureStore(iosMod);
     const deviceId =
       rest.deviceId ?? (await resolveDurableDeviceId(storage, secureStore ?? undefined));
-    instance = new AdvenueClient({ ...rest, deviceId, storage });
+    instance = new AdvenueClient({ ...rest, platform, deviceId, storage });
     // (a) resolve ad-id at init time
     void resolveAdvertisingId().catch((err) => reportError('enrich.advertisingId', err));
     // Collect native device info (Meta CAPI extinfo) once at init time; a
     // best-effort, synchronous read, so no fire-and-forget needed.
     const deviceInfo = collectDeviceInfo({
-      platform: rest.platform,
+      platform,
       ios: getIosNative(),
       android: getAndroidNative(),
     });
@@ -312,6 +423,20 @@ export const Advenue = {
             (await resolveClipboardMatch()) ?? client.resolveDeferredDeepLink(),
           onDeepLink,
         });
+        // Cold-start resolution is fire-and-forget: a failure (Linking or the
+        // deferred poll rejecting) must surface via diagnostics, never as an
+        // unhandled rejection crashing the host app.
+        deepLinkSub.ready.catch((err) => reportError('deepLink.resolve', err));
+      }
+    }
+    if (autoTrackInstall !== false) {
+      if (instance.getRequireConsent() && !instance.getTrackingConsent()) {
+        // Consent gate is closed — defer to the consent-granting paths so the
+        // install is neither dropped nor fired pre-consent.
+        autoInstallPending = true;
+      } else {
+        // Fire-and-forget: referrer/attestation resolution must not delay init.
+        fireAutoInstall();
       }
     }
     return instance;
@@ -329,227 +454,38 @@ export const Advenue = {
     active().setTrackingConsent(status === 'authorized');
     // (b) re-resolve ad-id after ATT prompt result is known
     void resolveAdvertisingId().catch((err) => reportError('enrich.advertisingId', err));
+    if (status === 'authorized') {
+      fireAutoInstallIfPending();
+    }
     return status;
   },
 
-  /**
-   * Tracks the install event enriched with native attribution data: Play +
-   * Meta install referrers on Android, SKAdNetwork registration on iOS.
-   * Safe to call on every launch — when a `secureStore` is wired it fires at
-   * most once per device (reinstall-resilient on iOS via Keychain; Android
-   * re-fires after a reinstall, which is unavoidable post-GAID).
-   */
-  async trackInstall(properties?: Record<string, unknown>): Promise<void> {
-    const client = active();
-    // Client-side dedup works even without a secure store: check the sync MMKV
-    // flag (durable across launches) AND, when wired, the secure store (durable
-    // across reinstall on iOS).
-    let sent = installFlagStore?.getItem(INSTALL_SENT_KEY) === '1';
-    if (!sent && secureStore) {
-      try {
-        sent = (await secureStore.getItemAsync(INSTALL_SENT_KEY)) === '1';
-      } catch (err) {
-        // fail-open: a missed install is worse than a duplicate
-        reportError('install.guardRead', err);
-      }
-    }
-    if (sent) {
-      return; // already counted this device (durable flag from a prior launch)
-    }
-    // C7: same-process dedup guard. If another trackInstall() call is already
-    // in-flight within this process (awaiting referrer/ad-id resolution), bail
-    // out — the first call will enqueue the install. This replaces the previous
-    // synchronous flag write which permanently suppressed the install if the
-    // process crashed before the flag was written to durable storage.
-    //
-    // Tradeoff: if the process crashes AFTER client.track() but BEFORE the
-    // durable flag write below, the next launch re-fires the install. The
-    // backend per-device dedup window absorbs the duplicate. A permanently missed
-    // install is worse than a duplicate.
-    if (installInFlight) {
-      return; // another call is already processing this install in this process
-    }
-    installInFlight = true;
-
-    const opts: { network?: string; campaign?: string; adservicesToken?: string } = {};
-    const props: Record<string, unknown> = { ...properties };
-
-    const android = getAndroidNative();
-    if (android) {
-      try {
-        const result = await android.getInstallReferrer();
-        if (result) {
-          const parsed = parseInstallReferrer(result.referrer);
-          if (parsed.network) opts.network = parsed.network;
-          if (parsed.campaign) opts.campaign = parsed.campaign;
-          if (parsed.gclid) props.gclid = parsed.gclid;
-          if (parsed.fbclid) props.fbclid = parsed.fbclid;
-          // G1: extractReferrerProperties emits both the legacy timestamp keys
-          // AND the explicit server-trusted keys (`*ServerTimestamp`) so the
-          // worker can apply the higher-trust (+0.7) click-injection weight.
-          // Both sets carry the same value — Play API timestamps are server-clock.
-          Object.assign(props, extractReferrerProperties(result));
-        }
-      } catch (err) {
-        // referrer is best-effort enrichment
-        reportError('enrich.installReferrer', err);
-      }
-      try {
-        const meta = await android.getMetaInstallReferrer();
-        const parsedMeta = meta ? parseMetaInstallReferrer(meta) : null;
-        if (parsedMeta) {
-          props.metaInstallReferrer = parsedMeta.raw;
-          if (parsedMeta.encryptedData) props.metaReferrerData = parsedMeta.encryptedData;
-          if (parsedMeta.nonce) props.metaReferrerNonce = parsedMeta.nonce;
-          if (!opts.network && parsedMeta.isClickThrough) {
-            opts.network = 'meta';
-            if (parsedMeta.campaign) opts.campaign = parsedMeta.campaign;
-          }
-        }
-      } catch (err) {
-        // best-effort
-        reportError('enrich.metaReferrer', err);
-      }
-    }
-
-    const ios = getIosNative();
-    if (ios) {
-      try {
-        ios.registerAppForAttribution();
-      } catch (err) {
-        // best-effort
-        reportError('enrich.skanRegister', err);
-      }
-      // Apple Ads AdServices attribution token (iOS 14.3+). Best-effort: a
-      // rejection (older OS / AdServices unavailable) must NOT fail the
-      // install — the token is simply omitted and attribution proceeds
-      // without it (resolved server-side against the AdServices API).
-      try {
-        const asaToken = await ios.getAttributionToken();
-        if (asaToken) {
-          opts.adservicesToken = asaToken;
-        }
-      } catch (err) {
-        reportError('enrich.adservicesToken', err);
-      }
-    }
-
-    await resolveAdvertisingId(); // ensure idfa/gaid is attached to the install event
-
-    // G3.1n — Play Integrity attestation (Android only). Best-effort: any error
-    // leaves attestation absent; the install is never blocked.
-    const trackOpts: TrackOptions = { type: 'install', ...opts };
-    if (
-      configuredAppId &&
-      android &&
-      typeof (android as { getIntegrityToken?: unknown }).getIntegrityToken === 'function'
-    ) {
-      try {
-        // requestHash = sha256_hex("<appId>:<deviceId>") — must match the server's
-        // mapIntegrityVerdict computation byte-for-byte (see makeDecodeAndroid in
-        // apps/worker/src/attestation-decoders.ts):
-        //   expectedRequestHash = sha256(`${event.appId}:${event.deviceId}`)
-        // configuredAppId must be the app's UUID from the Advenue dashboard.
-        const deviceId = client.getDeviceId();
-        const requestHash = sha256Hex(`${configuredAppId}:${deviceId}`);
-        const token = await (
-          android as { getIntegrityToken(h: string): Promise<string> }
-        ).getIntegrityToken(requestHash);
-        if (token) {
-          trackOpts.attestationToken = token;
-          trackOpts.attestationType = 'play-integrity';
-        }
-      } catch (err) {
-        // attestation is best-effort — never block the install
-        reportError('attest.playIntegrity', err);
-      }
-    }
-
-    // G3.2n — App Attest attestation (iOS only). Best-effort: any error (no
-    // support on simulator, challenge fetch failure, attest failure) leaves
-    // attestation absent; the install is NEVER blocked.
-    if (
-      configuredAppId &&
-      configuredApiKey &&
-      ios &&
-      typeof (ios as { attestKey?: unknown }).attestKey === 'function'
-    ) {
-      try {
-        // Step 1: fetch a one-time server challenge bound to this device.
-        const deviceId = client.getDeviceId();
-        const challengeUrl = `${configuredEndpoint}/v1/attest/challenge?deviceId=${encodeURIComponent(deviceId)}`;
-        const challengeRes = await fetch(challengeUrl, {
-          headers: { 'x-api-key': configuredApiKey },
-        });
-        if (!challengeRes.ok) throw new Error(`challenge HTTP ${challengeRes.status}`);
-        const { challenge } = (await challengeRes.json()) as { challenge: string };
-
-        // Step 2: call the native module (generates/reuses keychain key, attests).
-        const { keyId, attestationObject } = await (
-          ios as { attestKey(c: string): Promise<{ keyId: string; attestationObject: string }> }
-        ).attestKey(challenge);
-
-        // Step 3: attach the four G3.4-schema fields to the install event.
-        trackOpts.attestationToken = attestationObject;
-        trackOpts.attestationType = 'app-attest';
-        trackOpts.attestationKeyId = keyId;
-        trackOpts.attestationChallenge = challenge;
-      } catch (err) {
-        // fail-safe: attestation absent, install proceeds normally
-        reportError('attest.appAttest', err);
-      }
+  setTrackingConsent(granted: boolean): void {
+    active().setTrackingConsent(granted);
+    if (granted) {
+      fireAutoInstallIfPending();
     }
-
-    // G3.3n — DeviceCheck token (iOS only). Generates a per-physical-device opaque
-    // token via DCDevice.current.generateToken. The server uses it with the
-    // per-app DeviceCheck key to detect reinstall abuse (bit0 = "already produced
-    // a paid install"). Fail-safe: any error (unsupported device, simulator, native
-    // error) silently omits the token — the install is NEVER blocked.
-    if (
-      ios &&
-      typeof (ios as { getDeviceCheckToken?: unknown }).getDeviceCheckToken === 'function'
-    ) {
-      try {
-        const token = await (
-          ios as { getDeviceCheckToken(): Promise<string> }
-        ).getDeviceCheckToken();
-        if (token) {
-          trackOpts.deviceCheckToken = token;
-        }
-      } catch (err) {
-        // fail-safe: deviceCheckToken absent, install proceeds normally
-        reportError('attest.deviceCheck', err);
-      }
-    }
-
-    client.track('install', props, trackOpts);
-    // Write durable flags AFTER the install event is successfully enqueued. If
-    // the process crashes between here and the flag write, the next launch will
-    // re-fire the install — the backend per-device dedup window absorbs the
-    // duplicate. Writing the flag before enqueue (the old behavior) permanently
-    // suppressed the install on crash, which is unacceptable.
+  },
+  getTrackingConsent: () => active().getTrackingConsent(),
+  /** GDPR/CCPA erasure: stop tracking and wipe local identifiers/queue. */
+  forgetMe(): void {
+    active().forgetMe();
+    // The install guard is facade state, not client state — wipe the sync copy
+    // here so it can't diverge from the (also wiped) Keychain copy.
     try {
-      installFlagStore?.setItem(INSTALL_SENT_KEY, '1');
+      installFlagStore?.removeItem(INSTALL_SENT_KEY);
     } catch (err) {
-      // best-effort; backend per-device window dedups a re-fire
-      reportError('install.flagPersist', err);
+      reportError('forget.wipe', err);
     }
-    if (secureStore) {
-      try {
-        await secureStore.setItemAsync(INSTALL_SENT_KEY, '1');
-      } catch (err) {
-        // best-effort; backend per-device window dedups a re-fire
-        reportError('install.flagPersistSecure', err);
+    // Best-effort wipe of the reinstall-durable secure entries — without this
+    // the Keychain copy would resurrect the erased device id on next launch.
+    const secure = secureStore;
+    if (secure?.deleteItemAsync) {
+      for (const key of [DEVICE_ID_KEY, INSTALL_SENT_KEY]) {
+        void secure.deleteItemAsync(key).catch((err) => reportError('forget.secureWipe', err));
       }
     }
-    // Do NOT reset installInFlight — once-per-process is correct. The durable
-    // flag above handles cross-launch dedup; installInFlight handles same-process.
   },
-
-  setTrackingConsent: (granted: boolean) => active().setTrackingConsent(granted),
-  getTrackingConsent: () => active().getTrackingConsent(),
-  /** GDPR/CCPA erasure: stop tracking and wipe local identifiers/queue. */
-  forgetMe: () => active().forgetMe(),
   setConsentData(consent: Consent): void {
     active().setConsentData(consent);
     // (d) re-resolve ad-id after a consent change
@@ -566,9 +502,253 @@ export const Advenue = {
     instance?.shutdown();
     instance = null;
     secureStore = null;
-    installInFlight = false; // reset so re-initialize + trackInstall works correctly
+    installInFlight = false; // reset so re-initialize works correctly
+    autoInstallPending = false;
+    autoInstallEnabled = true;
     configuredAppId = null;
     configuredApiKey = null;
     configuredEndpoint = DEFAULT_ENDPOINT;
   },
 };
+
+/**
+ * Tracks the install event enriched with native attribution data: Play + Meta
+ * install referrers on Android, SKAdNetwork registration on iOS. Fired
+ * automatically by `initialize()` (or its consent deferral); when a
+ * `secureStore` is wired it fires at most once per device (reinstall-resilient
+ * on iOS via Keychain; Android re-fires after a reinstall, which is
+ * unavoidable post-GAID).
+ *
+ * @internal Exported for tests only — install tracking is automatic and this
+ * function is deliberately NOT on the `Advenue` facade. Do not call it from
+ * app code.
+ */
+export async function trackInstall(): Promise<void> {
+  const client = active();
+  // Consent gate: client.track() would silently drop the event, but the
+  // durable flag below would still be written — permanently losing the
+  // install. Bail before any side effect; the caller (or the auto-install
+  // deferral) retries after consent is granted.
+  if (client.getRequireConsent() && !client.getTrackingConsent()) {
+    return;
+  }
+  // Client-side dedup works even without a secure store: check the sync MMKV
+  // flag (durable across launches) AND, when wired, the secure store (durable
+  // across reinstall on iOS).
+  let sent = installFlagStore?.getItem(INSTALL_SENT_KEY) === '1';
+  if (!sent && secureStore) {
+    try {
+      sent = (await secureStore.getItemAsync(INSTALL_SENT_KEY)) === '1';
+    } catch (err) {
+      // fail-open: a missed install is worse than a duplicate
+      reportError('install.guardRead', err);
+    }
+  }
+  if (sent) {
+    return; // already counted this device (durable flag from a prior launch)
+  }
+  // C7: same-process dedup guard. If another trackInstall() call is already
+  // in-flight within this process (awaiting referrer/ad-id resolution), bail
+  // out — the first call will enqueue the install. This replaces the previous
+  // synchronous flag write which permanently suppressed the install if the
+  // process crashed before the flag was written to durable storage.
+  //
+  // Tradeoff: if the process crashes AFTER client.track() but BEFORE the
+  // durable flag write below, the next launch re-fires the install. The
+  // backend per-device dedup window absorbs the duplicate. A permanently missed
+  // install is worse than a duplicate.
+  if (installInFlight) {
+    return; // another call is already processing this install in this process
+  }
+  installInFlight = true;
+
+  const opts: { network?: string; campaign?: string; adservicesToken?: string } = {};
+  const props: Record<string, unknown> = {};
+
+  const android = getAndroidNative();
+  if (android) {
+    try {
+      const result = await android.getInstallReferrer();
+      if (result) {
+        const parsed = parseInstallReferrer(result.referrer);
+        if (parsed.network) opts.network = parsed.network;
+        if (parsed.campaign) opts.campaign = parsed.campaign;
+        if (parsed.gclid) props.gclid = parsed.gclid;
+        if (parsed.fbclid) props.fbclid = parsed.fbclid;
+        // G1: extractReferrerProperties always forwards the device-clock keys
+        // (referrerClickTimestamp/installBeginTimestamp → referrerTrust:'client')
+        // and, ONLY when Play returned non-zero server-clock values, the
+        // server-trusted `*ServerTimestamp` keys (referrerTrust:'server', +0.7).
+        // Device-clock values are never aliased into the server keys.
+        Object.assign(props, extractReferrerProperties(result));
+      }
+    } catch (err) {
+      // referrer is best-effort enrichment
+      reportError('enrich.installReferrer', err);
+    }
+    try {
+      const meta = await android.getMetaInstallReferrer();
+      const parsedMeta = meta ? parseMetaInstallReferrer(meta) : null;
+      if (parsedMeta) {
+        props.metaInstallReferrer = parsedMeta.raw;
+        if (parsedMeta.encryptedData) props.metaReferrerData = parsedMeta.encryptedData;
+        if (parsedMeta.nonce) props.metaReferrerNonce = parsedMeta.nonce;
+        if (!opts.network && parsedMeta.isClickThrough) {
+          opts.network = 'meta';
+          if (parsedMeta.campaign) opts.campaign = parsedMeta.campaign;
+        }
+      }
+    } catch (err) {
+      // best-effort
+      reportError('enrich.metaReferrer', err);
+    }
+  }
+
+  const ios = getIosNative();
+  if (ios) {
+    try {
+      ios.registerAppForAttribution();
+    } catch (err) {
+      // best-effort
+      reportError('enrich.skanRegister', err);
+    }
+    // Apple Ads AdServices attribution token (iOS 14.3+). Best-effort: a
+    // rejection (older OS / AdServices unavailable) must NOT fail the
+    // install — the token is simply omitted and attribution proceeds
+    // without it (resolved server-side against the AdServices API).
+    try {
+      const asaToken = await ios.getAttributionToken();
+      if (asaToken) {
+        opts.adservicesToken = asaToken;
+      }
+    } catch (err) {
+      reportError('enrich.adservicesToken', err);
+    }
+  }
+
+  await resolveAdvertisingId(); // ensure idfa/gaid is attached to the install event
+
+  // G3.1n — Play Integrity attestation (Android only). Best-effort: any error
+  // leaves attestation absent; the install is never blocked.
+  const trackOpts: TrackOptions = { type: 'install', ...opts };
+  if (
+    configuredAppId &&
+    android &&
+    typeof (android as { getIntegrityToken?: unknown }).getIntegrityToken === 'function'
+  ) {
+    try {
+      // requestHash = sha256_hex("<appId>:<deviceId>") — must match the server's
+      // mapIntegrityVerdict computation byte-for-byte (see makeDecodeAndroid in
+      // apps/worker/src/attestation-decoders.ts):
+      //   expectedRequestHash = sha256(`${event.appId}:${event.deviceId}`)
+      // configuredAppId must be the app's UUID from the Advenue dashboard.
+      const deviceId = client.getDeviceId();
+      const requestHash = sha256Hex(`${configuredAppId}:${deviceId}`);
+      const token = await (
+        android as { getIntegrityToken(h: string): Promise<string> }
+      ).getIntegrityToken(requestHash);
+      if (token) {
+        trackOpts.attestationToken = token;
+        trackOpts.attestationType = 'play-integrity';
+      }
+    } catch (err) {
+      // attestation is best-effort — never block the install
+      reportError('attest.playIntegrity', err);
+    }
+  }
+
+  // G3.2n — App Attest attestation (iOS only). Best-effort: any error (no
+  // support on simulator, challenge fetch failure, attest failure) leaves
+  // attestation absent; the install is NEVER blocked.
+  if (
+    configuredAppId &&
+    configuredApiKey &&
+    ios &&
+    typeof (ios as { attestKey?: unknown }).attestKey === 'function'
+  ) {
+    try {
+      // Step 1: fetch a one-time server challenge bound to this device.
+      const deviceId = client.getDeviceId();
+      const challengeUrl = `${configuredEndpoint}/v1/attest/challenge?deviceId=${encodeURIComponent(deviceId)}`;
+      const challengeRes = await fetch(challengeUrl, {
+        headers: { 'x-api-key': configuredApiKey },
+      });
+      if (!challengeRes.ok) throw new Error(`challenge HTTP ${challengeRes.status}`);
+      const { challenge } = (await challengeRes.json()) as { challenge: string };
+
+      // Step 2: call the native module (generates/reuses keychain key, attests).
+      const { keyId, attestationObject } = await (
+        ios as { attestKey(c: string): Promise<{ keyId: string; attestationObject: string }> }
+      ).attestKey(challenge);
+
+      // Step 3: attach the four G3.4-schema fields to the install event.
+      trackOpts.attestationToken = attestationObject;
+      trackOpts.attestationType = 'app-attest';
+      trackOpts.attestationKeyId = keyId;
+      trackOpts.attestationChallenge = challenge;
+    } catch (err) {
+      // fail-safe: attestation absent, install proceeds normally
+      reportError('attest.appAttest', err);
+    }
+  }
+
+  // G3.3n — DeviceCheck token (iOS only). Generates a per-physical-device opaque
+  // token via DCDevice.current.generateToken. The server uses it with the
+  // per-app DeviceCheck key to detect reinstall abuse (bit0 = "already produced
+  // a paid install"). Fail-safe: any error (unsupported device, simulator, native
+  // error) silently omits the token — the install is NEVER blocked.
+  if (ios && typeof (ios as { getDeviceCheckToken?: unknown }).getDeviceCheckToken === 'function') {
+    try {
+      const token = await (ios as { getDeviceCheckToken(): Promise<string> }).getDeviceCheckToken();
+      if (token) {
+        trackOpts.deviceCheckToken = token;
+      }
+    } catch (err) {
+      // fail-safe: deviceCheckToken absent, install proceeds normally
+      reportError('attest.deviceCheck', err);
+    }
+  }
+
+  // The gate was open at entry, but the enrichment awaits above leave a
+  // window where consent can be revoked (e.g. CMP grant → ATT deny) or
+  // forgetMe() can run — client.track() then silently drops the event.
+  // Enqueue-confirm via the synchronous pendingCount delta (enqueue is sync;
+  // a flush can only ack after its transport await) so a dropped install
+  // never burns the durable flag. Known edge: at the queue's hard cap,
+  // enqueue evicts the head so the delta reads 0 for an event that WAS
+  // enqueued — the flag stays unwritten and the next launch re-fires, which
+  // the backend per-device guard dedups. Duplicate over lost, by design.
+  const pendingBefore = client.pendingCount;
+  client.track('install', props, trackOpts);
+  if (client.pendingCount === pendingBefore) {
+    // Dropped. Allow a same-process retry, and re-arm the auto deferral when
+    // the drop was the consent gate closing (not erasure) so a later grant
+    // re-fires without waiting for the next launch.
+    installInFlight = false;
+    if (autoInstallEnabled && client.getRequireConsent() && !client.getTrackingConsent()) {
+      autoInstallPending = true;
+    }
+    return;
+  }
+  // Write durable flags AFTER the install event is successfully enqueued. If
+  // the process crashes between here and the flag write, the next launch will
+  // re-fire the install — the backend per-device dedup window absorbs the
+  // duplicate. Writing the flag before enqueue (the old behavior) permanently
+  // suppressed the install on crash, which is unacceptable.
+  try {
+    installFlagStore?.setItem(INSTALL_SENT_KEY, '1');
+  } catch (err) {
+    // best-effort; backend per-device window dedups a re-fire
+    reportError('install.flagPersist', err);
+  }
+  if (secureStore) {
+    try {
+      await secureStore.setItemAsync(INSTALL_SENT_KEY, '1');
+    } catch (err) {
+      // best-effort; backend per-device window dedups a re-fire
+      reportError('install.flagPersistSecure', err);
+    }
+  }
+  // Do NOT reset installInFlight — once-per-process is correct. The durable
+  // flag above handles cross-launch dedup; installInFlight handles same-process.
+}