Skip to main content
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.

​
Subscribe to resolved and failed events (optional)

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). 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

ConstraintDetails
Android & iOSBoth platforms implement handleLink and emit DeepLinkResolved / DeepLinkFailed.
Configure firstCall configure({ apiKey }) before handleLink() or events; otherwise the native side may throw (e.g. “SDK not configured”).
Activity requiredCall configure() after the app has an Activity (e.g. in root component). Calling too early can yield a NO_ACTIVITY error.
Rebuild after installAfter adding or updating the package, run npx react-native run-android. Otherwise you get “Native module not found”.
Single API keyThe SDK keeps one apiKey per process (from the last configure()). All requests use that key.
handleLink(url)url must be a non-empty string.
SubscriptionsonDeepLinkResolved and onDeepLinkFailed return a subscription; call .remove() in your effect cleanup to avoid leaks.
BackendBy 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