xref: /expo/docs/pages/guides/deep-linking.mdx (revision a16ac082)

---
title: Deep linking
description: Learn how to use app/universal links to open your app from a standard web URL.
---

import { ConfigReactNative } from '~/components/plugins/ConfigSection';
import { Collapsible } from '~/ui/components/Collapsible';
import { Step } from '~/ui/components/Step';
import { CODE } from '~/ui/components/Text';
import { Terminal } from '~/ui/components/Snippet';

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`](https://github.com/expo/config-plugins/tree/main/packages/react-native-branch).

Before you can use an app/universal links, you've 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've 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](/routing/introduction/).

> Universal links cannot be tested in the Expo Go app. You need to create a [development build](/develop/development-builds/introduction).

## 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`](/versions/latest/config/app/#associateddomains) to your [app config](/workflow/configuration/), and make sure to follow [Apple's specified format](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_associated-domains). 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:

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

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

<ConfigReactNative title="Manual native configuration">

Apps that don't use [Continuous Native Generation](/workflow/continuous-native-generation) (`npx expo prebuild`) must [manually configure](/build-reference/ios-capabilities#manual-setup) the **Associated Domains** capability for their bundle identifier.

If you enable through the [Apple Developer Console](/build-reference/ios-capabilities#apple-developer-console), then be sure to add the following entitlements in your `ios/[app]/[app].entitlements` file:

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

</ConfigReactNative>

### AASA configuration

On the web-side, you've 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](/routing/introduction/) 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**.

```json public/.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": ["*"]
      }
    ]
  },
  // 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've setup the AASA file, deploy your website to a server that supports HTTPS (most modern web hosts).

See [Apple's documentation](https://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html) for further details on the format of the AASA. Branch provides an [AASA validator](https://branch.io/resources/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](https://developer.apple.com/documentation/xcode/supporting-associated-domains) 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

<Collapsible summary="Here's an example AASA JSON from Apple's documentation">

```json
{
  "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"
          }
        ]
      }
    ]
  }
}
```

</Collapsible>

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](https://developer.apple.com/account/resources/identifiers/list). Once you've got your app opened, move to the [Handling links into your app](/guides/linking/#handling-links) 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](https://developer.apple.com/documentation/webkit/promoting_apps_with_smart_app_banners) 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:

```html
<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:

<Terminal cmd={['$ npx setup-safari']} />

If you're building a [statically rendered website with Expo Router](/router/reference/static-rendering), then add this HTML tag to the `<head>` component in your [**app/+html.js** file](/router/reference/static-rendering#root-html).

```jsx app/+html.js
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`](/versions/latest/config/app/#android) section of your [app config](/workflow/configuration/). 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`:

```json app.json
{
  "expo": {
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          /* @info Add the autoVerify property to the intent filter in app config to enable app links.*/
          "autoVerify": true,
          /* @end */
          "data": [
            {
              "scheme": "https",
              "host": "*.myapp.io",
              "pathPrefix": "/records"
            }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}
```

### Android Asset 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 (a.k.a. [digital asset links](https://developers.google.com/digital-asset-links/v1/getting-started) 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](/versions/latest/config/app/#package) 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](https://play.google.com/console/) developer account under **Release > Setup > App Integrity > 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...`

```json public/.well-known/assetlinks.json
[
  {
    "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](https://developer.android.com/training/app-links/verify-android-applinks#web-assoc) process, which can take up to 20 seconds.

<ConfigReactNative title="Manual native configuration">

If you're not using EAS to manage code signing, you can find the **sha256_cert_fingerprints** by building and submitting your app manually, then visiting the [Google Play Console](https://play.google.com/console/) developer account under **Release > Setup > App Integrity > 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...`. Copy this value into your `public/.well-known/assetlinks.json` file.

</ConfigReactNative>

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.

<Collapsible summary={<>Handle App Links on Android for <CODE>expo-dev-client</CODE> version 1.2.1 and below</>}>

From Android 12 onwards, there is an issue reported when verifying the App Links with [`expo-dev-client`](/develop/development-builds/introduction/#what-is-an-expo-dev-client) version 1.2.1 and below.

In app config, when `expo.android.intentFilters` is used and `"autoVerify"` is set to `true`, the `expo-dev-client` adds a scheme `<data android:scheme="exp+<slug>" />` to the intent filter. This scheme breaks the App Links verification.

An example of the `exp+` scheme breaking the verification process:

```xml AndroidManifest.xml
<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"/>
    <!-- @info -->
    <data android:scheme="exp+<slug>"/>
    <!-- @end -->
    <category android:name="android.intent.category.BROWSABLE"/>
    <category android:name="android.intent.category.DEFAULT"/>
  </intent-filter>
</activity>
```

You can fix this issue by creating a custom [Config Plugin](/config-plugins/introduction/) that removes the `exp+` schemes when verifying `intentFilters`. In your project, create a new file called **withAndroidVerifiedLinksWorkaround.js** with the following code snippet:

```js withAndroidVerifiedLinksWorkaround.js
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'
);
```

Next, in your **app.json**, add the path to the plugin under `expo.plugins`:

```json app.json
{
  "plugins": ["./plugins/withAndroidVerifiedLinksWorkaround"]
}
```

If you are using [EAS Build](/build/introduction/), you will have to create a new build after adding these changes to your project so that they are reflected in your Android app.

</Collapsible>

## Debugging

Expo CLI enables you to test your universal links without deploying a website. Utilizing the [`--tunnel` functionality](/more/expo-cli/#tunneling), 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:

<Terminal cmd={['$ npx expo start --tunnel --dev-client']} />

4. Compile the development build on your device:

<Terminal
  cmd={[
    '# Build your native Android project',
    '$ npx expo run:android',
    '',
    '# Build your native iOS project',
    '$ npx expo run:ios',
  ]}
/>

## Troubleshooting

- Ensure your apple app site association file is valid by using a [validator tool](https://branch.io/resources/aasa-validator/).
- Ensure your website is served over HTTPS.
- The uncompressed `apple-app-site-association` file cannot be [larger than 128kb](https://developer.apple.com/library/archive/documentation/General/Conceptual/AppSearch/UniversalLinks.html).
- [Verify Android app links](https://developer.android.com/training/app-links/verify-android-applinks)
- 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:

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