> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deeplink.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling links

> Respond to incoming deep link URLs in your React Native app

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:

```javascript theme={null}
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)`.

```javascript theme={null}
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](https://docs.deeplink.in).
* Use the [Track Install API](/api-reference/track-install) if you need to record installs outside the SDK.