@sendoracloud/sdk-react-native 1.36.0 → 1.38.0

package/dist/index.cjs

@@ -228,7 +228,7 @@ var Storage = class {
 // package.json
 var package_default = {
   name: "@sendoracloud/sdk-react-native",
-  version: "1.36.0",
+  version: "1.38.0",
   description: "Sendora Cloud React Native + Expo SDK \u2014 analytics, identity, push-token registration, auth (incl. Game Center / Play Games), deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push-token registration and the no-arg Game Center / Play Games sign-in require a Dev Client (EAS Build or `npx expo prebuild`).",
   type: "module",
   main: "./dist/index.cjs",
@@ -284,7 +284,7 @@ var package_default = {
   scripts: {
     build: "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
     typecheck: "tsc --noEmit",
-    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts"
+    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts"
   },
   devDependencies: {
     "@types/react": "^19.2.16",
@@ -2156,7 +2156,7 @@ var Auth = class {
     this.hooks.storage.remove(TOKEN_EXPIRES_KEY);
     this.hooks.storage.remove(REFRESH_KEY);
     this.stopProactiveRefreshCron();
-    await this.hooks.onAnonymousWipe();
+    await this.hooks.onAnonymousWipe(reason);
     if (reason !== "replaced") {
       this.emitAuthState({ event: "signed_out", user: null, reason });
     }
@@ -2627,33 +2627,31 @@ var Links = class {
     }
   }
   /**
-   * Cold-launch deferred deep link match. When neither `fingerprintHash` nor
-   * `installReferrer` is supplied, the SDK auto-discovers:
-   *   - Android: probes `react-native-play-install-referrer` (preferred — 100%
-   *     accurate when present).
-   *   - Otherwise: computes the canonical device fingerprint hash.
+   * Cold-launch deferred deep-link match.
+   *
+   * ⚠ NO IMPLICIT FINGERPRINTING (compliance). This used to compute a device
+   * fingerprint on iOS when you passed no signal; it no longer does — Apple
+   * prohibits deriving a device identifier from device signals for attribution
+   * (App Store 5.1.2 / DPLA §3.3.9), regardless of ATT, and doing it on-device is
+   * exactly that. Signal resolution now:
+   *   - Android: probes `react-native-play-install-referrer` — deterministic, the
+   *     preferred and compliant path.
+   *   - iOS: no deterministic signal exists (the App Store has no install referrer).
+   *     With `allowProbabilisticMatch: true` the server matches on a coarse
+   *     IP + time window (OFF by default — see `LinkMatchInput`). Otherwise this
+   *     returns `null` and you route the user through your normal onboarding UX —
+   *     which is the expected iOS cold-launch outcome, not an error.
    *
    * Fires `onLinkOpened` with `isDeferred: true` on success.
    */
   async matchDeferred(input = {}) {
-    let fingerprintHash = input.fingerprintHash;
+    const fingerprintHash = input.fingerprintHash;
     let installReferrer = input.installReferrer;
     if (!fingerprintHash && !installReferrer) {
       installReferrer = await getPlayInstallReferrer() ?? void 0;
-      if (!installReferrer) {
-        try {
-          fingerprintHash = await computeDeviceFingerprint();
-        } catch (err) {
-          if (this.deps.debug) console.warn("[sendoracloud] fingerprint compute failed:", err);
-        }
-      }
-    }
-    if (!fingerprintHash && !installReferrer) {
-      throw new LinkError(
-        "INVALID_INPUT",
-        "links.matchDeferred: install `react-native-play-install-referrer` for Android, or ensure web crypto / expo-crypto is available for iOS fingerprint compute."
-      );
     }
+    const canMatch = !!fingerprintHash || !!installReferrer || input.allowProbabilisticMatch === true;
+    if (!canMatch) return null;
     const body = {};
     if (fingerprintHash) body.fingerprintHash = fingerprintHash;
     if (installReferrer) body.installReferrer = installReferrer;
@@ -3101,9 +3099,11 @@ var SendoraSDK = class {
         if (userId) this.storage.set(USER_ID_KEY, userId);
         else this.storage.remove(USER_ID_KEY);
       },
-      onAnonymousWipe: async () => {
-        this.anonId = uuid();
-        this.storage.set(ANON_KEY, this.anonId);
+      onAnonymousWipe: async (reason) => {
+        if (reason === "user" || reason === "account_deleted") {
+          this.anonId = uuid();
+          this.storage.set(ANON_KEY, this.anonId);
+        }
         this.userId = null;
         this.storage.remove(USER_ID_KEY);
       }

package/dist/index.d.cts

@@ -497,12 +497,15 @@ interface AuthHooks {
      *  identity (analytics userId, push token registration, etc). */
     onIdentityChange: (userId: string | null) => void;
     /**
-     * Called when the SDK switches from one identity to another via
-     * signIn() or non-anonymous signUp(). The parent rotates anonId
-     * + drops any pending events so the new user can't carry over
-     * orphaned attribution.
-     */
-    onAnonymousWipe: () => Promise<void>;
+     * Called from `wipeLocalIdentity` whenever the local session is cleared. The
+     * `reason` lets the parent decide whether to rotate the anonymous analytics id:
+     * it rotates ONLY at a person-boundary ("user" = explicit signOut,
+     * "account_deleted"), never on a successful sign-in/upgrade ("replaced") or an
+     * involuntary session death ("session_expired") — those are the same person, and
+     * the anon id must survive so pre-auth analytics link to them (Firebase-FID
+     * semantics; the industry norm).
+     */
+    onAnonymousWipe: (reason: WipeReason) => Promise<void>;
     apiUrl: string;
     publicKey: string;
     debug: boolean;
@@ -565,6 +568,12 @@ type AuthStateChange = {
     user: AuthUser | null;
 };
 type AuthStateListener = (change: AuthStateChange) => void;
+/**
+ * Internal marker for a wipe that is immediately followed by a `persist()` of
+ * a NEW session (the sign-in success path). Not a sign-out — emitting one
+ * would make every successful sign-in look like a logout to subscribers.
+ */
+type WipeReason = AuthSignedOutReason | "replaced";
 declare class Auth {
     private hooks;
     private user;
@@ -1400,11 +1409,33 @@ interface LinkOpenedEvent<T extends LinkData = LinkData> {
 }
 type LinkOpenedHandler<T extends LinkData = LinkData> = (event: LinkOpenedEvent<T>) => void;
 interface LinkMatchInput {
-    /** Hex-encoded SHA-256 — pass output of `computeDeviceFingerprint()`. */
+    /**
+     * Hex-encoded SHA-256 device fingerprint.
+     *
+     * ⚠ **Do not supply this on iOS.** Apple prohibits deriving a device identifier
+     * from device signals for attribution (App Store 5.1.2 / DPLA §3.3.9), and it
+     * does not care which side of the network computed it — passing a hash you built
+     * on-device is the same practice. The SDK no longer computes one for you (it used
+     * to, implicitly, on iOS). Left here for the rare Android/self-hosted caller that
+     * has a legitimate deterministic hash; on iOS, omit it.
+     */
     fingerprintHash?: string;
     /** Raw Play Install Referrer. Sendora probes
      *  `react-native-play-install-referrer` automatically when this is omitted. */
     installReferrer?: string;
+    /**
+     * Opt in to probabilistic matching on iOS.
+     *
+     * iOS has no deterministic deferred-install signal (no install referrer), and the
+     * SDK will not fingerprint the device. The only remaining matcher is the server's
+     * coarse IP + timestamp window — the same class of practice Apple scrutinises, and
+     * it collides across a shared NAT / iCloud Private Relay. So it is **off by
+     * default**: without this flag, `matchDeferred()` on iOS matches nothing and
+     * returns `null` (route the user through your normal onboarding UX). Set it only
+     * if you accept the accuracy and compliance trade-off. No effect on Android, where
+     * the Play Install Referrer is deterministic.
+     */
+    allowProbabilisticMatch?: boolean;
     iosBundleId?: string;
     androidPackageName?: string;
 }
@@ -1437,12 +1468,14 @@ interface LinkStats {
  */
 declare function extractShortcodeFromUrl(url: string, linkDomain?: string): string | null;
 /**
- * Canonical device-fingerprint recipe. Identical byte-for-byte across the
- * RN / iOS / Android SDKs so a click logged from one platform and an
- * install completing on another won't accidentally match.
+ * Canonical device-fingerprint recipe (`${platform}|${screenW}x${screenH}|${timezone}|${locale}`
+ * → lowercase hex SHA-256), identical across the RN / iOS / Android SDKs.
  *
- * Input: `${platform}|${screenW}x${screenH}|${timezone}|${locale}`
- * Output: lowercase hex SHA-256.
+ * @deprecated ⚠ Do not use on iOS. Apple prohibits deriving a device identifier
+ * from device signals for attribution (App Store 5.1.2 / DPLA §3.3.9), regardless
+ * of ATT — and this is exactly that. `matchDeferred()` no longer calls it
+ * implicitly. It is retained only for an Android/self-hosted caller with a
+ * legitimate deterministic use, and is slated for removal in a future major.
  */
 declare function computeDeviceFingerprint(): Promise<string>;
 /** Probe optional `react-native-play-install-referrer` peer. Returns the
@@ -1511,11 +1544,20 @@ declare class Links {
      */
     handleUniversalLink(url: string): Promise<boolean>;
     /**
-     * Cold-launch deferred deep link match. When neither `fingerprintHash` nor
-     * `installReferrer` is supplied, the SDK auto-discovers:
-     *   - Android: probes `react-native-play-install-referrer` (preferred — 100%
-     *     accurate when present).
-     *   - Otherwise: computes the canonical device fingerprint hash.
+     * Cold-launch deferred deep-link match.
+     *
+     * ⚠ NO IMPLICIT FINGERPRINTING (compliance). This used to compute a device
+     * fingerprint on iOS when you passed no signal; it no longer does — Apple
+     * prohibits deriving a device identifier from device signals for attribution
+     * (App Store 5.1.2 / DPLA §3.3.9), regardless of ATT, and doing it on-device is
+     * exactly that. Signal resolution now:
+     *   - Android: probes `react-native-play-install-referrer` — deterministic, the
+     *     preferred and compliant path.
+     *   - iOS: no deterministic signal exists (the App Store has no install referrer).
+     *     With `allowProbabilisticMatch: true` the server matches on a coarse
+     *     IP + time window (OFF by default — see `LinkMatchInput`). Otherwise this
+     *     returns `null` and you route the user through your normal onboarding UX —
+     *     which is the expected iOS cold-launch outcome, not an error.
      *
      * Fires `onLinkOpened` with `isDeferred: true` on success.
      */

package/dist/index.d.ts

@@ -497,12 +497,15 @@ interface AuthHooks {
      *  identity (analytics userId, push token registration, etc). */
     onIdentityChange: (userId: string | null) => void;
     /**
-     * Called when the SDK switches from one identity to another via
-     * signIn() or non-anonymous signUp(). The parent rotates anonId
-     * + drops any pending events so the new user can't carry over
-     * orphaned attribution.
-     */
-    onAnonymousWipe: () => Promise<void>;
+     * Called from `wipeLocalIdentity` whenever the local session is cleared. The
+     * `reason` lets the parent decide whether to rotate the anonymous analytics id:
+     * it rotates ONLY at a person-boundary ("user" = explicit signOut,
+     * "account_deleted"), never on a successful sign-in/upgrade ("replaced") or an
+     * involuntary session death ("session_expired") — those are the same person, and
+     * the anon id must survive so pre-auth analytics link to them (Firebase-FID
+     * semantics; the industry norm).
+     */
+    onAnonymousWipe: (reason: WipeReason) => Promise<void>;
     apiUrl: string;
     publicKey: string;
     debug: boolean;
@@ -565,6 +568,12 @@ type AuthStateChange = {
     user: AuthUser | null;
 };
 type AuthStateListener = (change: AuthStateChange) => void;
+/**
+ * Internal marker for a wipe that is immediately followed by a `persist()` of
+ * a NEW session (the sign-in success path). Not a sign-out — emitting one
+ * would make every successful sign-in look like a logout to subscribers.
+ */
+type WipeReason = AuthSignedOutReason | "replaced";
 declare class Auth {
     private hooks;
     private user;
@@ -1400,11 +1409,33 @@ interface LinkOpenedEvent<T extends LinkData = LinkData> {
 }
 type LinkOpenedHandler<T extends LinkData = LinkData> = (event: LinkOpenedEvent<T>) => void;
 interface LinkMatchInput {
-    /** Hex-encoded SHA-256 — pass output of `computeDeviceFingerprint()`. */
+    /**
+     * Hex-encoded SHA-256 device fingerprint.
+     *
+     * ⚠ **Do not supply this on iOS.** Apple prohibits deriving a device identifier
+     * from device signals for attribution (App Store 5.1.2 / DPLA §3.3.9), and it
+     * does not care which side of the network computed it — passing a hash you built
+     * on-device is the same practice. The SDK no longer computes one for you (it used
+     * to, implicitly, on iOS). Left here for the rare Android/self-hosted caller that
+     * has a legitimate deterministic hash; on iOS, omit it.
+     */
     fingerprintHash?: string;
     /** Raw Play Install Referrer. Sendora probes
      *  `react-native-play-install-referrer` automatically when this is omitted. */
     installReferrer?: string;
+    /**
+     * Opt in to probabilistic matching on iOS.
+     *
+     * iOS has no deterministic deferred-install signal (no install referrer), and the
+     * SDK will not fingerprint the device. The only remaining matcher is the server's
+     * coarse IP + timestamp window — the same class of practice Apple scrutinises, and
+     * it collides across a shared NAT / iCloud Private Relay. So it is **off by
+     * default**: without this flag, `matchDeferred()` on iOS matches nothing and
+     * returns `null` (route the user through your normal onboarding UX). Set it only
+     * if you accept the accuracy and compliance trade-off. No effect on Android, where
+     * the Play Install Referrer is deterministic.
+     */
+    allowProbabilisticMatch?: boolean;
     iosBundleId?: string;
     androidPackageName?: string;
 }
@@ -1437,12 +1468,14 @@ interface LinkStats {
  */
 declare function extractShortcodeFromUrl(url: string, linkDomain?: string): string | null;
 /**
- * Canonical device-fingerprint recipe. Identical byte-for-byte across the
- * RN / iOS / Android SDKs so a click logged from one platform and an
- * install completing on another won't accidentally match.
+ * Canonical device-fingerprint recipe (`${platform}|${screenW}x${screenH}|${timezone}|${locale}`
+ * → lowercase hex SHA-256), identical across the RN / iOS / Android SDKs.
  *
- * Input: `${platform}|${screenW}x${screenH}|${timezone}|${locale}`
- * Output: lowercase hex SHA-256.
+ * @deprecated ⚠ Do not use on iOS. Apple prohibits deriving a device identifier
+ * from device signals for attribution (App Store 5.1.2 / DPLA §3.3.9), regardless
+ * of ATT — and this is exactly that. `matchDeferred()` no longer calls it
+ * implicitly. It is retained only for an Android/self-hosted caller with a
+ * legitimate deterministic use, and is slated for removal in a future major.
  */
 declare function computeDeviceFingerprint(): Promise<string>;
 /** Probe optional `react-native-play-install-referrer` peer. Returns the
@@ -1511,11 +1544,20 @@ declare class Links {
      */
     handleUniversalLink(url: string): Promise<boolean>;
     /**
-     * Cold-launch deferred deep link match. When neither `fingerprintHash` nor
-     * `installReferrer` is supplied, the SDK auto-discovers:
-     *   - Android: probes `react-native-play-install-referrer` (preferred — 100%
-     *     accurate when present).
-     *   - Otherwise: computes the canonical device fingerprint hash.
+     * Cold-launch deferred deep-link match.
+     *
+     * ⚠ NO IMPLICIT FINGERPRINTING (compliance). This used to compute a device
+     * fingerprint on iOS when you passed no signal; it no longer does — Apple
+     * prohibits deriving a device identifier from device signals for attribution
+     * (App Store 5.1.2 / DPLA §3.3.9), regardless of ATT, and doing it on-device is
+     * exactly that. Signal resolution now:
+     *   - Android: probes `react-native-play-install-referrer` — deterministic, the
+     *     preferred and compliant path.
+     *   - iOS: no deterministic signal exists (the App Store has no install referrer).
+     *     With `allowProbabilisticMatch: true` the server matches on a coarse
+     *     IP + time window (OFF by default — see `LinkMatchInput`). Otherwise this
+     *     returns `null` and you route the user through your normal onboarding UX —
+     *     which is the expected iOS cold-launch outcome, not an error.
      *
      * Fires `onLinkOpened` with `isDeferred: true` on success.
      */

package/dist/index.js

@@ -183,7 +183,7 @@ var Storage = class {
 // package.json
 var package_default = {
   name: "@sendoracloud/sdk-react-native",
-  version: "1.36.0",
+  version: "1.38.0",
   description: "Sendora Cloud React Native + Expo SDK \u2014 analytics, identity, push-token registration, auth (incl. Game Center / Play Games), deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push-token registration and the no-arg Game Center / Play Games sign-in require a Dev Client (EAS Build or `npx expo prebuild`).",
   type: "module",
   main: "./dist/index.cjs",
@@ -239,7 +239,7 @@ var package_default = {
   scripts: {
     build: "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
     typecheck: "tsc --noEmit",
-    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts"
+    test: "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts"
   },
   devDependencies: {
     "@types/react": "^19.2.16",
@@ -2111,7 +2111,7 @@ var Auth = class {
     this.hooks.storage.remove(TOKEN_EXPIRES_KEY);
     this.hooks.storage.remove(REFRESH_KEY);
     this.stopProactiveRefreshCron();
-    await this.hooks.onAnonymousWipe();
+    await this.hooks.onAnonymousWipe(reason);
     if (reason !== "replaced") {
       this.emitAuthState({ event: "signed_out", user: null, reason });
     }
@@ -2587,33 +2587,31 @@ var Links = class {
     }
   }
   /**
-   * Cold-launch deferred deep link match. When neither `fingerprintHash` nor
-   * `installReferrer` is supplied, the SDK auto-discovers:
-   *   - Android: probes `react-native-play-install-referrer` (preferred — 100%
-   *     accurate when present).
-   *   - Otherwise: computes the canonical device fingerprint hash.
+   * Cold-launch deferred deep-link match.
+   *
+   * ⚠ NO IMPLICIT FINGERPRINTING (compliance). This used to compute a device
+   * fingerprint on iOS when you passed no signal; it no longer does — Apple
+   * prohibits deriving a device identifier from device signals for attribution
+   * (App Store 5.1.2 / DPLA §3.3.9), regardless of ATT, and doing it on-device is
+   * exactly that. Signal resolution now:
+   *   - Android: probes `react-native-play-install-referrer` — deterministic, the
+   *     preferred and compliant path.
+   *   - iOS: no deterministic signal exists (the App Store has no install referrer).
+   *     With `allowProbabilisticMatch: true` the server matches on a coarse
+   *     IP + time window (OFF by default — see `LinkMatchInput`). Otherwise this
+   *     returns `null` and you route the user through your normal onboarding UX —
+   *     which is the expected iOS cold-launch outcome, not an error.
    *
    * Fires `onLinkOpened` with `isDeferred: true` on success.
    */
   async matchDeferred(input = {}) {
-    let fingerprintHash = input.fingerprintHash;
+    const fingerprintHash = input.fingerprintHash;
     let installReferrer = input.installReferrer;
     if (!fingerprintHash && !installReferrer) {
       installReferrer = await getPlayInstallReferrer() ?? void 0;
-      if (!installReferrer) {
-        try {
-          fingerprintHash = await computeDeviceFingerprint();
-        } catch (err) {
-          if (this.deps.debug) console.warn("[sendoracloud] fingerprint compute failed:", err);
-        }
-      }
-    }
-    if (!fingerprintHash && !installReferrer) {
-      throw new LinkError(
-        "INVALID_INPUT",
-        "links.matchDeferred: install `react-native-play-install-referrer` for Android, or ensure web crypto / expo-crypto is available for iOS fingerprint compute."
-      );
     }
+    const canMatch = !!fingerprintHash || !!installReferrer || input.allowProbabilisticMatch === true;
+    if (!canMatch) return null;
     const body = {};
     if (fingerprintHash) body.fingerprintHash = fingerprintHash;
     if (installReferrer) body.installReferrer = installReferrer;
@@ -3061,9 +3059,11 @@ var SendoraSDK = class {
         if (userId) this.storage.set(USER_ID_KEY, userId);
         else this.storage.remove(USER_ID_KEY);
       },
-      onAnonymousWipe: async () => {
-        this.anonId = uuid();
-        this.storage.set(ANON_KEY, this.anonId);
+      onAnonymousWipe: async (reason) => {
+        if (reason === "user" || reason === "account_deleted") {
+          this.anonId = uuid();
+          this.storage.set(ANON_KEY, this.anonId);
+        }
         this.userId = null;
         this.storage.remove(USER_ID_KEY);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendoracloud/sdk-react-native",
-  "version": "1.36.0",
+  "version": "1.38.0",
   "description": "Sendora Cloud React Native + Expo SDK — analytics, identity, push-token registration, auth (incl. Game Center / Play Games), deep links (Branch / Firebase Dynamic Links parity). Auth + analytics + deep links work in Expo Go; push-token registration and the no-arg Game Center / Play Games sign-in require a Dev Client (EAS Build or `npx expo prebuild`).",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -56,7 +56,7 @@
   "scripts": {
     "build": "tsup src/index.ts src/contact-widget.tsx --format esm,cjs --dts --clean --external react --external react-native --external react-native-webview",
     "typecheck": "tsc --noEmit",
-    "test": "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts"
+    "test": "tsx test/secure-storage.test.ts && tsx test/integration-storage.test.ts && tsx test/plugin.test.ts && tsx test/game-auth.test.ts && tsx test/link.test.ts && tsx test/session-preservation.test.ts && tsx test/credential-collision.test.ts && tsx test/token-expiry.test.ts && tsx test/unlink.test.ts && tsx test/deferred-match.test.ts && tsx test/anon-id-stability.test.ts"
   },
   "devDependencies": {
     "@types/react": "^19.2.16",