Deep linking

Learn how to use app/universal links to open your app from a standard web URL.

Universal links are different from standard deep links as they use regular HTTPS links to direct users to a specific route in your app. If a user doesn't have your app installed, the link will take them to the associated website. This allows you to send notification emails with links that work seamlessly on desktop web browsers while opening the content in your app on mobile. Android refers to this concept as app links, and iOS refers to it as universal links. This guide specifically discusses universal links that do not use a custom URL scheme.

Deferred deep links can be implemented with react-native-branch.

Before you can use an app/universal links, you have to setup the two-way association between the website and app for both Android and iOS:

1. Native app verification: This requires some form of code signing that references the target website domain (URL).
2. Website verification: This requires a file to be hosted on the target website in the /.well-known directory.

After the two-way association is setup, you have to setup the runtime routing of the link in your app. This is done in JavaScript and must be configured for every route, then coordinated between web and native. Expo offers a fully automated solution for this called Expo Router.

Universal links cannot be tested in the Expo Go app. You need to create a development build.

Universal links on iOS

Universal links on iOS require a paid Apple Developer account as you must associate your fully qualified Apple Developer Team ID.

Native Apple configuration

After deploying your apple-app-site-association (AASA) file, you must also configure your app to use your associated domain:

Add expo.ios.associatedDomains to your app config, and make sure to follow Apple's specified format. Make sure not to include the protocol (https) in your URL. This is a common mistake that will result in the universal links not working.

For example, if an associated website is https://expo.dev/, the app links are:

{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:expo.dev"]
    }
  }
}

Build your native app with EAS Build to ensure the entitlement is registered with Apple.

<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:expo.dev</string>
</array>

AASA configuration

On the web-side, you have to host a config file from /.well-known/apple-app-site-association (with no extension). This file JSON specifies your Apple Developer Team ID, Bundler ID, and a list of supported paths to redirect to the native app.

You can run the experimental CLI command npx setup-safari to automatically register a bundle identifier to your Apple account, assign entitlements to the ID, and create an iTunes app entry in the store. The local setup will be printed and you can skip most the following. This is the easiest way to get started with universal links on iOS.

If you're using Expo Router to build your website (or another modern React framework like Remix, Next.js, and so on), create the file at public/.well-known/apple-app-site-association. Legacy Expo webpack projects can create the file at web/.well-known/apple-app-site-association.

{
  // This section enables Universal Links
  "applinks": {
    "apps": [],
    "details": [
      {
        // Example: "QQ57RJ5UTD.com.acme.myapp"
        "appID": "{APPLE_TEAM_ID}.{BUNDLE_ID}",
        // All paths that should support redirecting
        "paths": ["/records/*"]
      }
    ]
  },
  // This section enables Apple Handoff
  "activitycontinuation": {
    "apps": ["{APPLE_TEAM_ID}.{BUNDLE_ID}"]
  },
  // This section enable Shared Web Credentials
  "webcredentials": {
    "apps": ["{APPLE_TEAM_ID}.{BUNDLE_ID}"]
  }
}

This snippet tells iOS that any links to https://www.myapp.io/records/* (with wildcard matching for the record ID) should be opened directly by the app with a matching bundle identifier. It is a combination of the Team ID and the app bundle identifier. The Team ID can be found under the membership details in the Apple Developer account.

The activitycontinuation and webcredentials objects are optional, but recommended.

After you have setup the AASA file, deploy your website to a server that supports HTTPS (most modern web hosts).

See Apple's documentation for further details on the format of the AASA. Branch provides an AASA validator which can help you confirm that your AASA is correctly deployed and has a valid format.

The * wildcard does not match domain or path separators (periods and slashes).

As of iOS 13, a new details format is supported which allows you to specify:

• appIDs instead of appID, which makes it easier to associate multiple apps with the same configuration
• an array of components, which allows you to specify fragments, exclude specific paths, and add comments

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app", "ABCDE12345.com.example.app2"],
        "components": [
          {
            "#": "no_universal_links",
            "exclude": true,
            "comment": "Matches any URL whose fragment equals no_universal_links and instructs the system not to open it as a universal link"
          },
          {
            "/": "/buy/*",
            "comment": "Matches any URL whose path starts with /buy/"
          },
          {
            "/": "/help/website/*",
            "exclude": true,
            "comment": "Matches any URL whose path starts with /help/website/ and instructs the system not to open it as a universal link"
          },
          {
            "/": "/help/*",
            "?": {
              "articleNumber": "????"
            },
            "comment": "Matches any URL whose path starts with /help/ and which has a query item with name 'articleNumber' and a value of exactly 4 characters"
          }
        ]
      }
    ]
  }
}

To support all iOS versions, you can provide both the above formats in your details key, but we recommend placing the configuration for more recent iOS versions first.

Note that iOS will download your AASA when your app is first installed and when updates are installed from the App Store, but it will not refresh any more frequently. If you wish to change the paths in your AASA for a production app, you will need to issue a full update via the App Store so that all of your users' apps re-fetch your AASA and recognize the new paths.

Now, a link to your website on your mobile device should open your app. If it doesn't, re-check the previous steps to ensure that your AASA is valid, the path is specified in the AASA, and you have correctly configured your App ID in the Apple Developer Console. Once you have got your app opened, move to the Handling links into your app section for details on how to handle the inbound link and show the user the content they requested.

Apple Smart Banner

If a user doesn't have your app installed, they'll be directed to the website. You can use the Apple Smart Banner to show a banner at the top of the page that prompts the user to install the app. The banner only shows if the user is on a mobile device and doesn't have the app installed.

To enable the banner, add the following meta tag to the <head> of your website, replacing {ITUNES_ID} with your app's iTunes ID:

<meta name="apple-itunes-app" content="app-id={ITUNES_ID}" />

If you're having trouble setting up the banner, run the following command to automatically generate the meta tag for your project:

If you're building a statically rendered website with Expo Router, then add this HTML tag to the <head> component in your app/+html.js file.

export default function Root({ children }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />

        <meta name="apple-itunes-app" content="app-id={ITUNES_ID}" />

        {/* Other head elements... */}
      </head>
      <body>{children}</body>
    </html>
  );
}

Next time you deploy your website, the banner should appear when you visit it on a mobile device that doesn't have your app installed.

Deep links on Android

Implementing deep links on Android (without a custom URL scheme) is somewhat simpler than on iOS. You need to add intentFilters to the android section of your app config. The following basic configuration will cause your app to be presented in the standard Android dialog as an option for handling any record links to myapp.io:

{
  "expo": {
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            {
              "scheme": "https",
              "host": "*.myapp.io",
              "pathPrefix": "/records"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}

Android App Links

It may be desirable for links to your domain to always open your app (without presenting the user a dialog where they can choose the browser or a different handler). You can implement this with Android App Links, which use a similar verification process as Universal Links on iOS.

Create a JSON file for the website verification (also known as digital asset links file) at public/.well-known/assetlinks.json (or web/.well-known/assetlinks.json for legacy Expo webpack websites), and collect the following information:

• package_name: The Android application ID of your app (for example, com.bacon.app). This can be found in the app.json file under expo.android.package.
• sha256_cert_fingerprints: The SHA256 fingerprints of your app's signing certificate. This can be obtained in one of two ways:
  1. After building an Android app with EAS Build, run eas credentials -p android and select the profile you wish to obtain the fingerprint for. The fingerprint will be listed under SHA256 Fingerprint.
  2. By visiting the Play Console developer account under Release > Setup > App Signing. If you do, then you'll also find the correct Digital Asset Links JSON snippet for your app on the same page. The value will look like 14:6D:E9:83...

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "{package_name}",
      "sha256_cert_fingerprints": [
        // Supports multiple fingerprints for different apps and keys
        "{sha256_cert_fingerprints}"
      ]
    }
  }
]

Installing the native app on a device will trigger the Android app verification process, which can take up to 20 seconds. Once you have got your app opened, move to the Handling links into your app section for details on how to handle the inbound link and show the user the content they requested.

<activity android:name=".MainActivity" android:label="@string/app_name" android:configChanges="keyboard|keyboardHidden|orientation|screenSize|uiMode" android:launchMode="singleTask" android:windowSoftInputMode="adjustResize" android:theme="@style/Theme.App.SplashScreen" android:screenOrientation="portrait">
  <intent-filter>
    <action android:name="android.intent.action.MAIN"/>
    <category android:name="android.intent.category.LAUNCHER"/>
  </intent-filter>
  <intent-filter>
    <action android:name="android.intent.action.VIEW"/>
    <category android:name="android.intent.category.DEFAULT"/>
    <category android:name="android.intent.category.BROWSABLE"/>
    <data android:scheme="<slug>"/>
    <data android:scheme="<package>"/>
    <data android:scheme="exp+<slug>"/>
  </intent-filter>
  <intent-filter android:autoVerify="true" data-generated="true">
    <action android:name="android.intent.action.VIEW"/>
    <data android:scheme="https" android:host="<name>.onelink.me" android:pathPrefix="/XXXX"/>
    <data android:scheme="https" android:host="<name>.onelink.me" android:pathPrefix="/XXXX"/>
    <data android:scheme="https" android:host="<name>.onelink.me" android:pathPrefix="/XXXX"/>
    <data android:scheme="exp+<slug>"/>
    <category android:name="android.intent.category.BROWSABLE"/>
    <category android:name="android.intent.category.DEFAULT"/>
  </intent-filter>
</activity>

const { createRunOncePlugin, withAndroidManifest } = require('@expo/config-plugins');

/**
 * @typedef {import('@expo/config-plugins').ConfigPlugin} ConfigPlugin
 * @typedef {import('@expo/config-plugins').AndroidManifest} AndroidManifest
 */

/**
 * Remove the custom Expo dev client scheme from intent filters, which are set to `autoVerify=true`.
 * The custom scheme `<data android:scheme="exp+<slug>"/>` seems to block verification for these intent filters.
 * This plugin makes sure there is no scheme in the autoVerify intent filters, that starts with `exp+`.
 *
 * @type {ConfigPlugin}
 */
const withAndroidVerifiedLinksWorkaround = config =>
  withAndroidManifest(config, config => {
    config.modResults = removeExpoSchemaFromVerifiedIntentFilters(config.modResults);
    return config;
  });

/**
 * Iterate over all `autoVerify=true` intent filters, and pull out schemes starting with `exp+`.
 *
 * @param {AndroidManifest} androidManifest
 */
function removeExpoSchemaFromVerifiedIntentFilters(androidManifest) {
  for (const application of androidManifest.manifest.application || []) {
    for (const activity of application.activity || []) {
      if (activityHasSingleTaskLaunchMode(activity)) {
        for (const intentFilter of activity['intent-filter'] || []) {
          if (intentFilterHasAutoVerification(intentFilter) && intentFilter?.data) {
            intentFilter.data = intentFilterRemoveSchemeFromData(intentFilter, scheme =>
              scheme?.startsWith('exp+')
            );
          }
        }
        break;
      }
    }
  }

  return androidManifest;
}

/**
 * Determine if the activity should contain the intent filters to clean.
 *
 */
function activityHasSingleTaskLaunchMode(activity) {
  return activity?.$?.['android:launchMode'] === 'singleTask';
}

/**
 * Determine if the intent filter has `autoVerify=true`.
 */
function intentFilterHasAutoVerification(intentFilter) {
  return intentFilter?.$?.['android:autoVerify'] === 'true';
}

/**
 * Remove schemes from the intent filter that matches the function.
 */
function intentFilterRemoveSchemeFromData(intentFilter, schemeMatcher) {
  return intentFilter?.data?.filter(entry => !schemeMatcher(entry?.$['android:scheme'] || ''));
}

module.exports = createRunOncePlugin(
  withAndroidVerifiedLinksWorkaround,
  'withAndroidVerifiedLinksWorkaround',
  '1.0.0'
);

{
  "plugins": ["./plugins/withAndroidVerifiedLinksWorkaround"]
}

Debugging

Expo CLI enables you to test your universal links without deploying a website. Utilizing the --tunnel functionality, you can forward your dev server to a publicly available https URL.

1. Set the environment variable EXPO_TUNNEL_SUBDOMAIN=my-custom-domain where "my-custom-domain" is a unique string that you will use during development. This will ensure that your tunnel URL is consistent across dev server restarts.
2. Setup universal links as described above, but this time using an Ngrok URL: my-custom-domain.ngrok.io
3. Start your dev server with the --tunnel flag:

4. Compile the development build on your device:

Troubleshooting

• Read Apple's official documentation on debugging universal links.
• Ensure your apple app site association file is valid by using a validator tool.
• Ensure your website is served over HTTPS.
• The uncompressed apple-app-site-association file cannot be larger than 128kb.
• Verify Android app links
• Ensure both website verification files are served with content-type application/json.
• Android verification may take up to 20 seconds to take effect.
• If you update your web files, rebuild the native app to trigger a server update on the vendor side (Google, Apple).

When to not use deep links

This is the easiest way to set up deep links in your app because it requires a minimal amount of configuration.

The main problem is that if the user does not have your app installed and follows a link to your app with its custom scheme, their operating system will indicate that the page couldn't be opened but not give much more information. This is not a great experience. There is no way to work around this in the browser.

Additionally, many messaging apps do not autolink URLs with custom schemes. For example, exp://u.expo.dev/[project-id]?channel-name=[channel-name]&runtime-version=[runtime-version] might just show up as plain text in your browser rather than as a link (exp://u.expo.dev/[project-id]?channel-name=[channel-name]&runtime-version=[runtime-version]).

An example of this is Gmail which strips the href property from the links of most apps, a trick to use is to link to a regular HTTPS URL instead of your app's custom scheme, this will open the user's web browser. Browsers do not usually strip the href property so you can host a file online that redirects the user to your app's custom schemes.

Instead of linking to example://path/into/app, you could link to https://example.com/redirect-to-app.html and redirect-to-app.html would contain the following code:

<script>
  window.location.replace('example://path/into/app');
</script>