In this guide, we will configure our app to handle deep links on various platforms. To handle incoming links, we need to handle 2 scenarios:
- If the app wasn't previously open, we need to set the initial state based on the link
- If the app was already open, we need to update the state to reflect the incoming link
React Native provides a
Linking to get notified of incoming links. React Navigation can integrate with the
Linking module to automatically handle deep links. See configuring links to see more details on how to configure links in React Navigation.
Below, we'll go through required configurations for each platform so that the deep link integration works.
Set up with Expo projects
First, you will want to specify a URL scheme for your app. This corresponds to the string before
:// in a URL, so if your scheme is
mychat then a link to your app would be
mychat://. The scheme only applies to standalone apps and you need to re-build the standalone app for the change to take effect. In the Expo client app you can deep link using
ADDRESS is often
PORT is often
19000 - the URL is printed when you run
expo start. If you want to test with your custom scheme you will need to run
expo build:ios -t simulator or
expo build:android and install the resulting binaries in your emulators. You can register for a scheme in your
app.json by adding a string under the scheme key:
Next, let's configure our navigation container to extract the path from the app's incoming URI.
The reason that is necessary to use
Linking.makeUrl is that the scheme will differ depending on whether you're in the client app or in a standalone app.
If you are using universal links, you need to add your domain to the prefixes.
Note: If you are using Expo SDK version 37 or lower, you need to add your domain with both the
exps scheme, to work around this bug in Expo.
To match all subdomains of an associated domain, you can specify a wildcard by prefixing
*. before the beginning of a specific domain. Note that an entry for
*.example.com does not match
example.com because of the period after the asterisk. To enable matching for both
example.com, you need to provide a separate prefix entry for each.
Test deep linking on iOS
To test the URI on the simulator in the Expo client app, run the following:
Test deep linking on Android
To test the intent handling in the Expo client app on Android, run the following:
host.exp.exponent to your app package name if you are testing on a standalone app.
Read the Expo linking guide for more information about how to configure linking in projects built with Expo.
Set up with bare React Native projects
Let's configure the native iOS app to open based on the
mychat:// URI scheme.
You'll need to link
RCTLinking to your project by following the steps described here. To be able to listen to incoming app links, you'll need to add the following lines to
If you're targeting iOS 9.x or newer:
If you're targeting iOS 8.x or older, you can use the following code instead:
If your app is using Universal Links, you'll need to add the following code as well:
Now you need to add the scheme to your project configuration.
The easiest way to do this is with the
npx uri-scheme add mychat --ios.
If you want to do it manually, open the project at
SimpleApp/ios/SimpleApp.xcodeproj in Xcode. Select the project in sidebar and navigate to the info tab. Scroll down to "URL Types" and add one. In the new URL type, set the identifier and the URL scheme to your desired URL scheme.
Now you can press play in Xcode, or re-build on the command line:
To test the URI on the simulator, run the following:
To test the URI on a real device, open Safari and type
To configure the external linking in Android, you can create a new intent in the manifest.
The easiest way to do this is with the
npx uri-scheme add mychat --android.
If you want to add it manually, open up
SimpleApp/android/app/src/main/AndroidManifest.xml, and make the following adjustments:
singleTaskin order to receive intent on existing
MainActivity(this is the default on all new projects, so you may not need to actually change anything!). It is useful if you want to perform navigation using deep link you have been registered - details
- Add the new
MainActivityentry with a
Now, re-install the app:
To test the intent handling in Android, run the following:
Hybrid React Native and native iOS Applications (skip for React-Native-only projects)
If you're using React Navigation within a hybrid app - an iOS app that has both Swift/ObjC and React Native parts - you may be missing the
RCTLinkingIOS subspec in your Podfile, which is installed by default in new RN projects. To add this, ensure your Podfile looks like the following:
Linking isn't the only way to handle deep linking. You might also want to integrate other services such as Branch which provide their own API for getting notified of incoming links, or you also might want to handle links from push notifications using Firebase etc.
Similar to the above example, you can integrate any API that provides a way to get the initial URL and to subscribe to new incoming URLs using the