@advenue/react-native 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -44,6 +44,14 @@ interface MetaInstallReferrerResult {
  * real `DeviceInfo` shape.
  */
 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;
@@ -55,6 +63,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>;
@@ -73,9 +91,11 @@ 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.
@@ -112,6 +132,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 +202,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 +251,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
@@ -228,15 +274,19 @@ declare function resolveAdvertisingId(): Promise<void>;
  * native-side error degrades to an empty object so callers can unconditionally
  * pass the result through.
  */
-declare function collectDeviceInfo(natives: {
+type NativeDeviceInfo = Partial<DeviceInfo> & {
+    shortVersion?: string;
+};
+type DeviceInfoNatives = {
     platform: 'ios' | 'android' | string;
     ios?: {
-        getDeviceInfo?: () => Partial<DeviceInfo>;
+        getDeviceInfo?: () => NativeDeviceInfo;
     } | null;
     android?: {
-        getDeviceInfo?: () => Partial<DeviceInfo>;
+        getDeviceInfo?: () => NativeDeviceInfo;
     } | null;
-}): DeviceInfo;
+};
+declare function collectDeviceInfo(natives: DeviceInfoNatives): DeviceInfo;
 interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage' | 'platform'> {
     /**
      * Auto-detected from React Native's `Platform.OS` — omit it. Pass explicitly
@@ -251,18 +301,6 @@ interface RNAdvenueConfig extends Omit<AdvenueConfig, 'storage' | 'platform'> {
      * 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
@@ -285,6 +323,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 +363,11 @@ declare const Advenue: {
     } | null;
     flush: () => Promise<void>;
     getDeviceId: () => string;
+    /** The Advenue ID — alias of getDeviceId (see AdvenueClient.getAdvenueId). */
+    getAdvenueId: () => string;
+    /** Which app the server resolved this API key to; null until a batch lands
+     *  (see AdvenueClient.getResolvedAppId). */
+    getResolvedAppId: () => string | null;
     shutdown(): void;
 };
 /**
@@ -333,4 +384,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.9.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,7 +471,29 @@ async function resolveAdvertisingId() {
   }
   client.setAdvertisingId({});
 }
-function collectDeviceInfo(natives) {
+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 readNativeDeviceInfo(natives) {
   try {
     if (natives.platform === "android" && natives.android?.getDeviceInfo) {
       return natives.android.getDeviceInfo();
@@ -466,6 +505,10 @@ function collectDeviceInfo(natives) {
   }
   return {};
 }
+function collectDeviceInfo(natives) {
+  const { shortVersion: _shortVersion, ...info } = readNativeDeviceInfo(natives);
+  return info;
+}
 function applyAppState(client, status) {
   if (status === "active") {
     client.notifyAppActive();
@@ -482,9 +525,12 @@ var INSTALL_SENT_KEY = "advenue.install_sent";
 var installInFlight = false;
 var autoInstallPending = false;
 var autoInstallEnabled = true;
-var configuredAppId = null;
+var manualConsentSet = false;
+var tcfCollectionEnabled = false;
+var ATTEST_CHALLENGE_TIMEOUT_MS = 5e3;
 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,11 +567,19 @@ function fireAutoInstallIfPending() {
 }
 var Advenue = {
   async initialize(config) {
-    const { mmkv, secureStore: secureMod, onDeepLink, appId, autoTrackInstall, ...rest } = config;
+    const {
+      mmkv,
+      secureStore: secureMod,
+      onDeepLink,
+      autoTrackInstall,
+      tcfDataCollection,
+      ...rest
+    } = config;
     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();
@@ -540,20 +594,26 @@ var Advenue = {
     secureStore = secureMod ? createSecureStore(secureMod) : createNativeSecureStore(iosMod);
     const deviceId = rest.deviceId ?? await resolveDurableDeviceId(storage, secureStore ?? void 0);
     const osVersion = rest.osVersion ?? getOsVersion() ?? void 0;
+    const nativeDeviceInfo = readNativeDeviceInfo({
+      platform,
+      ios: getIosNative(),
+      android: getAndroidNative()
+    });
+    const { shortVersion, ...deviceInfo } = nativeDeviceInfo;
+    const appVersion = rest.appVersion ?? shortVersion ?? void 0;
     instance = new AdvenueClient({
       ...rest,
       platform,
       deviceId,
       storage,
-      ...osVersion ? { osVersion } : {}
+      ...osVersion ? { osVersion } : {},
+      ...appVersion ? { appVersion } : {},
+      // Stamped by the SDK, never by the host app — see AdvenueConfig.sdkVersion.
+      sdkVersion: package_default.version
     });
     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,
-      ios: getIosNative(),
-      android: getAndroidNative()
-    });
     if (Object.keys(deviceInfo).length > 0) instance.setDeviceInfo(deviceInfo);
     if (!config.disableAutoSessions) {
       const appState = getAppState();
@@ -564,10 +624,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 +640,7 @@ var Advenue = {
         instance.notifyAppActive();
       }
     }
-    if (onDeepLink) {
+    {
       const linking = getLinking();
       if (linking) {
         const client = instance;
@@ -588,7 +650,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 +715,18 @@ 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(),
+  /** 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;
@@ -658,9 +738,11 @@ var Advenue = {
     installInFlight = false;
     autoInstallPending = false;
     autoInstallEnabled = true;
-    configuredAppId = null;
+    manualConsentSet = false;
+    tcfCollectionEnabled = false;
     configuredApiKey = null;
     configuredEndpoint = DEFAULT_ENDPOINT;
+    aemSeenUrlHashes.clear();
   }
 };
 async function trackInstall() {
@@ -735,10 +817,10 @@ async function trackInstall() {
   }
   await resolveAdvertisingId();
   const trackOpts = { type: "install", ...opts };
-  if (configuredAppId && android && typeof android.getIntegrityToken === "function") {
+  if (android && typeof android.getIntegrityToken === "function") {
     try {
       const deviceId = client.getDeviceId();
-      const requestHash = sha256Hex(`${configuredAppId}:${deviceId}`);
+      const requestHash = sha256Hex(deviceId);
       const token = await android.getIntegrityToken(requestHash);
       if (token) {
         trackOpts.attestationToken = token;
@@ -748,13 +830,24 @@ async function trackInstall() {
       reportError("attest.playIntegrity", err);
     }
   }
-  if (configuredAppId && configuredApiKey && ios && typeof ios.attestKey === "function") {
+  if (configuredApiKey && ios && typeof ios.attestKey === "function") {
     try {
       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;
+      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();
       const { keyId, attestationObject } = await ios.attestKey(challenge);
@@ -810,5 +903,6 @@ export {
   getIosNative,
   parseDirectLink,
   resolveAdvertisingId,
+  resolveDmaConsent,
   trackInstall
 };

package/ios/AdvenueIosModule.swift

@@ -249,6 +249,20 @@ public class AdvenueIosModule: Module {
       info["timezone"] = TimeZone.current.identifier
       info["cpuCores"] = ProcessInfo.processInfo.activeProcessorCount
 
+      // Meta CAPI extinfo slots 1-3. CFBundleShortVersionString is the
+      // user-facing version (slot 2, surfaced as the event's appVersion);
+      // CFBundleVersion is the build identifier (slot 3).
+      let bundle = Bundle.main
+      if let bundleId = bundle.bundleIdentifier {
+        info["packageName"] = bundleId
+      }
+      if let short = bundle.infoDictionary?["CFBundleShortVersionString"] as? String {
+        info["shortVersion"] = short
+      }
+      if let build = bundle.infoDictionary?["CFBundleVersion"] as? String {
+        info["longVersion"] = build
+      }
+
       let (screenWidth, screenHeight, screenDensity) = Self.onMainSync { () -> (Int, Int, Double) in
         let screen = UIScreen.main
         return (
@@ -288,6 +302,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.9.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.6.0"
   },
   "peerDependencies": {
     "@expo/config-plugins": ">=8",
@@ -50,7 +50,7 @@
     "tsup": "^8.5.1",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
-    "@advenue/shared": "0.2.0",
+    "@advenue/shared": "0.3.0",
     "@advenue/signing": "0.0.0"
   },
   "react-native": "./dist/index.cjs",

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();