@advenue/react-native 0.7.0 → 0.9.0

package/src/index.ts

@@ -16,9 +16,11 @@ import {
   type StorageAdapter,
   type TrackOptions,
   resolveDurableDeviceId,
+  tcfToConsent,
 } from '@advenue/sdk-core';
 import { sha256Hex } from '@advenue/signing';
 import pkg from '../package.json' with { type: 'json' };
+import { extractAemCampaignIds } from './aem';
 import { type DeepLinkHandle, setupDeepLinks } from './deep-links';
 import { type MMKVLike, createMMKVStorage } from './mmkv-storage';
 import {
@@ -47,6 +49,7 @@ export type {
   AdvenueIosNativeModule,
   InstallReferrerResult,
   MetaInstallReferrerResult,
+  NativeTcfData,
   TrackingAuthorizationStatus,
 } from './native-types';
 
@@ -122,6 +125,50 @@ export async function resolveAdvertisingId(): Promise<void> {
   client.setAdvertisingId({});
 }
 
+/** Field-wise equality for the small, flat Consent shape. */
+function consentEquals(a: Consent, b: Consent): boolean {
+  return (
+    a.isUserSubjectToGDPR === b.isUserSubjectToGDPR &&
+    a.hasConsentForDataUsage === b.hasConsentForDataUsage &&
+    a.hasConsentForAdsPersonalization === b.hasConsentForAdsPersonalization &&
+    a.hasConsentForAdStorage === b.hasConsentForAdStorage
+  );
+}
+
+/**
+ * Reads IAB TCF v2 consent (written by a TCF-compliant CMP, e.g. Google UMP,
+ * to the platform default store), maps it to the DMA Consent shape, and
+ * pushes it into the active client. No-op — returning null — when consent was
+ * set manually this session, the native module or its getter is absent, no
+ * TCF data exists, or the freshly-mapped consent is identical to what the
+ * client already has (skip-if-unchanged: avoids re-persisting to storage and
+ * re-firing the ad-id resolve on every foreground when nothing changed):
+ * absent/unchanged consent must stay untouched, never fabricated or re-churned.
+ *
+ * Must be called after `Advenue.initialize()` — like every facade method, it
+ * throws via the uninitialized guard otherwise.
+ */
+export function resolveDmaConsent(): Consent | null {
+  if (manualConsentSet) return null;
+  const native = getIosNative() ?? getAndroidNative();
+  if (!native || typeof native.getTcfData !== 'function') return null;
+  let consent: Consent | null = null;
+  try {
+    consent = tcfToConsent(native.getTcfData());
+  } catch (err) {
+    reportError('consent.tcfRead', err);
+    return null;
+  }
+  if (!consent) return null;
+  const client = active();
+  const current = client.getConsentData();
+  if (current && consentEquals(current, consent)) return null;
+  client.setConsentData(consent);
+  // Consent feeds the ad-id gate — re-resolve, same as manual setConsentData.
+  void resolveAdvertisingId().catch((err) => reportError('enrich.advertisingId', err));
+  return consent;
+}
+
 /**
  * Collects native device metadata (model, locale, screen, cpu, storage, timezone)
  * used to populate Meta CAPI `extinfo`. Reads from the platform-appropriate
@@ -131,11 +178,18 @@ export async function resolveAdvertisingId(): Promise<void> {
  * native-side error degrades to an empty object so callers can unconditionally
  * pass the result through.
  */
-export function collectDeviceInfo(natives: {
+type NativeDeviceInfo = Partial<DeviceInfo> & { shortVersion?: string };
+
+type DeviceInfoNatives = {
   platform: 'ios' | 'android' | string;
-  ios?: { getDeviceInfo?: () => Partial<DeviceInfo> } | null;
-  android?: { getDeviceInfo?: () => Partial<DeviceInfo> } | null;
-}): DeviceInfo {
+  ios?: { getDeviceInfo?: () => NativeDeviceInfo } | null;
+  android?: { getDeviceInfo?: () => NativeDeviceInfo } | null;
+};
+
+/** The raw native map, `shortVersion` included. Internal: `initialize` needs
+ *  that field for the event's top-level `appVersion`, everyone else wants the
+ *  deviceInfo blob that `collectDeviceInfo` returns. */
+function readNativeDeviceInfo(natives: DeviceInfoNatives): NativeDeviceInfo {
   try {
     if (natives.platform === 'android' && natives.android?.getDeviceInfo) {
       return natives.android.getDeviceInfo();
@@ -149,6 +203,13 @@ export function collectDeviceInfo(natives: {
   return {};
 }
 
+export function collectDeviceInfo(natives: DeviceInfoNatives): DeviceInfo {
+  // shortVersion is the app's own version, carried by the event's `appVersion`
+  // field (extinfo slot 2) — it is not part of the persisted deviceInfo blob.
+  const { shortVersion: _shortVersion, ...info } = readNativeDeviceInfo(natives);
+  return info;
+}
+
 export interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage' | 'platform'> {
   /**
    * Auto-detected from React Native's `Platform.OS` — omit it. Pass explicitly
@@ -163,18 +224,6 @@ export interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage' | 'platfo
    * 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 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).
-   *
-   * Omit to run without attestation (the server field stays `unavailable`).
-   */
-  appId?: string;
   /**
    * @internal Secure-store override (tests / custom embeddings). The SDK uses
    * its own Keychain-backed native storage on iOS for the reinstall-resilient
@@ -197,6 +246,14 @@ export interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage' | 'platfo
    * install path deterministically.
    */
   autoTrackInstall?: boolean;
+  /**
+   * Auto-collect IAB TCF v2 consent written by a TCF-compliant CMP (e.g.
+   * Google UMP) and attach it to every event as DMA consent data (AppsFlyer
+   * `enableTCFDataCollection` parity). Read at init and re-read on each
+   * foreground, so a CMP decision made after startup lands on later events.
+   * A manual `setConsentData()` call always wins. Default false.
+   */
+  tcfDataCollection?: boolean;
 }
 
 /**
@@ -237,9 +294,17 @@ let autoInstallPending = false;
 // 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;
+// D5: an explicit setConsentData() call disables auto-TCF application for the
+// rest of the session (AppsFlyer semantics: manual wins). Reset by
+// initialize()/shutdown().
+let manualConsentSet = false;
+// Whether the current initialize() opted into TCF auto-collection
+// (RNAdvenueConfig.tcfDataCollection). Reset by initialize()/shutdown().
+let tcfCollectionEnabled = false;
+/** Deadline for the App Attest challenge fetch. Enrichment on the install path:
+ *  bounded well under the transport's 15s so a slow host costs the install a
+ *  moment, never the platform socket timeout. */
+const ATTEST_CHALLENGE_TIMEOUT_MS = 5_000;
 // G3.2n: API key + endpoint needed to fetch the App Attest challenge from the
 // server. Stored at module level so trackInstall() can issue the challenge
 // request without reaching into the private AdvenueClient fields.
@@ -251,6 +316,12 @@ let configuredAppId: string | null = null;
 // attestation silently never works.
 let configuredApiKey: string | null = null;
 let configuredEndpoint = DEFAULT_ENDPOINT;
+// Meta AEM campaign_ids capture: per-process dedup so a URL delivered twice in
+// one open (cold-start + a redundant warm listener re-delivery) enqueues only
+// one adv_meta_aem event. Keyed on the sourceUrlHash (sha256 of the raw URL),
+// not the campaign_ids blob, so two distinct URLs carrying the same blob
+// still each get their own event. Cleared in shutdown().
+const aemSeenUrlHashes = new Set<string>();
 
 function active(): AdvenueClient {
   if (!instance) {
@@ -314,13 +385,21 @@ function fireAutoInstallIfPending(): void {
  */
 export const Advenue = {
   async initialize(config: RNAdvenueConfig): Promise<AdvenueClient> {
-    const { mmkv, secureStore: secureMod, onDeepLink, appId, autoTrackInstall, ...rest } = config;
+    const {
+      mmkv,
+      secureStore: secureMod,
+      onDeepLink,
+      autoTrackInstall,
+      tcfDataCollection,
+      ...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;
+    manualConsentSet = false;
+    tcfCollectionEnabled = tcfDataCollection === true;
     autoInstallEnabled = autoTrackInstall !== false;
     const platform = resolvePlatform(rest.platform);
-    configuredAppId = appId ?? null;
     configuredApiKey = config.apiKey;
     configuredEndpoint = config.endpoint ?? DEFAULT_ENDPOINT;
     appStateSub?.remove();
@@ -343,25 +422,38 @@ export const Advenue = {
     // Auto-collect the OS release version — it feeds the server's normalized
     // probabilistic fingerprint (spec D1); an explicit config value wins.
     const osVersion = rest.osVersion ?? getOsVersion() ?? undefined;
+    // Native device metadata (Meta CAPI extinfo) — read BEFORE the client is
+    // constructed because the app's short version becomes the event's
+    // `appVersion`, which the client takes at construction time. Best-effort
+    // and synchronous, so no fire-and-forget needed.
+    const nativeDeviceInfo = readNativeDeviceInfo({
+      platform,
+      ios: getIosNative(),
+      android: getAndroidNative(),
+    });
+    const { shortVersion, ...deviceInfo } = nativeDeviceInfo;
+    // Same contract as osVersion: the config wins, the platform fills the gap.
+    // Without this fallback nothing ever set it — every event, and every
+    // device_profiles row, recorded an empty app version.
+    const appVersion = rest.appVersion ?? shortVersion ?? undefined;
     instance = new AdvenueClient({
       ...rest,
       platform,
       deviceId,
       storage,
       ...(osVersion ? { osVersion } : {}),
+      ...(appVersion ? { appVersion } : {}),
+      // Stamped by the SDK, never by the host app — see AdvenueConfig.sdkVersion.
+      sdkVersion: pkg.version,
     });
     // One-line ground truth for "which SDK build talks to which host" — the
     // exact questions a silent integration always raises first.
     instance.debugLog(`SDK v${pkg.version} — events -> ${configuredEndpoint}`);
+    // TCF auto-collection (opt-in): populate DMA consent before the ad-id
+    // resolve below and before any event is enqueued.
+    if (tcfCollectionEnabled) resolveDmaConsent();
     // (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,
-      ios: getIosNative(),
-      android: getAndroidNative(),
-    });
     if (Object.keys(deviceInfo).length > 0) instance.setDeviceInfo(deviceInfo);
     if (!config.disableAutoSessions) {
       const appState = getAppState();
@@ -377,10 +469,21 @@ export const Advenue = {
           if (!instance) return;
           if (status === 'background') {
             seenBackground = true;
+            // The CMP dialog usually completes mid-foreground, so the
+            // background flush is the first moment that decision can leave
+            // the device — refresh TCF consent BEFORE applyAppState()
+            // enqueues session_end, so it ships with the flush rather than
+            // one session late.
+            if (tcfCollectionEnabled) resolveDmaConsent();
             applyAppState(instance, status);
           } else if (status === 'active') {
             if (!seenBackground) return; // suppress: platform initial 'active' after cold-start
             seenBackground = false;
+            // CMP dialogs usually complete after init — refresh TCF consent
+            // BEFORE applyAppState() enqueues session_start, so that event (and
+            // the ad-id re-resolve below) see the up-to-date consent instead of
+            // a stale snapshot from before the CMP decision changed.
+            if (tcfCollectionEnabled) resolveDmaConsent();
             applyAppState(instance, status);
             // (c) re-resolve ad-id on foreground (after a real background→active transition)
             void resolveAdvertisingId().catch((err) => reportError('enrich.advertisingId', err));
@@ -392,7 +495,12 @@ export const Advenue = {
         instance.notifyAppActive(); // non-RN / test env fallback
       }
     }
-    if (onDeepLink) {
+    {
+      // The OS-link listener is set up unconditionally — Meta AEM capture
+      // (onDirectUrl below) must run regardless of whether the integrator
+      // wants navigation callbacks; the old `if (onDeepLink)` gate silently
+      // disabled capture whenever onDeepLink was omitted. `onDeepLink` itself
+      // stays optional: a no-op stands in when the integrator didn't pass one.
       const linking = getLinking();
       if (linking) {
         const client = instance;
@@ -402,7 +510,24 @@ export const Advenue = {
           // Deferred deep link: server-side conversion poll (deterministic ids
           // where available, probabilistic otherwise).
           resolveDeferred: () => client.resolveDeferredDeepLink(),
-          onDeepLink,
+          onDeepLink: onDeepLink ?? (() => {}),
+          onDirectUrl: (url, link) => {
+            const raw = link.params?.al_applink_data;
+            if (typeof raw !== 'string') return;
+            const campaignIds = extractAemCampaignIds(raw);
+            if (!campaignIds) return;
+            const sourceUrlHash = sha256Hex(url);
+            // Cold-start + warm-listener can deliver the same URL twice in
+            // one open — one marker per distinct URL per process.
+            if (aemSeenUrlHashes.has(sourceUrlHash)) return;
+            // Consent gate closed: client.track() silently drops the event.
+            // Don't burn the dedup slot on a URL that never actually got
+            // enqueued — otherwise it could never fire even after consent is
+            // later granted. Mirrors the auto-install consent gate check.
+            if (client.getRequireConsent() && !client.getTrackingConsent()) return;
+            client.track('adv_meta_aem', { campaignIds, sourceUrlHash });
+            aemSeenUrlHashes.add(sourceUrlHash);
+          },
         });
         // Cold-start resolution is fire-and-forget: a failure (Linking or the
         // deferred poll rejecting) must surface via diagnostics, never as an
@@ -469,6 +594,7 @@ export const Advenue = {
     }
   },
   setConsentData(consent: Consent): void {
+    manualConsentSet = true;
     active().setConsentData(consent);
     // (d) re-resolve ad-id after a consent change
     void resolveAdvertisingId().catch((err) => reportError('enrich.advertisingId', err));
@@ -476,6 +602,11 @@ export const Advenue = {
   getConsentData: () => active().getConsentData(),
   flush: () => active().flush(),
   getDeviceId: () => active().getDeviceId(),
+  /** The Advenue ID — alias of getDeviceId (see AdvenueClient.getAdvenueId). */
+  getAdvenueId: () => active().getAdvenueId(),
+  /** Which app the server resolved this API key to; null until a batch lands
+   *  (see AdvenueClient.getResolvedAppId). */
+  getResolvedAppId: () => active().getResolvedAppId(),
   shutdown() {
     appStateSub?.remove();
     appStateSub = null;
@@ -487,9 +618,11 @@ export const Advenue = {
     installInFlight = false; // reset so re-initialize works correctly
     autoInstallPending = false;
     autoInstallEnabled = true;
-    configuredAppId = null;
+    manualConsentSet = false;
+    tcfCollectionEnabled = false;
     configuredApiKey = null;
     configuredEndpoint = DEFAULT_ENDPOINT;
+    aemSeenUrlHashes.clear();
   },
 };
 
@@ -615,18 +748,20 @@ export async function trackInstall(): Promise<void> {
   // 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
+      // requestHash = sha256_hex("<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.
+      //   expectedRequestHash = sha256(event.deviceId)
+      // No app id is hashed in, deliberately: the token is already decoded
+      // against the app's Play package name and must be PLAY_RECOGNIZED, which
+      // binds the app more tightly than an internal UUID could — and it keeps
+      // the API key as the SDK's only app identity.
       const deviceId = client.getDeviceId();
-      const requestHash = sha256Hex(`${configuredAppId}:${deviceId}`);
+      const requestHash = sha256Hex(deviceId);
       const token = await (
         android as { getIntegrityToken(h: string): Promise<string> }
       ).getIntegrityToken(requestHash);
@@ -643,19 +778,32 @@ export async function trackInstall(): Promise<void> {
   // 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'
-  ) {
+  if (configuredApiKey && ios && typeof (ios as { attestKey?: unknown }).attestKey === 'function') {
     try {
       // Step 1: fetch a one-time server challenge bound to this device.
+      //
+      // Deadline-bounded, like every other SDK fetch (see sdk-core transport):
+      // the install event is only enqueued after this await, and attestation is
+      // attempted on every install — so an unreachable or hung host would
+      // otherwise delay the install by the platform socket timeout, shifting the
+      // recorded install time and the deferred deep link the user is waiting on.
+      // Shorter than the transport's 15s: this is enrichment, not the payload.
       const deviceId = client.getDeviceId();
       const challengeUrl = `${configuredEndpoint}/v1/attest/challenge?deviceId=${encodeURIComponent(deviceId)}`;
-      const challengeRes = await fetch(challengeUrl, {
-        headers: { 'x-api-key': configuredApiKey },
-      });
+      const ac = new AbortController();
+      const timer = setTimeout(
+        () => ac.abort(new Error('attest challenge timed out')),
+        ATTEST_CHALLENGE_TIMEOUT_MS,
+      );
+      let challengeRes: Response;
+      try {
+        challengeRes = await fetch(challengeUrl, {
+          headers: { 'x-api-key': configuredApiKey },
+          signal: ac.signal,
+        });
+      } finally {
+        clearTimeout(timer);
+      }
       if (!challengeRes.ok) throw new Error(`challenge HTTP ${challengeRes.status}`);
       const { challenge } = (await challengeRes.json()) as { challenge: string };
 

package/src/native-types.ts

@@ -35,6 +35,14 @@ export interface MetaInstallReferrerResult {
  * real `DeviceInfo` shape.
  */
 export interface AdvenueDeviceInfo {
+  /** Bundle id / package name — Meta CAPI extinfo slot 1. */
+  packageName?: string;
+  /** User-facing app version (CFBundleShortVersionString / versionName) —
+   *  extinfo slot 2. Surfaced as the event's top-level `appVersion`, not as
+   *  part of the deviceInfo blob. */
+  shortVersion?: string;
+  /** Build identifier (CFBundleVersion / versionCode) — extinfo slot 3. */
+  longVersion?: string;
   model?: string;
   locale?: string;
   carrier?: string;
@@ -47,6 +55,17 @@ export interface AdvenueDeviceInfo {
   freeStorageGb?: number;
 }
 
+/**
+ * Raw IAB TCF v2 CMP values from the platform default store
+ * (`UserDefaults.standard` / default SharedPreferences) — where TCF-compliant
+ * CMPs (e.g. Google UMP) write `IABTCF_*` keys. Structurally mirrors
+ * `TcfData` from `@advenue/sdk-core`.
+ */
+export interface NativeTcfData {
+  gdprApplies?: number | null;
+  purposeConsents?: string | null;
+}
+
 export interface AdvenueAndroidNativeModule {
   /** Raw Play Install Referrer; parse with @advenue/install-referrer. */
   getInstallReferrer(): Promise<InstallReferrerResult | null>;
@@ -62,9 +81,11 @@ export interface AdvenueAndroidNativeModule {
   /**
    * Play Integrity Standard API token (G3.1n).
    *
-   * `requestHash` MUST be sha256_hex("<appId>:<deviceId>") — lowercase hex SHA-256
-   * of the literal string "<appId>:<deviceId>". The server's mapIntegrityVerdict
-   * re-derives the same string and compares it byte-for-byte.
+   * `requestHash` MUST be sha256_hex("<deviceId>") — lowercase hex SHA-256 of the
+   * device id alone. The server's mapIntegrityVerdict re-derives the same string
+   * and compares it byte-for-byte. No app id is hashed in: the token is decoded
+   * against the app's Play package name and must be PLAY_RECOGNIZED, which binds
+   * the app already.
    *
    * Rejects when:
    *  - ECONFIG: `io.advenue.INTEGRITY_CLOUD_PROJECT_NUMBER` meta-data is absent.
@@ -101,6 +122,12 @@ export interface AdvenueAndroidNativeModule {
    * policy). Optional: absent on older native builds; feature-detected.
    */
   getAndroidId?(): string | null;
+  /**
+   * IAB TCF v2 CMP data, null when no CMP has written TCF keys. Optional:
+   * older native builds lack it — callers feature-detect (getAndroidId
+   * precedent).
+   */
+  getTcfData?(): NativeTcfData | null;
 }
 
 export type TrackingAuthorizationStatus = 'notDetermined' | 'restricted' | 'denied' | 'authorized';
@@ -164,4 +191,10 @@ export interface AdvenueIosNativeModule {
   secureGetItem?(key: string): string | null;
   secureSetItem?(key: string, value: string): void;
   secureRemoveItem?(key: string): void;
+  /**
+   * IAB TCF v2 CMP data, null when no CMP has written TCF keys. Optional:
+   * older native builds lack it — callers feature-detect (getAndroidId
+   * precedent).
+   */
+  getTcfData?(): NativeTcfData | null;
 }