react-native-smartlink

React Native / Expo SDK for SmartLink — deep links, deferred deep linking, and typed API helpers.

Requirements

• React Native 0.73+ (or Expo SDK that ships a compatible RN)
• react and react-native as peer dependencies
• A running SmartLink backend API and redirect server (staging or self-hosted)

Install

npm install react-native-smartlink
# or
yarn add react-native-smartlink
# or
pnpm add react-native-smartlink

Peers (usually already present in an RN/Expo app):

npm install react react-native

Quick start

import { useEffect } from 'react';
import { createDeeplinkSDK } from 'react-native-smartlink';

const sdk = createDeeplinkSDK({
  apiKey: 'your-api-key',
  apiUrl: 'https://api-smartlink.example.com',
  redirectUrl: 'https://go-smartlink.example.com',
});

export function DeepLinkBootstrap() {
  useEffect(() => {
    const unsubscribe = sdk.onDeepLink((params) => {
      // Cold start + runtime links
      // params.shortCode, params.query, params.customParams, ...
      console.log('Deep link:', params);
    });

    return () => {
      unsubscribe();
      sdk.stop();
    };
  }, []);

  return null;
}

onDeepLink starts Linking listeners automatically. You can also call sdk.start() / sdk.stop() yourself.

Configuration

| Option | Required | Description | |--------|----------|-------------| | apiKey | Yes | API key sent as X-API-Key on deferred match | | apiUrl | No | Backend base URL (default http://localhost:5000) | | redirectUrl | No | Redirect / link domain base URL (default http://localhost:4000) |

Environment variables (recommended)

EXPO_PUBLIC_API_URL=https://api-smartlink.example.com
EXPO_PUBLIC_REDIRECT_URL=https://go-smartlink.example.com
EXPO_PUBLIC_APP_SCHEME=myscheme

const sdk = createDeeplinkSDK({
  apiKey: process.env.EXPO_PUBLIC_API_KEY ?? 'your-api-key',
  apiUrl: process.env.EXPO_PUBLIC_API_URL,
  redirectUrl: process.env.EXPO_PUBLIC_REDIRECT_URL,
});

Deep link listener

const unsubscribe = sdk.onDeepLink((params) => {
  // params.url
  // params.path
  // params.shortCode
  // params.query          // all query string key/values
  // params.customParams
  // params.deferred       // true when from deferred match
});

Uses React Native Linking:

• Cold start: Linking.getInitialURL()
• Runtime: Linking.addEventListener('url', ...)

Parse a URL manually

import { parseDeepLinkParams } from 'react-native-smartlink';

const params = parseDeepLinkParams('myscheme://product/123?campaign=spring');
// params.shortCode, params.query, ...

Also works with https Universal / App Links:

parseDeepLinkParams('https://go-smartlink.example.com/abc123?utm_source=email');

Deferred deep linking

After install (user opened a SmartLink before the app was installed):

const result = await sdk.getDeferredDeepLink();

if (result.matched && result.params) {
  // Navigate using result.params
}

// Full server payload:
result.raw; // DeferredMatchResponse

Calls POST {redirectUrl}/v1/deferred/match. If you omit a fingerprint, the server can derive one from IP + User-Agent.

Optional fingerprint:

await sdk.getDeferredDeepLink('optional-client-fingerprint');

Navigation helpers

Wire the SDK to React Navigation / Expo Router:

sdk.setNavigator((screen, params) => {
  // navigation.navigate(screen, params)
});

sdk.navigateToScreen('ProductDetail', { productId: '123' });

Custom events (in-memory queue)

sdk.trackEvent('purchase', { amount: 99.99 });
sdk.getQueuedEvents(); // until server ingestion is enabled

Typed API client

const client = sdk.getApiClient();

await client.getBackendHealth();
await client.getRedirectHealth();
await client.matchDeferred({ fingerprint: 'optional' });

Native setup (scheme + Universal / App Links)

The SDK listens to URLs the OS delivers. You still must register schemes / domains in the host app.

Custom URL scheme (Expo)

In app.json / app.config.ts:

{
  "expo": {
    "scheme": "myscheme"
  }
}

Test on iOS simulator:

xcrun simctl openurl booted "myscheme://abc123?campaign=spring"

iOS Universal Links

1. In the SmartLink admin, set App Linking / Team ID for your org.
2. Ensure the redirect host serves /.well-known/apple-app-site-association.
3. Add associated domains in the app, e.g. applinks:go-smartlink.example.com.

Expo example:

ios: {
  associatedDomains: ['applinks:go-smartlink.example.com'],
}

Android App Links

1. Set SHA-256 cert fingerprint in SmartLink app-linking settings.
2. Ensure the redirect host serves /.well-known/assetlinks.json.
3. Add intent filters for your link host in the Android config / AndroidManifest.

Staging example URLs

If you use the project staging hosts:

| Service | URL | |---------|-----| | Backend API | https://api-smartlink.24livehost.com | | Redirect / short links | https://go-smartlink.24livehost.com |

createDeeplinkSDK({
  apiKey: 'your-key',
  apiUrl: 'https://api-smartlink.24livehost.com',
  redirectUrl: 'https://go-smartlink.24livehost.com',
});

API surface

import {
  createDeeplinkSDK,
  DeeplinkSDK,
  DeeplinkApiClient,
  parseDeepLinkParams,
  deepLinkParamsFromDeferred,
  subscribeToDeepLinks,
} from 'react-native-smartlink';

import type {
  DeeplinkSDKConfig,
  DeepLinkParams,
  DeepLinkListener,
  DeferredDeepLinkResult,
  HealthResponse,
  DeferredMatchRequest,
  DeferredMatchResponse,
} from 'react-native-smartlink';

Troubleshooting

| Problem | What to check | |---------|----------------| | Listener never fires | Scheme / associated domains / intent filters; try simctl openurl / adb with the same scheme | | Deferred match always matched: false | Redirect server deployed; recent click recorded; same network/IP as click when fingerprint is server-derived | | Health check fails | apiUrl / redirectUrl reachable from the device/emulator (not localhost on a physical device) | | TypeScript can’t resolve package | Restart TS server; ensure node_modules/react-native-smartlink/dist exists after install |

License

MIT