@tolinku/react-native-sdk 0.2.0 → 0.4.0

package/README.md

@@ -142,12 +142,41 @@ if (link) {
   console.log(link.deep_link_path); // e.g. "/merchant/xyz"
 }
 
-// Claim by device signal matching (auto-detects timezone, language, screen size)
+// Claim by device signal matching. Timezone, language, screen size, pixel ratio and
+// OS version are detected for you.
 const link = await Tolinku.deferred.claimBySignals({
-  appspaceId: 'your_appspace_id',
+  appspaceId: '64f0a1b2c3d4e5f60718',
 });
 ```
 
+On Android the Play Install Referrer is the deterministic mechanism: a Tolinku
+link attaches a token to the store URL, Play keeps it through the install, and
+this SDK reads it back on first launch. It names the exact click, survives for
+days, and does not depend on the network the device was on. Device signals are
+the fallback, and the only option on iOS, where no equivalent exists.
+
+Prefer `claimDeferredLink()` over choosing a mechanism yourself:
+
+```ts
+// Referrer first, device signals as the fallback.
+const link = await Tolinku.deferred.claimDeferredLink({
+  appspaceId: '64f0a1b2c3d4e5f60718',
+});
+if (link) routeTo(link.deep_link_path);
+```
+
+Call it once on first launch. Calling again is safe, but a claim is consumed the
+first time it succeeds, so a second call returns nothing.
+
+The Android side is bundled with this package, so there is nothing else to
+install. Autolinking is per-platform, so an iOS-only app never builds it. In
+Expo Go the native module is absent and Android falls back to signal matching;
+a development build gets the referrer.
+
+`appspaceId` is your Appspace ID, not your subdomain or slug. Copy it from the dashboard
+under **Integrate** or **Settings**. It looks like `64f0a1b2c3d4e5f60718`.
+
+
 ### In-App Messages (React Native Component)
 
 Display server-configured in-app messages using the `<TolinkuMessages>` component. Drop it anywhere in your React Native component tree to automatically fetch and render messages as a modal overlay. Messages are created and managed from the Tolinku dashboard without shipping app updates.

package/android/build.gradle

@@ -0,0 +1,74 @@
+// Android side of @tolinku/react-native-sdk.
+//
+// Exists only to read the Play Install Referrer, which is the deterministic way
+// a deferred link survives an install on Android. It is bundled rather than
+// delegated to a third-party package because the referrer token is Tolinku's
+// own mechanism: we mint it on the link and read it back here.
+//
+// Autolinking is per-platform, so this is not built when compiling for iOS. An
+// iOS-only app pays nothing for its presence.
+//
+// To verify compilation outside a host app:
+//   printf 'rootProject.name = "t"\n' > android/settings.gradle
+//   ../../android-sdk/gradlew -p android assembleRelease \
+//       -PtolinkuReactAndroidVersion=0.73.11 -Pandroid.useAndroidX=true
+//   rm android/settings.gradle
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.1.4")
+    }
+}
+
+apply plugin: "com.android.library"
+
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+    // The peer range starts at React Native 0.72, whose AGP 7.4 supports
+    // namespace, so the old manifest package attribute is not needed.
+    namespace "com.tolinku.rnsdk"
+
+    compileSdkVersion safeExtGet("compileSdkVersion", 34)
+
+    defaultConfig {
+        // The Install Referrer library needs 21; the host app decides above that.
+        minSdkVersion safeExtGet("minSdkVersion", 21)
+        targetSdkVersion safeExtGet("targetSdkVersion", 34)
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+
+    lintOptions {
+        abortOnError false
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    // Unversioned on purpose: the React Native Gradle plugin in the host app
+    // pins this to whatever version the app is on, so the library follows the
+    // app rather than forcing one. A version is supplied only for the standalone
+    // build used to verify compilation outside an app.
+    def rnVersion = project.findProperty("tolinkuReactAndroidVersion")
+    if (rnVersion) {
+        implementation "com.facebook.react:react-android:${rnVersion}"
+    } else {
+        implementation "com.facebook.react:react-android"
+    }
+
+    implementation "com.android.installreferrer:installreferrer:2.2"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/com/tolinku/rnsdk/TolinkuInstallReferrerModule.java

@@ -0,0 +1,107 @@
+package com.tolinku.rnsdk;
+
+import androidx.annotation.NonNull;
+
+import com.android.installreferrer.api.InstallReferrerClient;
+import com.android.installreferrer.api.InstallReferrerStateListener;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/**
+ * Reads the Play Install Referrer.
+ *
+ * A Tolinku link sends an Android visitor to the store with
+ * {@code referrer=tolk_token=<token>} attached. Play keeps that string through
+ * the install and hands it back on first launch, which names the exact click
+ * instead of inferring it from device signals.
+ *
+ * Only the raw referrer string is returned. Finding our token inside it is done
+ * in JavaScript, where it is covered by tests that run on every platform rather
+ * than only where an Android toolchain exists.
+ */
+public class TolinkuInstallReferrerModule extends ReactContextBaseJavaModule {
+
+    public static final String NAME = "TolinkuInstallReferrer";
+
+    public TolinkuInstallReferrerModule(ReactApplicationContext reactContext) {
+        super(reactContext);
+    }
+
+    @Override
+    @NonNull
+    public String getName() {
+        return NAME;
+    }
+
+    /**
+     * Resolves with the raw referrer string, or null when there is nothing to
+     * report.
+     *
+     * Never rejects. An organic install, a device without Play Services, and a
+     * store other than Play are all ordinary outcomes rather than errors, and
+     * the caller falls back to signal matching for every one of them. Rejecting
+     * would turn a routine absence into an unhandled promise on first launch.
+     */
+    @ReactMethod
+    public void getInstallReferrer(final Promise promise) {
+        final InstallReferrerClient client;
+        try {
+            client = InstallReferrerClient.newBuilder(getReactApplicationContext()).build();
+        } catch (Throwable t) {
+            promise.resolve(null);
+            return;
+        }
+
+        // The Play listener can fire more than once on some devices, and
+        // resolving a promise twice is an error in React Native.
+        final AtomicBoolean settled = new AtomicBoolean(false);
+
+        try {
+            client.startConnection(new InstallReferrerStateListener() {
+                @Override
+                public void onInstallReferrerSetupFinished(int responseCode) {
+                    if (!settled.compareAndSet(false, true)) {
+                        return;
+                    }
+                    String referrer = null;
+                    try {
+                        if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
+                            referrer = client.getInstallReferrer().getInstallReferrer();
+                        }
+                    } catch (Throwable t) {
+                        referrer = null;
+                    } finally {
+                        endQuietly(client);
+                    }
+                    promise.resolve(referrer);
+                }
+
+                @Override
+                public void onInstallReferrerServiceDisconnected() {
+                    if (!settled.compareAndSet(false, true)) {
+                        return;
+                    }
+                    endQuietly(client);
+                    promise.resolve(null);
+                }
+            });
+        } catch (Throwable t) {
+            if (settled.compareAndSet(false, true)) {
+                endQuietly(client);
+                promise.resolve(null);
+            }
+        }
+    }
+
+    private static void endQuietly(InstallReferrerClient client) {
+        try {
+            client.endConnection();
+        } catch (Throwable ignored) {
+            // Already gone.
+        }
+    }
+}

package/android/src/main/java/com/tolinku/rnsdk/TolinkuInstallReferrerPackage.java

@@ -0,0 +1,30 @@
+package com.tolinku.rnsdk;
+
+import androidx.annotation.NonNull;
+
+import com.facebook.react.ReactPackage;
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.uimanager.ViewManager;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/** Registers the install referrer module with React Native's autolinking. */
+public class TolinkuInstallReferrerPackage implements ReactPackage {
+
+    @Override
+    @NonNull
+    public List<NativeModule> createNativeModules(@NonNull ReactApplicationContext reactContext) {
+        List<NativeModule> modules = new ArrayList<>();
+        modules.add(new TolinkuInstallReferrerModule(reactContext));
+        return modules;
+    }
+
+    @Override
+    @NonNull
+    public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext reactContext) {
+        return Collections.emptyList();
+    }
+}

package/dist/index.d.mts

@@ -111,6 +111,10 @@ interface ClaimBySignalsOptions {
     language?: string;
     screenWidth?: number;
     screenHeight?: number;
+    /** Defaults to `PixelRatio.get()`. Override only if you report a custom screen size. */
+    devicePixelRatio?: number;
+    /** Defaults to `Platform.Version`. Compared on the major component only. */
+    osVersion?: string;
 }
 /** In-app message from the API */
 interface Message {
@@ -315,13 +319,68 @@ declare class Referrals {
     }>;
 }
 
+/**
+ * Pull our token out of a Play referrer string.
+ *
+ * The referrer is shared. A developer's own `utm_source` and anything else they
+ * attached sit in the same string, so the token is found among the pairs rather
+ * than assumed to be the whole value. A percent-encoded `%3D` is tolerated
+ * because Play normally decodes it, and that assumption is not worth a lost
+ * install if it is ever wrong.
+ */
+declare function parseInstallReferrer(referrer: string | null | undefined): string | null;
+/** Anything that can hand back a Play referrer string. */
+type ReferrerProvider = () => Promise<string | null> | string | null;
+/**
+ * Best effort at the referrer token for this install.
+ *
+ * Android only, and null everywhere else: there is no equivalent on iOS, which
+ * is why signal matching exists at all. Never throws, because attribution must
+ * not be able to fail a first launch.
+ */
+declare function getInstallReferrerToken(provider?: ReferrerProvider): Promise<string | null>;
+
 declare class Deferred {
     private client;
     constructor(client: HttpClient);
     /** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
-    claimByToken(token: string): Promise<DeferredLink | null>;
+    claimByToken(token: string, appspaceId?: string): Promise<DeferredLink | null>;
+    /**
+     * Recover the link that led to this install, trying both mechanisms.
+     *
+     * The Play Install Referrer is asked first on Android: it names the exact
+     * click, survives for days, and does not care which network the device was
+     * on. Device signals are the fallback, and the only option on iOS, where no
+     * equivalent exists.
+     *
+     * Call once on first launch. Safe to call again, but a claim is consumed the
+     * first time it succeeds, so a second call returns null.
+     *
+     * Reading the referrer needs a native Play Services binding, which this
+     * package deliberately does not bundle. Pass `referrerProvider`, or install a
+     * supported referrer package and it is used automatically. Without either,
+     * Android falls back to signal matching.
+     */
+    claimDeferredLink(options: {
+        appspaceId: string;
+        referrerProvider?: ReferrerProvider;
+        /** Claim again even if an attempt was already recorded. For tests. */
+        force?: boolean;
+    }): Promise<DeferredLink | null>;
+    private alreadyAttempted;
+    private rememberAttempt;
     /** Claim a deferred deep link by device signal matching */
     claimBySignals(options: ClaimBySignalsOptions): Promise<DeferredLink | null>;
+    /**
+     * The signal claim, with whether the server actually answered.
+     *
+     * `settled` separates "nothing is waiting for this device", which no amount
+     * of asking will change, from "the request never got there". Both surface as
+     * null to callers of claimBySignals, but claimDeferredLink has to tell them
+     * apart: recording an attempt that never reached the server would spend an
+     * install's one chance at attribution on a dropped connection.
+     */
+    private attemptSignals;
 }
 
 /**
@@ -334,7 +393,7 @@ declare class Deferred {
  *   await Tolinku.track('signup', { source: 'onboarding' });
  */
 declare class Tolinku {
-    static readonly VERSION = "0.1.0";
+    static readonly VERSION = "0.4.0";
     private static client;
     private static analyticsInstance;
     private static ecommerceInstance;
@@ -348,6 +407,15 @@ declare class Tolinku {
      * If init() is called a second time without calling destroy() first,
      * a warning is logged and the existing instance is returned.
      */
+    /**
+     * Configure the SDK.
+     *
+     * The name the Android, iOS and Flutter SDKs use for this. {@link init} does
+     * the same thing and still works; it is what this package shipped and
+     * breaking it would serve nobody. It is meant for deprecation later, once
+     * moving off it is a one-line change rather than a surprise.
+     */
+    static configure(config: TolinkuConfig): void;
     static init(config: TolinkuConfig): void;
     /** Check whether the SDK has been initialized. */
     static isConfigured(): boolean;
@@ -413,4 +481,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
  */
 declare function isSafeUrl(url: string): boolean;
 
-export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, isSafeUrl };
+export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type ReferrerProvider, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, getInstallReferrerToken, isSafeUrl, parseInstallReferrer };

package/dist/index.d.ts

@@ -111,6 +111,10 @@ interface ClaimBySignalsOptions {
     language?: string;
     screenWidth?: number;
     screenHeight?: number;
+    /** Defaults to `PixelRatio.get()`. Override only if you report a custom screen size. */
+    devicePixelRatio?: number;
+    /** Defaults to `Platform.Version`. Compared on the major component only. */
+    osVersion?: string;
 }
 /** In-app message from the API */
 interface Message {
@@ -315,13 +319,68 @@ declare class Referrals {
     }>;
 }
 
+/**
+ * Pull our token out of a Play referrer string.
+ *
+ * The referrer is shared. A developer's own `utm_source` and anything else they
+ * attached sit in the same string, so the token is found among the pairs rather
+ * than assumed to be the whole value. A percent-encoded `%3D` is tolerated
+ * because Play normally decodes it, and that assumption is not worth a lost
+ * install if it is ever wrong.
+ */
+declare function parseInstallReferrer(referrer: string | null | undefined): string | null;
+/** Anything that can hand back a Play referrer string. */
+type ReferrerProvider = () => Promise<string | null> | string | null;
+/**
+ * Best effort at the referrer token for this install.
+ *
+ * Android only, and null everywhere else: there is no equivalent on iOS, which
+ * is why signal matching exists at all. Never throws, because attribution must
+ * not be able to fail a first launch.
+ */
+declare function getInstallReferrerToken(provider?: ReferrerProvider): Promise<string | null>;
+
 declare class Deferred {
     private client;
     constructor(client: HttpClient);
     /** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
-    claimByToken(token: string): Promise<DeferredLink | null>;
+    claimByToken(token: string, appspaceId?: string): Promise<DeferredLink | null>;
+    /**
+     * Recover the link that led to this install, trying both mechanisms.
+     *
+     * The Play Install Referrer is asked first on Android: it names the exact
+     * click, survives for days, and does not care which network the device was
+     * on. Device signals are the fallback, and the only option on iOS, where no
+     * equivalent exists.
+     *
+     * Call once on first launch. Safe to call again, but a claim is consumed the
+     * first time it succeeds, so a second call returns null.
+     *
+     * Reading the referrer needs a native Play Services binding, which this
+     * package deliberately does not bundle. Pass `referrerProvider`, or install a
+     * supported referrer package and it is used automatically. Without either,
+     * Android falls back to signal matching.
+     */
+    claimDeferredLink(options: {
+        appspaceId: string;
+        referrerProvider?: ReferrerProvider;
+        /** Claim again even if an attempt was already recorded. For tests. */
+        force?: boolean;
+    }): Promise<DeferredLink | null>;
+    private alreadyAttempted;
+    private rememberAttempt;
     /** Claim a deferred deep link by device signal matching */
     claimBySignals(options: ClaimBySignalsOptions): Promise<DeferredLink | null>;
+    /**
+     * The signal claim, with whether the server actually answered.
+     *
+     * `settled` separates "nothing is waiting for this device", which no amount
+     * of asking will change, from "the request never got there". Both surface as
+     * null to callers of claimBySignals, but claimDeferredLink has to tell them
+     * apart: recording an attempt that never reached the server would spend an
+     * install's one chance at attribution on a dropped connection.
+     */
+    private attemptSignals;
 }
 
 /**
@@ -334,7 +393,7 @@ declare class Deferred {
  *   await Tolinku.track('signup', { source: 'onboarding' });
  */
 declare class Tolinku {
-    static readonly VERSION = "0.1.0";
+    static readonly VERSION = "0.4.0";
     private static client;
     private static analyticsInstance;
     private static ecommerceInstance;
@@ -348,6 +407,15 @@ declare class Tolinku {
      * If init() is called a second time without calling destroy() first,
      * a warning is logged and the existing instance is returned.
      */
+    /**
+     * Configure the SDK.
+     *
+     * The name the Android, iOS and Flutter SDKs use for this. {@link init} does
+     * the same thing and still works; it is what this package shipped and
+     * breaking it would serve nobody. It is meant for deprecation later, once
+     * moving off it is a one-line change rather than a surprise.
+     */
+    static configure(config: TolinkuConfig): void;
     static init(config: TolinkuConfig): void;
     /** Check whether the SDK has been initialized. */
     static isConfigured(): boolean;
@@ -413,4 +481,4 @@ declare function TolinkuMessages({ trigger, triggerValue, onDismiss, onButtonPre
  */
 declare function isSafeUrl(url: string): boolean;
 
-export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, isSafeUrl };
+export { type AddPaymentInfoParams, type AddToCartParams, type AddToWishlistParams, type BeginCheckoutParams, type ClaimBySignalsOptions, type CompleteReferralOptions, type CompleteReferralResult, type CreateReferralOptions, type CreateReferralResult, type DeferredLink, type EcommerceItem, type LeaderboardEntry, type Message, type MessageComponent, type MessageContent, type MilestoneOptions, type MilestoneResult, type PurchaseParams, type RateParams, type ReferralInfo, type ReferrerProvider, type RefundParams, type RemoveFromCartParams, type ResolvedTolinkuConfig, type SearchParams, type ShareParams, type ShowMessageOptions, type SpendCreditsParams, Tolinku, type TolinkuConfig, TolinkuError, TolinkuMessages, type TrackProperties, type ViewItemParams, getInstallReferrerToken, isSafeUrl, parseInstallReferrer };

package/dist/index.js

@@ -10,7 +10,7 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 var AsyncStorage__default = /*#__PURE__*/_interopDefault(AsyncStorage);
 
 // src/types.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.4.0";
 
 // src/debug.ts
 var _debugEnabled = false;
@@ -630,41 +630,150 @@ var Referrals = class {
     });
   }
 };
+var TOKEN_KEY = "tolk_token";
+function parseInstallReferrer(referrer) {
+  if (!referrer || !referrer.trim()) return null;
+  let decoded = referrer;
+  try {
+    decoded = decodeURIComponent(referrer);
+  } catch {
+  }
+  const pair = decoded.split("&").map((p) => p.trim()).find((p) => p.startsWith(`${TOKEN_KEY}=`));
+  if (!pair) return null;
+  const token = pair.slice(TOKEN_KEY.length + 1);
+  return token.trim() ? token : null;
+}
+function nativeProvider() {
+  const native = reactNative.NativeModules?.TolinkuInstallReferrer;
+  if (!native || typeof native.getInstallReferrer !== "function") return null;
+  return () => native.getInstallReferrer();
+}
+async function getInstallReferrerToken(provider) {
+  if (reactNative.Platform.OS !== "android") return null;
+  const source = provider ?? nativeProvider();
+  if (!source) return null;
+  try {
+    const referrer = await source();
+    return parseInstallReferrer(referrer);
+  } catch (err) {
+    debugWarn(`Install referrer lookup failed: ${err.message}`);
+    return null;
+  }
+}
+
+// src/deferred.ts
+var CLAIMED_KEY = "tolinku_deferred_claimed";
 var Deferred = class {
   constructor(client) {
     this.client = client;
   }
   /** Claim a deferred deep link by referrer token (from Play Store referrer or clipboard) */
-  async claimByToken(token) {
+  async claimByToken(token, appspaceId) {
     if (!token || !token.trim()) {
       throw new Error("Tolinku: token is required and must not be blank for claimByToken.");
     }
     try {
-      return await this.client.getPublic("/v1/api/deferred/claim", { token });
+      return await this.client.getPublic("/v1/api/deferred/claim", {
+        token,
+        ...appspaceId ? { appspace_id: appspaceId } : {}
+      });
     } catch (err) {
       debugWarn(`Deferred claimByToken failed: ${err.message}`);
       return null;
     }
   }
+  /**
+   * Recover the link that led to this install, trying both mechanisms.
+   *
+   * The Play Install Referrer is asked first on Android: it names the exact
+   * click, survives for days, and does not care which network the device was
+   * on. Device signals are the fallback, and the only option on iOS, where no
+   * equivalent exists.
+   *
+   * Call once on first launch. Safe to call again, but a claim is consumed the
+   * first time it succeeds, so a second call returns null.
+   *
+   * Reading the referrer needs a native Play Services binding, which this
+   * package deliberately does not bundle. Pass `referrerProvider`, or install a
+   * supported referrer package and it is used automatically. Without either,
+   * Android falls back to signal matching.
+   */
+  async claimDeferredLink(options) {
+    if (!options.appspaceId || !options.appspaceId.trim()) {
+      throw new Error("Tolinku: appspaceId is required and must not be blank for claimDeferredLink.");
+    }
+    if (!options.force && await this.alreadyAttempted()) return null;
+    const token = await getInstallReferrerToken(options.referrerProvider);
+    if (token) {
+      const byToken = await this.claimByToken(token, options.appspaceId).catch(() => null);
+      if (byToken) {
+        await this.rememberAttempt();
+        return byToken;
+      }
+    }
+    const { link, settled } = await this.attemptSignals({ appspaceId: options.appspaceId });
+    if (settled) await this.rememberAttempt();
+    return link;
+  }
+  async alreadyAttempted() {
+    try {
+      return await AsyncStorage__default.default.getItem(CLAIMED_KEY) !== null;
+    } catch {
+      return false;
+    }
+  }
+  async rememberAttempt() {
+    try {
+      await AsyncStorage__default.default.setItem(CLAIMED_KEY, (/* @__PURE__ */ new Date()).toISOString());
+    } catch {
+    }
+  }
   /** Claim a deferred deep link by device signal matching */
   async claimBySignals(options) {
     if (!options.appspaceId || !options.appspaceId.trim()) {
       throw new Error("Tolinku: appspaceId is required and must not be blank for claimBySignals.");
     }
+    return (await this.attemptSignals(options)).link;
+  }
+  /**
+   * The signal claim, with whether the server actually answered.
+   *
+   * `settled` separates "nothing is waiting for this device", which no amount
+   * of asking will change, from "the request never got there". Both surface as
+   * null to callers of claimBySignals, but claimDeferredLink has to tell them
+   * apart: recording an attempt that never reached the server would spend an
+   * install's one chance at attribution on a dropped connection.
+   */
+  async attemptSignals(options) {
     try {
       const { width, height } = reactNative.Dimensions.get("screen");
       const resolvedTimezone = options.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
-      const resolvedLanguage = options.language || "en";
-      return await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
+      const resolvedLanguage = options.language || (typeof Intl !== "undefined" && typeof Intl.DateTimeFormat === "function" ? Intl.DateTimeFormat().resolvedOptions().locale : void 0) || "en";
+      const link = await this.client.postPublic("/v1/api/deferred/claim-by-signals", {
         appspace_id: options.appspaceId,
         timezone: resolvedTimezone,
         language: resolvedLanguage,
         screen_width: options.screenWidth || width,
-        screen_height: options.screenHeight || height
+        screen_height: options.screenHeight || height,
+        // Separates devices reporting identical dp dimensions.
+        device_pixel_ratio: options.devicePixelRatio || reactNative.PixelRatio.get(),
+        os_version: options.osVersion || String(reactNative.Platform.Version)
       });
+      return { link, settled: true };
     } catch (err) {
+      const status = err?.statusCode ?? err?.status;
+      if (status === 404) {
+        debugWarn("Deferred claimBySignals: no match for this device.");
+        return { link: null, settled: true };
+      }
+      if (status === 403) {
+        console.warn(
+          `[Tolinku] claimBySignals failed with HTTP 403. Check that appspaceId is your Appspace ID (copy it from the dashboard under Settings), not your subdomain or slug. ${err.message}`
+        );
+        return { link: null, settled: false };
+      }
       debugWarn(`Deferred claimBySignals failed: ${err.message}`);
-      return null;
+      return { link: null, settled: false };
     }
   }
 };
@@ -754,6 +863,17 @@ var _Tolinku = class _Tolinku {
    * If init() is called a second time without calling destroy() first,
    * a warning is logged and the existing instance is returned.
    */
+  /**
+   * Configure the SDK.
+   *
+   * The name the Android, iOS and Flutter SDKs use for this. {@link init} does
+   * the same thing and still works; it is what this package shipped and
+   * breaking it would serve nobody. It is meant for deprecation later, once
+   * moving off it is a one-line change rather than a surprise.
+   */
+  static configure(config) {
+    _Tolinku.init(config);
+  }
   static init(config) {
     if (!config.apiKey) throw new Error("Tolinku: apiKey is required");
     if (_Tolinku._initialized) {
@@ -1191,6 +1311,8 @@ function TolinkuMessages({
 exports.Tolinku = Tolinku;
 exports.TolinkuError = TolinkuError;
 exports.TolinkuMessages = TolinkuMessages;
+exports.getInstallReferrerToken = getInstallReferrerToken;
 exports.isSafeUrl = isSafeUrl;
+exports.parseInstallReferrer = parseInstallReferrer;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map