@advenue/react-native 0.7.0 → 0.8.0

package/README.md

@@ -33,6 +33,11 @@ await Advenue.initialize({
 Advenue.track('signup_completed', { plan: 'pro' });
 ```
 
+> The `adv_` event-name prefix (e.g. `adv_meta_aem`) is reserved for
+> Advenue-internal signals — don't name your own custom events with it. Such
+> events are still accepted by `track()` (the pipeline relies on them) but are
+> hidden from analytics surfaces like the dashboard's funnel event picker.
+
 ## Deep links (Universal Links / App Links)
 
 Add the config plugin so install-time deep links resolve on device:

package/android/src/main/java/expo/modules/advenue/AdvenueAndroidModule.kt

@@ -327,6 +327,29 @@ class AdvenueAndroidModule : Module() {
       sdkPrefs()?.edit()?.remove(key)?.apply()
     }
 
+    // IAB TCF v2 data a TCF-compliant CMP (e.g. Google UMP) writes to the
+    // *default* SharedPreferences ("<package>_preferences", per the TCF spec) —
+    // deliberately not our io.advenue.sdk file. Raw values pass through; the
+    // TS side (tcfToConsent) owns the policy mapping.
+    Function("getTcfData") { ->
+      val ctx = appContext.reactContext?.applicationContext ?: return@Function null
+      val prefs = ctx.getSharedPreferences(
+        "${ctx.packageName}_preferences", android.content.Context.MODE_PRIVATE
+      )
+      // prefs.all + map lookup: a missing key reads as null (no default value
+      // involved), so "missing" and "0" stay distinguishable. `as? Number`
+      // tolerates a CMP writing the value as Int OR Long (SharedPreferences
+      // has no fixed numeric type per the TCF spec's own contract) without
+      // degrading a Long writer to unknown. runCatching stays as the
+      // last-resort crash guard.
+      val gdprApplies = runCatching {
+        (prefs.all["IABTCF_gdprApplies"] as? Number)?.toInt()
+      }.getOrNull()
+      val purposeConsents = runCatching { prefs.getString("IABTCF_PurposeConsents", null) }.getOrNull()
+      if (gdprApplies == null && purposeConsents == null) return@Function null
+      mapOf("gdprApplies" to gdprApplies, "purposeConsents" to purposeConsents)
+    }
+
     // SSAID (ANDROID_ID): signing-key-scoped, stable across reinstalls, reset
     // only by factory reset. Read by the JS facade ONLY when no usable GAID
     // exists, as a first-party fraud/dedup + reinstall-detection signal (Play

package/dist/index.cjs

@@ -63,6 +63,7 @@ __export(index_exports, {
   getIosNative: () => getIosNative,
   parseDirectLink: () => parseDirectLink,
   resolveAdvertisingId: () => resolveAdvertisingId,
+  resolveDmaConsent: () => resolveDmaConsent,
   trackInstall: () => trackInstall
 });
 module.exports = __toCommonJS(index_exports);
@@ -221,7 +222,7 @@ function sha256Hex(message) {
 // package.json
 var package_default = {
   name: "@advenue/react-native",
-  version: "0.7.0",
+  version: "0.8.0",
   description: "Advenue MMP React Native SDK \u2014 attribution, install tracking, and deep links (bundled iOS/Android Expo native modules)",
   type: "module",
   license: "MIT",
@@ -282,6 +283,17 @@ var package_default = {
   "react-native": "./dist/index.cjs"
 };
 
+// src/aem.ts
+function extractAemCampaignIds(alApplinkData) {
+  try {
+    const parsed = JSON.parse(alApplinkData);
+    const value = typeof parsed.campaign_ids === "string" && parsed.campaign_ids ? parsed.campaign_ids : typeof parsed.extras?.campaign_ids === "string" && parsed.extras.campaign_ids ? parsed.extras.campaign_ids : null;
+    return value && value.length <= 2048 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
 // src/deep-links.ts
 function parseDirectLink(url) {
   let deepLinkValue = "";
@@ -307,11 +319,16 @@ function parseDirectLink(url) {
   };
 }
 function setupDeepLinks(setup) {
-  const listener = setup.addUrlListener((url) => setup.onDeepLink(parseDirectLink(url)));
+  const deliverDirect = (url) => {
+    const link = parseDirectLink(url);
+    setup.onDirectUrl?.(url, link);
+    setup.onDeepLink(link);
+  };
+  const listener = setup.addUrlListener(deliverDirect);
   const ready = (async () => {
     const initial = await setup.getInitialURL();
     if (initial) {
-      setup.onDeepLink(parseDirectLink(initial));
+      deliverDirect(initial);
       return;
     }
     const deferred = await setup.resolveDeferred();
@@ -458,6 +475,28 @@ async function resolveAdvertisingId() {
   }
   client.setAdvertisingId({});
 }
+function consentEquals(a, b) {
+  return a.isUserSubjectToGDPR === b.isUserSubjectToGDPR && a.hasConsentForDataUsage === b.hasConsentForDataUsage && a.hasConsentForAdsPersonalization === b.hasConsentForAdsPersonalization && a.hasConsentForAdStorage === b.hasConsentForAdStorage;
+}
+function resolveDmaConsent() {
+  if (manualConsentSet) return null;
+  const native = getIosNative() ?? getAndroidNative();
+  if (!native || typeof native.getTcfData !== "function") return null;
+  let consent = null;
+  try {
+    consent = (0, import_sdk_core.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);
+  void resolveAdvertisingId().catch((err) => reportError("enrich.advertisingId", err));
+  return consent;
+}
 function collectDeviceInfo(natives) {
   try {
     if (natives.platform === "android" && natives.android?.getDeviceInfo) {
@@ -486,9 +525,12 @@ var INSTALL_SENT_KEY = "advenue.install_sent";
 var installInFlight = false;
 var autoInstallPending = false;
 var autoInstallEnabled = true;
+var manualConsentSet = false;
+var tcfCollectionEnabled = false;
 var configuredAppId = null;
 var configuredApiKey = null;
 var configuredEndpoint = import_sdk_core.DEFAULT_ENDPOINT;
+var aemSeenUrlHashes = /* @__PURE__ */ new Set();
 function active() {
   if (!instance) {
     throw new Error("Advenue.initialize() must be called before tracking events.");
@@ -525,8 +567,18 @@ function fireAutoInstallIfPending() {
 }
 var Advenue = {
   async initialize(config) {
-    const { mmkv, secureStore: secureMod, onDeepLink, appId, autoTrackInstall, ...rest } = config;
+    const {
+      mmkv,
+      secureStore: secureMod,
+      onDeepLink,
+      appId,
+      autoTrackInstall,
+      tcfDataCollection,
+      ...rest
+    } = config;
     autoInstallPending = false;
+    manualConsentSet = false;
+    tcfCollectionEnabled = tcfDataCollection === true;
     autoInstallEnabled = autoTrackInstall !== false;
     const platform = resolvePlatform(rest.platform);
     configuredAppId = appId ?? null;
@@ -552,6 +604,7 @@ var Advenue = {
       ...osVersion ? { osVersion } : {}
     });
     instance.debugLog(`SDK v${package_default.version} \u2014 events -> ${configuredEndpoint}`);
+    if (tcfCollectionEnabled) resolveDmaConsent();
     void resolveAdvertisingId().catch((err) => reportError("enrich.advertisingId", err));
     const deviceInfo = collectDeviceInfo({
       platform,
@@ -568,10 +621,12 @@ var Advenue = {
           if (!instance) return;
           if (status === "background") {
             seenBackground = true;
+            if (tcfCollectionEnabled) resolveDmaConsent();
             applyAppState(instance, status);
           } else if (status === "active") {
             if (!seenBackground) return;
             seenBackground = false;
+            if (tcfCollectionEnabled) resolveDmaConsent();
             applyAppState(instance, status);
             void resolveAdvertisingId().catch((err) => reportError("enrich.advertisingId", err));
           }
@@ -582,7 +637,7 @@ var Advenue = {
         instance.notifyAppActive();
       }
     }
-    if (onDeepLink) {
+    {
       const linking = getLinking();
       if (linking) {
         const client = instance;
@@ -592,7 +647,19 @@ var 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);
+            if (aemSeenUrlHashes.has(sourceUrlHash)) return;
+            if (client.getRequireConsent() && !client.getTrackingConsent()) return;
+            client.track("adv_meta_aem", { campaignIds, sourceUrlHash });
+            aemSeenUrlHashes.add(sourceUrlHash);
+          }
         });
         deepLinkSub.ready.catch((err) => reportError("deepLink.resolve", err));
       }
@@ -645,12 +712,15 @@ var Advenue = {
     }
   },
   setConsentData(consent) {
+    manualConsentSet = true;
     active().setConsentData(consent);
     void resolveAdvertisingId().catch((err) => reportError("enrich.advertisingId", err));
   },
   getConsentData: () => active().getConsentData(),
   flush: () => active().flush(),
   getDeviceId: () => active().getDeviceId(),
+  /** The Advenue ID — alias of getDeviceId (see AdvenueClient.getAdvenueId). */
+  getAdvenueId: () => active().getAdvenueId(),
   shutdown() {
     appStateSub?.remove();
     appStateSub = null;
@@ -662,9 +732,12 @@ var Advenue = {
     installInFlight = false;
     autoInstallPending = false;
     autoInstallEnabled = true;
+    manualConsentSet = false;
+    tcfCollectionEnabled = false;
     configuredAppId = null;
     configuredApiKey = null;
     configuredEndpoint = import_sdk_core.DEFAULT_ENDPOINT;
+    aemSeenUrlHashes.clear();
   }
 };
 async function trackInstall() {
@@ -815,5 +888,6 @@ async function trackInstall() {
   getIosNative,
   parseDirectLink,
   resolveAdvertisingId,
+  resolveDmaConsent,
   trackInstall
 });

package/dist/index.d.cts

@@ -55,6 +55,16 @@ interface AdvenueDeviceInfo {
     totalStorageGb?: number;
     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`.
+ */
+interface NativeTcfData {
+    gdprApplies?: number | null;
+    purposeConsents?: string | null;
+}
 interface AdvenueAndroidNativeModule {
     /** Raw Play Install Referrer; parse with @advenue/install-referrer. */
     getInstallReferrer(): Promise<InstallReferrerResult | null>;
@@ -112,6 +122,12 @@ 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;
 }
 type TrackingAuthorizationStatus = 'notDetermined' | 'restricted' | 'denied' | 'authorized';
 interface AdvenueIosNativeModule {
@@ -176,6 +192,12 @@ 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;
 }
 
 /**
@@ -219,6 +241,20 @@ declare function getAndroidNative(): AdvenueAndroidNativeModule | null;
  * Fire-and-forget at call sites; errors are suppressed internally.
  */
 declare function resolveAdvertisingId(): Promise<void>;
+/**
+ * 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.
+ */
+declare function resolveDmaConsent(): Consent | null;
 /**
  * Collects native device metadata (model, locale, screen, cpu, storage, timezone)
  * used to populate Meta CAPI `extinfo`. Reads from the platform-appropriate
@@ -285,6 +321,14 @@ interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage' | 'platform'> {
      * 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;
 }
 /**
  * Maps a React Native AppState status to the client's session lifecycle hooks.
@@ -317,6 +361,8 @@ declare const Advenue: {
     } | null;
     flush: () => Promise<void>;
     getDeviceId: () => string;
+    /** The Advenue ID — alias of getDeviceId (see AdvenueClient.getAdvenueId). */
+    getAdvenueId: () => string;
     shutdown(): void;
 };
 /**
@@ -333,4 +379,4 @@ declare const Advenue: {
  */
 declare function trackInstall(): Promise<void>;
 
-export { Advenue, type AdvenueAndroidNativeModule, type AdvenueDeviceInfo, type AdvenueIosNativeModule, type InstallReferrerResult, type MMKVLike, type MetaInstallReferrerResult, type RNAdvenueConfig, type SecureStoreLike, type TrackingAuthorizationStatus, applyAppState, collectDeviceInfo, createMMKVStorage, createSecureStore, getAndroidNative, getIosNative, parseDirectLink, resolveAdvertisingId, trackInstall };
+export { Advenue, type AdvenueAndroidNativeModule, type AdvenueDeviceInfo, type AdvenueIosNativeModule, type InstallReferrerResult, type MMKVLike, type MetaInstallReferrerResult, type NativeTcfData, type RNAdvenueConfig, type SecureStoreLike, type TrackingAuthorizationStatus, applyAppState, collectDeviceInfo, createMMKVStorage, createSecureStore, getAndroidNative, getIosNative, parseDirectLink, resolveAdvertisingId, resolveDmaConsent, trackInstall };

package/dist/index.d.ts

@@ -55,6 +55,16 @@ interface AdvenueDeviceInfo {
     totalStorageGb?: number;
     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`.
+ */
+interface NativeTcfData {
+    gdprApplies?: number | null;
+    purposeConsents?: string | null;
+}
 interface AdvenueAndroidNativeModule {
     /** Raw Play Install Referrer; parse with @advenue/install-referrer. */
     getInstallReferrer(): Promise<InstallReferrerResult | null>;
@@ -112,6 +122,12 @@ 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;
 }
 type TrackingAuthorizationStatus = 'notDetermined' | 'restricted' | 'denied' | 'authorized';
 interface AdvenueIosNativeModule {
@@ -176,6 +192,12 @@ 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;
 }
 
 /**
@@ -219,6 +241,20 @@ declare function getAndroidNative(): AdvenueAndroidNativeModule | null;
  * Fire-and-forget at call sites; errors are suppressed internally.
  */
 declare function resolveAdvertisingId(): Promise<void>;
+/**
+ * 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.
+ */
+declare function resolveDmaConsent(): Consent | null;
 /**
  * Collects native device metadata (model, locale, screen, cpu, storage, timezone)
  * used to populate Meta CAPI `extinfo`. Reads from the platform-appropriate
@@ -285,6 +321,14 @@ interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage' | 'platform'> {
      * 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;
 }
 /**
  * Maps a React Native AppState status to the client's session lifecycle hooks.
@@ -317,6 +361,8 @@ declare const Advenue: {
     } | null;
     flush: () => Promise<void>;
     getDeviceId: () => string;
+    /** The Advenue ID — alias of getDeviceId (see AdvenueClient.getAdvenueId). */
+    getAdvenueId: () => string;
     shutdown(): void;
 };
 /**
@@ -333,4 +379,4 @@ declare const Advenue: {
  */
 declare function trackInstall(): Promise<void>;
 
-export { Advenue, type AdvenueAndroidNativeModule, type AdvenueDeviceInfo, type AdvenueIosNativeModule, type InstallReferrerResult, type MMKVLike, type MetaInstallReferrerResult, type RNAdvenueConfig, type SecureStoreLike, type TrackingAuthorizationStatus, applyAppState, collectDeviceInfo, createMMKVStorage, createSecureStore, getAndroidNative, getIosNative, parseDirectLink, resolveAdvertisingId, trackInstall };
+export { Advenue, type AdvenueAndroidNativeModule, type AdvenueDeviceInfo, type AdvenueIosNativeModule, type InstallReferrerResult, type MMKVLike, type MetaInstallReferrerResult, type NativeTcfData, type RNAdvenueConfig, type SecureStoreLike, type TrackingAuthorizationStatus, applyAppState, collectDeviceInfo, createMMKVStorage, createSecureStore, getAndroidNative, getIosNative, parseDirectLink, resolveAdvertisingId, resolveDmaConsent, trackInstall };

package/dist/index.js

@@ -62,7 +62,8 @@ import {
   DEFAULT_ENDPOINT,
   DEVICE_ID_KEY,
   MemoryStorage,
-  resolveDurableDeviceId
+  resolveDurableDeviceId,
+  tcfToConsent
 } from "@advenue/sdk-core";
 
 // ../signing/src/index.ts
@@ -217,7 +218,7 @@ function sha256Hex(message) {
 // package.json
 var package_default = {
   name: "@advenue/react-native",
-  version: "0.7.0",
+  version: "0.8.0",
   description: "Advenue MMP React Native SDK \u2014 attribution, install tracking, and deep links (bundled iOS/Android Expo native modules)",
   type: "module",
   license: "MIT",
@@ -278,6 +279,17 @@ var package_default = {
   "react-native": "./dist/index.cjs"
 };
 
+// src/aem.ts
+function extractAemCampaignIds(alApplinkData) {
+  try {
+    const parsed = JSON.parse(alApplinkData);
+    const value = typeof parsed.campaign_ids === "string" && parsed.campaign_ids ? parsed.campaign_ids : typeof parsed.extras?.campaign_ids === "string" && parsed.extras.campaign_ids ? parsed.extras.campaign_ids : null;
+    return value && value.length <= 2048 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
 // src/deep-links.ts
 function parseDirectLink(url) {
   let deepLinkValue = "";
@@ -303,11 +315,16 @@ function parseDirectLink(url) {
   };
 }
 function setupDeepLinks(setup) {
-  const listener = setup.addUrlListener((url) => setup.onDeepLink(parseDirectLink(url)));
+  const deliverDirect = (url) => {
+    const link = parseDirectLink(url);
+    setup.onDirectUrl?.(url, link);
+    setup.onDeepLink(link);
+  };
+  const listener = setup.addUrlListener(deliverDirect);
   const ready = (async () => {
     const initial = await setup.getInitialURL();
     if (initial) {
-      setup.onDeepLink(parseDirectLink(initial));
+      deliverDirect(initial);
       return;
     }
     const deferred = await setup.resolveDeferred();
@@ -454,6 +471,28 @@ async function resolveAdvertisingId() {
   }
   client.setAdvertisingId({});
 }
+function consentEquals(a, b) {
+  return a.isUserSubjectToGDPR === b.isUserSubjectToGDPR && a.hasConsentForDataUsage === b.hasConsentForDataUsage && a.hasConsentForAdsPersonalization === b.hasConsentForAdsPersonalization && a.hasConsentForAdStorage === b.hasConsentForAdStorage;
+}
+function resolveDmaConsent() {
+  if (manualConsentSet) return null;
+  const native = getIosNative() ?? getAndroidNative();
+  if (!native || typeof native.getTcfData !== "function") return null;
+  let consent = 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);
+  void resolveAdvertisingId().catch((err) => reportError("enrich.advertisingId", err));
+  return consent;
+}
 function collectDeviceInfo(natives) {
   try {
     if (natives.platform === "android" && natives.android?.getDeviceInfo) {
@@ -482,9 +521,12 @@ var INSTALL_SENT_KEY = "advenue.install_sent";
 var installInFlight = false;
 var autoInstallPending = false;
 var autoInstallEnabled = true;
+var manualConsentSet = false;
+var tcfCollectionEnabled = false;
 var configuredAppId = null;
 var configuredApiKey = null;
 var configuredEndpoint = DEFAULT_ENDPOINT;
+var aemSeenUrlHashes = /* @__PURE__ */ new Set();
 function active() {
   if (!instance) {
     throw new Error("Advenue.initialize() must be called before tracking events.");
@@ -521,8 +563,18 @@ function fireAutoInstallIfPending() {
 }
 var Advenue = {
   async initialize(config) {
-    const { mmkv, secureStore: secureMod, onDeepLink, appId, autoTrackInstall, ...rest } = config;
+    const {
+      mmkv,
+      secureStore: secureMod,
+      onDeepLink,
+      appId,
+      autoTrackInstall,
+      tcfDataCollection,
+      ...rest
+    } = config;
     autoInstallPending = false;
+    manualConsentSet = false;
+    tcfCollectionEnabled = tcfDataCollection === true;
     autoInstallEnabled = autoTrackInstall !== false;
     const platform = resolvePlatform(rest.platform);
     configuredAppId = appId ?? null;
@@ -548,6 +600,7 @@ var Advenue = {
       ...osVersion ? { osVersion } : {}
     });
     instance.debugLog(`SDK v${package_default.version} \u2014 events -> ${configuredEndpoint}`);
+    if (tcfCollectionEnabled) resolveDmaConsent();
     void resolveAdvertisingId().catch((err) => reportError("enrich.advertisingId", err));
     const deviceInfo = collectDeviceInfo({
       platform,
@@ -564,10 +617,12 @@ var Advenue = {
           if (!instance) return;
           if (status === "background") {
             seenBackground = true;
+            if (tcfCollectionEnabled) resolveDmaConsent();
             applyAppState(instance, status);
           } else if (status === "active") {
             if (!seenBackground) return;
             seenBackground = false;
+            if (tcfCollectionEnabled) resolveDmaConsent();
             applyAppState(instance, status);
             void resolveAdvertisingId().catch((err) => reportError("enrich.advertisingId", err));
           }
@@ -578,7 +633,7 @@ var Advenue = {
         instance.notifyAppActive();
       }
     }
-    if (onDeepLink) {
+    {
       const linking = getLinking();
       if (linking) {
         const client = instance;
@@ -588,7 +643,19 @@ var 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);
+            if (aemSeenUrlHashes.has(sourceUrlHash)) return;
+            if (client.getRequireConsent() && !client.getTrackingConsent()) return;
+            client.track("adv_meta_aem", { campaignIds, sourceUrlHash });
+            aemSeenUrlHashes.add(sourceUrlHash);
+          }
         });
         deepLinkSub.ready.catch((err) => reportError("deepLink.resolve", err));
       }
@@ -641,12 +708,15 @@ var Advenue = {
     }
   },
   setConsentData(consent) {
+    manualConsentSet = true;
     active().setConsentData(consent);
     void resolveAdvertisingId().catch((err) => reportError("enrich.advertisingId", err));
   },
   getConsentData: () => active().getConsentData(),
   flush: () => active().flush(),
   getDeviceId: () => active().getDeviceId(),
+  /** The Advenue ID — alias of getDeviceId (see AdvenueClient.getAdvenueId). */
+  getAdvenueId: () => active().getAdvenueId(),
   shutdown() {
     appStateSub?.remove();
     appStateSub = null;
@@ -658,9 +728,12 @@ var Advenue = {
     installInFlight = false;
     autoInstallPending = false;
     autoInstallEnabled = true;
+    manualConsentSet = false;
+    tcfCollectionEnabled = false;
     configuredAppId = null;
     configuredApiKey = null;
     configuredEndpoint = DEFAULT_ENDPOINT;
+    aemSeenUrlHashes.clear();
   }
 };
 async function trackInstall() {
@@ -810,5 +883,6 @@ export {
   getIosNative,
   parseDirectLink,
   resolveAdvertisingId,
+  resolveDmaConsent,
   trackInstall
 };

package/ios/AdvenueIosModule.swift

@@ -288,6 +288,23 @@ public class AdvenueIosModule: Module {
       Self.sdkDefaults.removeObject(forKey: key)
     }
 
+    // MARK: - DMA / TCF consent (read-only)
+
+    // IAB TCF v2 data a TCF-compliant CMP (e.g. Google UMP) writes to the
+    // app's *standard* UserDefaults — deliberately not our io.advenue.sdk
+    // suite. Raw values pass through; the TS side (tcfToConsent) owns the
+    // policy mapping. UserDefaults is thread-safe — no main-thread hop.
+    Function("getTcfData") { () -> [String: Any?]? in
+      let std = UserDefaults.standard
+      // object(forKey:), not integer(forKey:): a missing key must read as
+      // unknown, not 0 ("GDPR does not apply") — a defaulted 0 would strip
+      // consent handling from EEA traffic.
+      let gdprApplies = std.object(forKey: "IABTCF_gdprApplies") as? Int
+      let purposeConsents = std.string(forKey: "IABTCF_PurposeConsents")
+      if gdprApplies == nil && purposeConsents == nil { return nil }
+      return ["gdprApplies": gdprApplies, "purposeConsents": purposeConsents]
+    }
+
     // Keychain-backed secure storage for the reinstall-durable identifiers
     // (device id, install guard). kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly:
     // survives app reinstall, readable after first unlock (background events),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@advenue/react-native",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Advenue MMP React Native SDK — attribution, install tracking, and deep links (bundled iOS/Android Expo native modules)",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@advenue/install-referrer": "0.3.0",
-    "@advenue/sdk-core": "0.4.0"
+    "@advenue/sdk-core": "0.5.0"
   },
   "peerDependencies": {
     "@expo/config-plugins": ">=8",

package/src/aem.ts

@@ -0,0 +1,33 @@
+/**
+ * Meta AEM campaign_ids extraction from an al_applink_data payload.
+ *
+ * The input string is the ALREADY percent-decoded query-param value
+ * (URLSearchParams decodes; decoding again would corrupt blobs containing
+ * '%'). Meta does not publicly document the al_applink_data schema for AEM,
+ * so we accept the two shapes observed in the wild — top-level
+ * `campaign_ids` and `extras.campaign_ids` — top level first. VERIFY against
+ * a real captured payload when one is available and update this comment
+ * with what production links actually show (spec: implementation-time
+ * verification).
+ *
+ * The blob is opaque, Meta-encrypted, non-user metadata: returned verbatim,
+ * never trimmed/re-encoded. ≤ 2048 chars as URL hygiene (the worker
+ * re-validates — SDK caps are advisory at the trust boundary).
+ */
+export function extractAemCampaignIds(alApplinkData: string): string | null {
+  try {
+    const parsed = JSON.parse(alApplinkData) as {
+      campaign_ids?: unknown;
+      extras?: { campaign_ids?: unknown };
+    };
+    const value =
+      typeof parsed.campaign_ids === 'string' && parsed.campaign_ids
+        ? parsed.campaign_ids
+        : typeof parsed.extras?.campaign_ids === 'string' && parsed.extras.campaign_ids
+          ? parsed.extras.campaign_ids
+          : null;
+    return value && value.length <= 2048 ? value : null;
+  } catch {
+    return null;
+  }
+}

package/src/deep-links.ts

@@ -58,6 +58,10 @@ export interface DeepLinkSetup {
   resolveDeferred: () => Promise<DeepLink | null>;
   /** Fired for every resolved deep link (direct or deferred). The app navigates. */
   onDeepLink: (link: DeepLink) => void;
+  /** Fired for every DIRECT OS-delivered URL (cold or warm), before the
+   *  navigation callback. Internal hook (AEM capture); never fires for
+   *  deferred links, which are our own server's data, not an OS URL. */
+  onDirectUrl?: (url: string, link: DeepLink) => void;
 }
 
 /**
@@ -70,12 +74,17 @@ export interface DeepLinkSetup {
  * `deepLinkValue`. Await `handle.ready` to observe completion (used in tests).
  */
 export function setupDeepLinks(setup: DeepLinkSetup): DeepLinkHandle {
-  const listener = setup.addUrlListener((url) => setup.onDeepLink(parseDirectLink(url)));
+  const deliverDirect = (url: string) => {
+    const link = parseDirectLink(url);
+    setup.onDirectUrl?.(url, link);
+    setup.onDeepLink(link);
+  };
+  const listener = setup.addUrlListener(deliverDirect);
 
   const ready = (async () => {
     const initial = await setup.getInitialURL();
     if (initial) {
-      setup.onDeepLink(parseDirectLink(initial));
+      deliverDirect(initial);
       return;
     }
     const deferred = await setup.resolveDeferred();

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
@@ -197,6 +244,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,6 +292,13 @@ 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;
+// 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;
 // 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;
@@ -251,6 +313,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,10 +382,20 @@ 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,
+      appId,
+      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;
@@ -353,6 +431,9 @@ export const Advenue = {
     // 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
@@ -377,10 +458,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 +484,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 +499,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 +583,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 +591,8 @@ export const Advenue = {
   getConsentData: () => active().getConsentData(),
   flush: () => active().flush(),
   getDeviceId: () => active().getDeviceId(),
+  /** The Advenue ID — alias of getDeviceId (see AdvenueClient.getAdvenueId). */
+  getAdvenueId: () => active().getAdvenueId(),
   shutdown() {
     appStateSub?.remove();
     appStateSub = null;
@@ -487,9 +604,12 @@ export const Advenue = {
     installInFlight = false; // reset so re-initialize works correctly
     autoInstallPending = false;
     autoInstallEnabled = true;
+    manualConsentSet = false;
+    tcfCollectionEnabled = false;
     configuredAppId = null;
     configuredApiKey = null;
     configuredEndpoint = DEFAULT_ENDPOINT;
+    aemSeenUrlHashes.clear();
   },
 };
 

package/src/native-types.ts

@@ -47,6 +47,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>;
@@ -101,6 +112,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 +181,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;
 }