Handling links

When a user opens a DeepLink URL (e.g. from an email or ad), your app can receive the URL and navigate to the right screen. Pass every deep link URL to the SDK with handleLink(url); the SDK sends it to your backend and fires resolved or failed events you can subscribe to. Register listeners in a useEffect so you can navigate or show errors. Clean up by calling .remove() on the returned subscriptions:

import { onDeepLinkResolved, onDeepLinkFailed } from 'deeplink-rn';
import { useEffect } from 'react';

useEffect(() => {
  const resolved = onDeepLinkResolved((event) => {
    console.log('Deep link resolved:', event.url);
    console.log('Metadata:', event.metadata);
    // Navigate or take action based on event.url / event.metadata
  });
  const failed = onDeepLinkFailed((event) => {
    console.log('Deep link failed:', event.error);
    console.log('Error code:', event.errorCode);
    console.log('Original URL:', event.originalUrl);
  });
  return () => {
    resolved.remove();
    failed.remove();
  };
}, []);

Resolved event: event.url (string), event.metadata (object; currently empty, can be extended later). Failed event: event.error (string), event.errorCode (e.g. "NETWORK_ERROR", "SERVER_ERROR"), event.originalUrl (string).

Pass every deep link URL to the SDK

Use React Native’s Linking API to get the URL, then call handleLink(url):

Cold start (app opened from link): Linking.getInitialURL() then handleLink(initialUrl).
Foreground (app already open): Linking.addEventListener('url', ...) and handleLink(event.url).

import { handleLink } from 'deeplink-rn';
import { Linking } from 'react-native';
import { useEffect } from 'react';

// Cold start: link that launched the app
useEffect(() => {
  const run = async () => {
    try {
      const initialUrl = await Linking.getInitialURL();
      if (initialUrl) handleLink(initialUrl);
    } catch (e) {
      console.error('Failed to get initial URL', e);
    }
  };
  run();
}, []);

// Foreground: link received while app is open
useEffect(() => {
  const sub = Linking.addEventListener('url', (event) => handleLink(event.url));
  return () => sub?.remove();
}, []);

Constraints

Constraint	Details
Android & iOS	Both platforms implement `handleLink` and emit `DeepLinkResolved` / `DeepLinkFailed`.
Configure first	Call `configure({ apiKey })` before `handleLink()` or events; otherwise the native side may throw (e.g. “SDK not configured”).
Activity required	Call `configure()` after the app has an Activity (e.g. in root component). Calling too early can yield a `NO_ACTIVITY` error.
Rebuild after install	After adding or updating the package, run `npx react-native run-android`. Otherwise you get “Native module not found”.
Single API key	The SDK keeps one `apiKey` per process (from the last `configure()`). All requests use that key.
`handleLink(url)`	`url` must be a non-empty string.
Subscriptions	`onDeepLinkResolved` and `onDeepLinkFailed` return a subscription; call `.remove()` in your effect cleanup to avoid leaks.
Backend	By default the SDK uses `https://api.lorrymithra.in/api/v1/sdk`. You can override with `configure({ endpoint })`.

Troubleshooting

Native module not found — Rebuild the app after installing the package (e.g. cd android && ./gradlew clean && cd .. then npx react-native run-android).
NO_ACTIVITY error — Call configure after the app has started (e.g. in root component), not from very early bootstrap.
No deep links received — Check that AndroidManifest.xml has the correct <intent-filter> for your scheme/host/path and that you open a URL that matches them.

Next steps

Create and test links in the Dashboard.
Use the Track Install API if you need to record installs outside the SDK.

Getting Started

Flutter SDK

React Native SDK

REST API

Pass every deep link URL to the SDK

Constraints

Troubleshooting

Next steps

​Subscribe to resolved and failed events (optional)

​Pass every deep link URL to the SDK

​Constraints

​Troubleshooting

​Next steps

Subscribe to resolved and failed events (optional)

Pass every deep link URL to the SDK

Constraints

Troubleshooting

Next steps