What This Guide Covers

Firebase Dynamic Links is gone. If you're migrating your React Native app to HopLinks — or starting fresh — this guide walks you through the complete integration. We cover both the React Native CLI path and the Expo path (Expo SDK 54+), including deferred deep linking for new installs.

How HopLinks Deep Linking Works

HopLinks works entirely through native OS protocols — Universal Links (AASA) on iOS and Android App Links (Digital Asset Links) on Android. There is no proprietary SDK to install in your app. HopLinks automatically hosts the verification files on your behalf based on what you enter in the dashboard.

The deferred deep linking flow works in four stages:

1. Click — user taps a HopLink on any platform.
2. Install — if the app isn't installed, they're redirected to the App Store or Google Play.
3. Match — on first app launch, HopLinks identifies the user via device fingerprinting and matches them to the original click.
4. Route — the app opens directly to the intended destination, not the generic home screen.

"Standard deep links fail if the app isn't installed. Deferred Deep Links 'remember' the destination during the installation process, ensuring the user lands exactly where they intended after their first launch."

— HopLinks Developer Guide

Before touching any code, register your app in the HopLinks dashboard. This is what activates the AASA and assetlinks.json endpoints that iOS and Android will verify.

1. Log into your HopLinks console and go to App Settings.
2. Create a new app configuration.
3. For Android: enter your Package Name and SHA-256 fingerprint.
4. For iOS: enter your Apple Team ID and Bundle Identifier.

Once saved, HopLinks automatically generates and serves the following files — you don't host anything yourself:

• /.well-known/assetlinks.json — for Android App Link verification
• /.well-known/apple-app-site-association — for iOS Universal Link verification

Both iOS and Android need to know which domain your app is authorized to handle. The HopLinks domain to use is www.hpln.in (or your custom domain if configured).

Android — AndroidManifest.xml

Add the following intent filter to your main activity in AndroidManifest.xml:

<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="www.hpln.in" />
</intent-filter>

iOS — Xcode Associated Domains

In Xcode, navigate to your target → Signing & Capabilities → add the Associated Domains capability. Then add:

applinks:www.hpln.in

If you're using the React Native CLI (not Expo), the built-in Linking module handles incoming deep links. No extra package needed.

import React, { useEffect, useState } from 'react';
import { Linking, Text, View } from 'react-native';

const App = () => {
  const [initialUrl, setInitialUrl] = useState(null);

  useEffect(() => {
    // 1. App opened from cold start (was not running)
    const getUrlAsync = async () => {
      const url = await Linking.getInitialURL();
      if (url) handleDeepLink(url);
    };
    getUrlAsync();

    // 2. App was already open in background
    const subscription = Linking.addEventListener('url', (event) => {
      handleDeepLink(event.url);
    });

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

  const handleDeepLink = (url) => {
    setInitialUrl(url);
    if (url.includes('/product/')) {
      const id = url.split('/').pop();
      console.log('Navigate to product ID:', id);
      // navigate('Explore', { id })
    }
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>Opened from: {initialUrl}</Text>
    </View>
  );
};

export default App;

Expo requires a few more configuration steps because the native build is managed by Expo's toolchain. Follow all 8 steps in order.

Step 4.1 — Install expo-linking

Always use npx expo install — not plain npm install — so Expo selects the version that matches your SDK.

npx expo install expo-linking

Step 4.2 — Configure app.json

Open app.json and add URL scheme, iOS associated domains, and Android intent filters:

{
  "expo": {
    "scheme": "myapp",
    "ios": {
      "bundleIdentifier": "com.example.myapp",
      "associatedDomains": [
        "applinks:www.hpln.in",
        "applinks:hoplinks.in"
      ]
    },
    "android": {
      "package": "com.example.myapp",
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            { "scheme": "https", "host": "www.hpln.in" },
            { "scheme": "https", "host": "hoplinks.in" }
          ]
        }
      ]
    }
  }
}

Step 4.3 — Configure React Navigation

Create a linking object that maps URL paths to screens, and pass it to NavigationContainer:

import * as Linking from 'expo-linking';
import { NavigationContainer } from '@react-navigation/native';

// Base prefix for Expo Go development URLs
const prefix = Linking.createURL('/');

const linking = {
  prefixes: [
    prefix,
    'myapp://',
    'https://www.hpln.in',
    'https://hoplinks.in',
  ],
  config: {
    screens: {
      Home:          'home',
      Explore:       'product/:id',   // :id is a dynamic param
      Notifications: 'notifications',
      Profile:       'profile',
    },
  },
};

export default function App() {
  return (
    <NavigationContainer linking={linking}>
      {/* Your navigator here */}
    </NavigationContainer>
  );
}

URL to Screen Mapping Reference

Step 4.4 — Read Parameters in Screens

React Navigation automatically injects URL segments as route params. Use the useRoute hook to access them:

import { useRoute } from '@react-navigation/native';
import { View, Text } from 'react-native';

export default function ExploreScreen() {
  const route = useRoute();
  const deepLinkId = route.params?.id; // from :id in the URL pattern

  return (
    <View>
      {deepLinkId && (
        <Text>You opened product: {deepLinkId}</Text>
      )}
    </View>
  );
}

Step 4.5 — Domain Verification (Automatic)

This step requires no code. HopLinks automatically generates and serves both verification files based on your App Settings in the dashboard. Simply ensure your Package Name, SHA-256 fingerprint (Android), Team ID, and Bundle ID (iOS) are correctly entered.

• Android: /.well-known/assetlinks.json — served automatically
• iOS: /.well-known/apple-app-site-association — served automatically

Step 4.6 — Testing the Integration

Testing approach depends on whether you're running Expo Go or a native build.

Testing in Expo Go — use ADB

adb shell am start -W -a android.intent.action.VIEW \
  -d "exp://127.0.0.1:8081/--/product/id123"

Testing Native Builds — use uri-scheme CLI

# Test the custom URI scheme first
npx uri-scheme open "myapp://product/id123" --android

# Once scheme works, test verified App Link
npx uri-scheme open "https://hoplinks.in/product/id123" --android

Step 4.7 — Configure HopLinks Dashboard Links

Each HopLinks short link needs an In-App Deep Link value that maps to a screen in your app. In the dashboard, after setting the standard destination URL (web fallback), scroll to the "Deep Link Intent" section and set the value:

How HopLinks uses these values at runtime:

• App installed: the phone intercepts the link and React Navigation routes to the correct screen.
• App not installed: the custom scheme fails silently; HopLinks redirects the user to the App Store or Google Play.

Step 4.8 — Handle Deferred Deep Linking

This is the critical step for preserving intent across installs. Without it, users who click a HopLink, install the app, and open it for the first time will land on the generic Home screen — not the content they originally clicked.

Add a getInitialURL() function to your linking config:

const linking = {
  prefixes: [prefix, 'myapp://', 'https://www.hpln.in', 'https://hoplinks.in'],

  // This catches the URL that originally launched the app
  async getInitialURL() {
    // Check if opened via a standard OS deep link
    const url = await Linking.getInitialURL();
    if (url != null) return url;

    // Optional: call HopLinks API for deferred link data
    // const deferredUrl = await Hoplinks.getDeferredLink();
    // if (deferredUrl) return deferredUrl;

    return null;
  },

  config: {
    screens: {
      Home:          'home',
      Explore:       'product/:id',
      Notifications: 'notifications',
      Profile:       'profile',
    },
  },
};

To verify the complete deferred flow: click a HopLinks URL on a device that does not have your app installed → install from the store → confirm the app opens the correct screen on first launch.

Quick Reference — Do's & Don'ts

Troubleshooting

Android — Links opening in browser instead of the app

• Confirm android:autoVerify="true" is present in the intent filter.
• Android can take up to 20 seconds after install to fetch and verify assetlinks.json. Try uninstalling and reinstalling the app before retesting.
• Check that the SHA-256 fingerprint in the HopLinks dashboard matches your current build (debug and release fingerprints are different).

iOS — Universal Links not triggering

• Confirm your Apple Team ID and Bundle ID in the HopLinks dashboard exactly match your Xcode settings — even a single character difference breaks verification.
• Universal Links only trigger from a "click" in an external app (Notes, Mail, WhatsApp). Pasting the URL into Safari's address bar will not trigger them.
• iOS fetches the AASA file at app install time, not at runtime. Reinstall the app after any changes.

Expo Go — https:// links not working

This is expected behavior. Expo Go cannot verify your AASA or assetlinks.json because its certificate doesn't match your app. Switch to a development build (npx expo run:android or npx expo run:ios) to test https:// links.

Frequently Asked Questions