Linking into your app

Learn how to handle an incoming URL in your app by creating a deep link.

This guide provides steps to configure standard deep links in your project by adding a custom scheme.

Add a custom scheme in app config

To provide a link to your app, add a custom string to the scheme property in the app config:

{
  "expo": {
    "scheme": "myapp"
  }
}

After adding a custom scheme to your app, you need to create a new development build. Once the app is installed on a device, you can open links within your app using myapp://.

If the custom scheme is not defined, the app will use android.package and ios.bundleIdentifier as the default schemes in both development and production builds. This is because Expo Prebuild automatically adds these properties as custom schemes for Android and iOS.

Test the deep link

You can test a link that opens your app using npx uri-scheme, which is a command-line utility for interacting and testing URI schemes.

For example, if your app has a /details screen that you want to open when a user taps on a link (either through another app or a web browser), you can test this behavior by running the following command:

Running the above command:

• Opens your app's /details screen
• The android or ios options specify that the link should be opened on Android or iOS
• Alternatively, you can open the link by searching for it in the device's native browser. For example, open Safari on iOS and type myapp:// in the address bar to prompt the device to open your app.

Handle URLs

If you are using Expo Router, you can ignore this section.

You can observe links that launch your app using the Linking.useURL() hook from expo-linking.

import * as Linking from 'expo-linking';

export default function Home() {
  const url = Linking.useURL();

  return <Text>URL: {url}</Text>;
}

The Linking.useURL() hook works behind the scenes by following these imperative methods:

• The link that launched the app is initially returned using Linking.getInitialURL()
• Any new links triggered while the app is already open are observed with Linking.addEventListener('url', callback)

Parse URLs

You can use the Linking.parse() method to parse the path, hostname, and query parameters from a URL. This method extracts deep linking information and considers nonstandard implementations.

import * as Linking from 'expo-linking';

export default function Home() {
  const url = Linking.useURL();

  if (url) {
    const { hostname, path, queryParams } = Linking.parse(url);

    console.log(
      `Linked to app with hostname: ${hostname}, path: ${path} and data: ${JSON.stringify(
        queryParams
      )}`
    );
  }

  return (
    %%placeholder-start%%Your React component here. %%placeholder-end%%
  )
}

Limitations

If a user does not have your app installed, deep links to your app will not work. Attribution services like Branch offer solutions for conditionally linking to your app or web page.

Universal links is another solution you can use to handle such cases, in which the route to your web page determines whether or not the app is installed. For more details, see Universal Links.