React Native SDK

Deep link resolution, the install referrer, attribution, queues, retries, device signals and networking all live in the native SDKs, shared with every other Deeplinkly integration. Native method names match those SDKs' own entry points one-for-one, and validation is enforced natively rather than in JavaScript — so a native-only integration and this package give the same answer for the same input.

• React Native: developed against 0.87 with React 19. Both the new and legacy architectures are supported from one import path.
• Android: minSdk 24, compileSdk 35, JVM target 17. Wraps com.deeplinkly:deeplinkly-android:1.3.0.
• iOS: deployment target 13.0, Swift 5. Wraps pod Deeplinkly 1.2.1. The paste control is iOS 16+ and ATT is iOS 14+, both weak-linked at runtime rather than raising the floor.
• API key: set natively, per platform — never hard-coded in JavaScript. You can create a key in App Settings.

Native key names

npm install react-native-deeplinkly
cd ios && pod install

Android autolinks and needs no manifest entries of its own: the install referrer receiver and the INTERNET permission arrive transitively from the native SDK.

Android build requirement — Kotlin 2.2.0

The native Android SDK is compiled with Kotlin 2.2.0, and a 2.0.x compiler cannot read its metadata. Gradle loads one Kotlin plugin for the whole build, so this is set by your app, not by the library:

// android/build.gradle
buildscript {
    ext {
        kotlinVersion = "2.2.0"
    }
    dependencies {
        // Version it explicitly. Left bare — as the React Native template has
        // it — the version arrives transitively from react-native-gradle-plugin
        // and ext.kotlinVersion is silently ignored.
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
    }
}

React Native 0.87's template already sets kotlinVersion = "2.2.0" but still leaves the classpath entry unversioned, so the version arrives transitively from react-native-gradle-plugin and ext.kotlinVersion is silently ignored. The library checks the resolved version at configuration time and fails with this instruction rather than letting the compiler emit an internal error that names nothing.

Subscribing is what tells native you are ready. Links that resolved before then — a cold start from a tap, or a deferred link recovered from the pasteboard — are buffered natively and delivered on subscribe, so nothing races your bundle.

import { useEffect } from 'react';
import Deeplinkly from 'react-native-deeplinkly';

export function DeeplinklyBootstrap() {
  useEffect(() => {
    // Subscribing is what signals readiness to native. Links that resolved
    // before now — a cold start from a tap, or a deferred link recovered from
    // the pasteboard — are buffered natively and delivered here, so nothing
    // races your bundle.
    const sub = Deeplinkly.addListener(({ click_id, params }) => {
      navigate(params.screen as string);
    });

    return () => sub.remove();
  }, []);

  return null;
}

Payload envelope — identical on Android and iOS

{
  click_id: 'ab12…',          // null if the backend did not recognise the click
  params: { screen: 'home' }, // the link's own parameters
}

<activity android:name=".MainActivity" android:launchMode="singleTask">
  <!-- App Links. This is the one that matters: it lets a tap on
       https://links.yourapp.com/abc123 open the app directly. Without it
       every link detours through the browser, and in-app browsers that
       block intent:// URLs (Instagram, Facebook, TikTok) never reach your
       app at all — even when it is installed.
       autoVerify only does anything on http/https. -->
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="links.yourapp.com" />
  </intent-filter>

  <!-- Custom scheme. The browser fallback path uses this, so keep it —
       but it is a fallback, not a substitute for the filter above. -->
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="yourapp" />
  </intent-filter>
</activity>

<application ...>
  <meta-data
      android:name="com.deeplinkly.sdk.api_key"
      android:value="your_api_key_here" />

  <!-- Optional, but set it if the app App Links any host besides its
       Deeplinkly link domain. Comma separated. -->
  <meta-data
      android:name="com.deeplinkly.sdk.link_domains"
      android:value="links.yourapp.com" />
</application>

Replace links.yourapp.com with your Deeplinkly link domain, and yourapp with the URI scheme you set in the dashboard.

React Native's template already sets launchMode="singleTask", which delivers a warm deep link through onNewIntent — that is what the SDK needs. Do not change it to standard, which would start a second activity instance per link instead.

Which links the SDK claims

The rule is the same on both platforms. A link that came through the redirect carries a click_id, and the SDK acts on that whatever the scheme. The ambiguous case is the App Link / Universal Link bypass, where the OS routes https://links.yourapp.com/<code> straight to the app and the first path segment is the only thing there is to resolve on. So:

• Custom-scheme URLs without a click_id are ignored. Your own routes (yourapp://settings/notifications) are yours; the SDK will not resolve them.
• http(s) URLs are resolved by code. If the link-domains list is set, only those hosts are; without it every https link the app handles is, which is fine for an app whose only App Link filter is its link domain.

Verifying App Links

Android checks https://<your-link-domain>/.well-known/assetlinks.json on install. Deeplinkly serves that file for you, but only once the dashboard has both your package name and your SHA-256 signing certificate fingerprint — with either missing the endpoint returns 404 and verification silently fails.

# The SHA-256 fingerprint the dashboard needs.
keytool -list -v -keystore <your-keystore> -alias <your-alias> | grep SHA256

# Confirm the file is live and verification passed.
curl https://links.yourapp.com/.well-known/assetlinks.json
adb shell pm get-app-links <your.package.name>

If you use Play App Signing, take the fingerprint from Play Console → Test and release → Setup → App signing, not from your upload keystore — Google re-signs the APK, so the upload fingerprint will not match what ships. pm get-app-links should report verified for your domain; none or legacy_failure means the fingerprint does not match or the file is not reachable.

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourapp</string>
    </array>
  </dict>
</array>

<key>DeeplinklyApiKey</key>
<string>your_api_key_here</string>

<!-- Your Deeplinkly link domains. Subdomains count. Two jobs: the hosts a
     deferred link may be read from, and the hosts whose first path segment
     may be read as a link code. Set it if the app Universal Links any host
     besides its link domain. -->
<key>DeeplinklyLinkDomains</key>
<array>
  <string>yourbrand.deeplinkly.com</string>
</array>

Then add an Associated Domains capability with applinks:yourbrand.deeplinkly.com for each link domain.

import react_native_deeplinkly

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {
    // ... existing React Native setup ...

    // Cold launch. A Universal Link that *starts* the app is in launchOptions,
    // not in continue(userActivity:) — missing this loses exactly the case
    // deferred deep linking exists for.
    RNDeeplinklyLinking.handleLaunchOptions(launchOptions)
    return true
  }

  // Universal Links while running.
  func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
  ) -> Bool {
    RNDeeplinklyLinking.handleUserActivity(userActivity)
    return RCTLinkingManager.application(
      application, continue: userActivity, restorationHandler: restorationHandler)
  }

  // Custom-scheme links.
  func application(
    _ app: UIApplication,
    open url: URL,
    options: [UIApplication.OpenURLOptionsKey: Any] = [:]
  ) -> Bool {
    RNDeeplinklyLinking.handleURL(url)
    return RCTLinkingManager.application(app, open: url, options: options)
  }
}

Calling RCTLinkingManager as well keeps JS Linking working — the Deeplinkly call is non-exclusive.

If your app uses a SceneDelegate

When the host adopts UISceneDelegate, the UIApplicationDelegate callbacks above never fire. Use these three instead:

func scene(
  _ scene: UIScene,
  willConnectTo session: UISceneSession,
  options connectionOptions: UIScene.ConnectionOptions
) {
  // Cold launch on the scene path.
  RNDeeplinklyLinking.handleSceneConnectionOptions(connectionOptions)
}

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  RNDeeplinklyLinking.handleUserActivity(userActivity)
}

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
  RNDeeplinklyLinking.handleOpenURLContexts(URLContexts)
}

From an Objective-C AppDelegate

Import the generated Swift header instead:

#if __has_include(<react_native_deeplinkly/react_native_deeplinkly-Swift.h>)
#import <react_native_deeplinkly/react_native_deeplinkly-Swift.h>
#else
#import "react_native_deeplinkly-Swift.h"
#endif

[RNDeeplinklyLinking handleURL:url];

The two forms cover framework and static-library linkage respectively.

The Deeplinkly interstitial copies the link when the visitor taps through to the store, and the SDK reads it back on first launch. There are two ways to read it back — pick one.

Option A — <DeeplinklyPasteButton> (recommended, no banner)

A system paste button rendered in your component tree. Because the user taps it themselves, iOS treats the tap as the grant and shows no “Pasted from…” banner at all.

import { DeeplinklyPasteButton } from 'react-native-deeplinkly';

<DeeplinklyPasteButton
  onPasted={(handled) => setShowPasteButton(!handled)}
  fallback={null}
/>;

Put it on a first-run screen next to something like “Tapped a link to get here? Restore where you left off.” The recovered link arrives on your normal listener exactly like any other; onPasted only tells you whether the pasted content was one of your links, so you can hide the button or explain that it was not.

Requires iOS 16+. Renders fallback on Android and older iOS, so it is safe to place unconditionally — isPasteButtonSupported is exported for hosts that want to change surrounding copy rather than just the button. The control has an intrinsic size React Native's layout does not read, so it defaults to 140×40; override with style. Other props are displayMode (iconOnly | labelOnly | iconAndLabel), cornerStyle (small | medium | large | capsule), backgroundColor and foregroundColor.

Option B — automatic read (on by default, shows the banner)

On by default; you do not need to enable it. To turn it off:

<key>DeeplinklyCheckPasteboardOnInstall</key>
<false/>

Do that in Info.plist, not from JavaScript — the read happens during native module construction, before your JS runs, so setCheckPasteboardOnInstall(false) arrives too late to prevent the first one. Turning it on from JS at runtime reads immediately rather than waiting for a next launch the pasteboard may not survive to.

To explain the prompt before it appears, turn the automatic read off in Info.plist and drive it yourself:

if (await Deeplinkly.willShowPasteboardBanner()) {
  await showMyPrimingDialog(); // "we can restore where you left off"
  await Deeplinkly.checkPasteboardNow();
}

willShowPasteboardBanner reads no content and shows no banner itself.

import Deeplinkly from 'react-native-deeplinkly';

const attribution = await Deeplinkly.getInstallAttribution();
const deeplinklyId = await Deeplinkly.getDeeplinklyId();

// custom_user_id, for enrichment and backend user linking.
Deeplinkly.setUserId('user_123');
Deeplinkly.setUserId(null); // clear on logout

getDeeplinklyId is the stable per-install id — the same value the API sees as deeplinkly_device_id / X-Deeplinkly-User-Id. setUserId sets custom_user_id for enrichment and backend user linking.

import Deeplinkly from 'react-native-deeplinkly';

// Returns false if any field was malformed, in which case nothing was stored.
const ok = await Deeplinkly.setUserData({
  userId: 'user_123',
  email: 'ada@example.com',
  phoneNumber: '+441234567890',
  firstName: 'Ada',
  lastName: 'Lovelace',
  city: 'London',
  country: 'GB',
});

Every field is optional and each call merges, so you can supply an email at sign-up and an address at checkout. A malformed field rejects the whole call — nothing is stored — so a rejected call never leaves you guessing which of the values took.

Validation is native, so a native-only integration gets the same answer this one does. These fields survive a reduced downgrade, because attribution levels gate what the SDK observes about a device and an email someone typed into your app is not an observation. At none nothing is sent.

• dateOfBirth: YYYY-MM-DD.
• gender: 'm' or 'f' — the only two values Meta's ge accepts. Anything else is refused rather than coerced.
• country: ISO-3166-1 alpha-2, for example 'US'.
• Every field has a maximum length, enforced before anything is stored.

Your own identifiers

customData carries identifiers Deeplinkly does not name — typically product-analytics ids such as a Mixpanel distinct id or a CleverTap id. Attach a new identifier anytime; no app release required.

await Deeplinkly.setUserData({
  userId: 'user_123',
  customData: {
    mixpanel_distinct_id: 'd-8837',
    clevertap_id: 'ct-4412',
  },
});

Up to 10 entries, keys up to 64 characters and values up to 256, enforced natively. Anything larger rejects the whole call, as one bad typed field does.

Erasing it

Deeplinkly.clearUserData(); // erases everything setUserData and setUserId recorded
Deeplinkly.setUserId(null); // clears only the id

This is not merely “stop sending”: the next enrichment carries each previously-set field as an empty value, which the service reads as null this column rather than not reported. The erasure is re-sent until it is delivered, so calling it on a device that is offline still takes effect once it is not.

import Deeplinkly, { DeeplinklyEvent } from 'react-native-deeplinkly';

const ok = await Deeplinkly.logEvent(DeeplinklyEvent.purchase, {
  order_id: 'ord_42',
  amount: 49.99,
  currency: 'INR',
});

DeeplinklyEvent holds the well-known names the backend reports on without extra configuration (purchase, add_to_cart, signup, and so on); any string is accepted for your own funnels.

Validation

• Event name: non-empty after trimming, at most 64 characters.
• At most 25 custom parameters. The SDK's own _dl_* keys do not count toward this, and passing a key with that prefix is rejected.
• Parameter keys: max 64 characters.
• Parameter string values: max 256 characters.
• Array and object values are stored as compact JSON, and the 256 limit applies to that encoded form.
• null values are rejected, not dropped. So is any type other than string, number, boolean, array or object.

Numbers and booleans keep their JSON types end to end — 49.99 is stored as a number, not "49.99". A rejected event resolves false and sends nothing.

await Deeplinkly.logPurchase({
  value: 49.99,
  currency: 'USD',
  orderId: 'ord_42',
  quantity: 1,
  productId: 'sku_9',
});

Not a separate pipeline: it sends the event named purchase with value and currency set, so everything true of logEvent — the retry queue, the parameter limits, the device block — is true of this too.

value and currency are what Meta's Conversions API and Google's enhanced conversions both key off, so this one call feeds both without you having to match their spelling.

Rejected, sending nothing, if the value is negative or not finite (a refund is a different event, not a negative purchase), the currency is not three letters, the quantity is negative, or parameters contains any of value, currency, order_id, quantity or product_id — pass those as fields instead.

const result = await Deeplinkly.generateLink(
  {
    canonicalIdentifier: 'product/sku_42',
    title: 'Pro Plan',
    metadata: { plan: 'pro' },
  },
  {
    channel: 'email',
    feature: 'upgrade_campaign',
    tags: ['spring', 'sale'],
  }
);

if (result.success) {
  Share.share({ message: result.url! });
} else {
  // camelCase, not the snake_case that crosses the bridge.
  console.warn(result.errorCode, result.errorMessage);
}

The result is { success, url?, errorCode?, errorMessage? }. It resolves rather than rejecting on failure. Observed errorCode values: SDK_DISABLED, INVALID, NO_URL, LINK_ERROR, HTTP_<status>, NULL_NATIVE_RESPONSE, NATIVE_EXCEPTION, or a backend code passed through.

await Deeplinkly.setTrackingEnabled(false);      // the consent-flow off switch
await Deeplinkly.setAttributionLevel('reduced'); // a middle ground
await Deeplinkly.resetPrivacyData();             // forget this device

setTrackingEnabled(false) sends no enrichment, no events and no error reports, skips the iOS pasteboard read, and deletes pending reporting retries. Deep links still resolve and are still delivered — the link a user tapped keeps working — but functional requests omit the stable Deeplinkly ID and custom user ID. It persists across launches.

resetPrivacyData() removes the stable Deeplinkly ID, custom user ID, attribution, cached device profile, session and event state, pasteboard state and pending queues. Tracking stays disabled afterwards; call setTrackingEnabled(true) only once the user opts back in.

Hashing identifiers on the device

Off by default. With it on, the email, phone number and names given to setUserData are SHA-256 hashed on the device, so the plaintext never leaves it.

await Deeplinkly.setPIIHashingEnabled(true); // SHA-256 on device before sending
await Deeplinkly.isPIIHashingEnabled();     // off unless you turned it on

Only those four are hashed. Gender, country and date of birth are not: their value ranges are small enough that a digest is reversed by enumerating them, so hashing them would be protection in appearance only.

Each level is a strict subset of the one above. Deep link delivery works at every level, including none — this restricts reporting, not functionality. Resolving a link never sends anything describing the device, at any level. setTrackingEnabled(false) wins over the level: while disabled, getAttributionLevel() reports none whatever was set.

To start restricted before any JavaScript runs — enrichment can be sent during native module construction, before a JS call could arrive — set it natively:

<key>DeeplinklyAttributionLevel</key>
<string>reduced</string>

<meta-data
    android:name="com.deeplinkly.sdk.attribution_level"
    android:value="reduced" />

The package's docs/SIGNALS.md is the field-by-field reference: every signal the SDK can send, its level, and which platforms report it. It is generated from the same catalogue the SDKs compile against, so it cannot drift from what is actually sent.

isAvailable() returns false and the rest degrade in place — logEvent resolves false, getAttributionLevel resolves none, generateLink resolves { success: false, errorCode: 'SDK_DISABLED' }. getDeeplinklyId and resetPrivacyData keep working, since they are local operations that need no key.

Each method carries its own correctly-typed default rather than sharing one SDK_DISABLED envelope: a typed native module cannot resolve a map where it declared a boolean, so an envelope would break the contract for every method that does not return an object. isAvailable() is what tells you the key is missing — assert it once on a debug build, since a missing key is a configuration bug rather than a runtime condition.

if (__DEV__ && !(await Deeplinkly.isAvailable())) {
  console.warn('Deeplinkly: no API key in AndroidManifest.xml / Info.plist');
}

Deeplinkly.setDebugMode(__DEV__);

Generate a link with generateLink, then open it. A URL with no click_id and no Deeplinkly short code is skipped by design, so yourapp://open?screen=home will never deliver anything — use a generated link.

# iOS Simulator
xcrun simctl openurl booted "https://<your-link-domain>/<code>"

# Android device or emulator
adb shell "am start -W -a android.intent.action.VIEW \
  -d 'https://<your-link-domain>/<code>' -p com.yourapp"

Verify cold start (process killed) and warm start (app backgrounded) separately. Two constraints worth planning around:

• Android: the Install Referrer is unavailable on sideloaded builds — test deferred flows through Play internal testing.
• iOS: deferred deep linking cannot be tested on the Simulator (no App Store). The automatic read is once per install and clears the pasteboard, so reinstall to retest — relaunching will not repeat it.