Hello Dev π trust you're hacking good. Let's talk about setting up deep linking for react native projects. Grab your laptop and let's grab some knowledge .
So what is deep linking?
Deep linking is a way to move directly to a particular screen in a particular mobile app through URLs.
You know the way you click a link for e.g dev.to/stanleyugwu and it takes you to a particular page within a website, with mobile deep linking, you'll be able to achieve the same result for mobile apps. In short you'll be able to navigate to a particular screen/view of a mobile app by clicking a link.
Without deep linking
The traditional way of getting to where you want in any mobile app without deep linking is to launch the app, and then follow whichever route the app puts you through, till you get to where you want.
Consider below diagram as the UI flow of an example mobile app. Each box represents a screen within the app.
Say you want to edit your profile from the Profile screen, you have to move from Home to Settings then to Profile screen.
With deep linking
With deep linking setup for our example app, we'll be able to move directly to the Profile screen without going through the intermediate screens (Home, Settings).
A common use-case scenario of deep linking is when slack sends you an email with a magic link which you click on and it takes you to slack app if you have it installed. That's deep linking at work there π
Benefits of deep links
There are numerous advantages of setting up deep links for your mobile app:
- Improves app discoverability
- Improves user engagement
- Enhances the user experience
- Re-Engages users to your app fast
- Campaign opportunity (campaign can be run for individual screen)
- e.t.c
Configuring deep links
Deep links are regular links, it's just the underlying operating system and the mobile app been deep-linked into that makes them powerful.
Configuring your mobile app to support deep linking is just about informing the operating system that the app can handle certain URLs and/or URL schemes. So that when the user clicks on a URL matching the specifications, your app can take over, and handle the user's request.
A typical URL has different parts or segments as denoted by the image below:
You can configure your app to handle each segment or combination of segments. What that means is you can configure your app to handle URLs with certain scheme, second-level domain, top-level domain, subdirectory, or a combination of them.
In this tutorial, we will be setting up our React Native app to handle the scheme myapp://
so that URLs having myapp://
scheme would be handled by our app.
I think I've said enough π€, let's get to work π».
1. Create a new React Native app (let's call it deepLinkApp π)
npx react-native init deepLinkApp
Move into the app's directory
cd ./deepLinkApp
Click here to learn how to setup your environment for React Native.
2. Configure deep links for android
On Android, deep links works through intents. The Android OS broadcasts an intent when a link is clicked, and apps that can handle the intent and link shows up for user to choose. Now let's tell Android that our app can handle myapp://
scheme.
The easiest way to do this is with the uri-scheme
package:
npx uri-scheme add myapp --android
If you want to set it up manually, open up deepLinkApp/android/app/src/main/AndroidManifest.xml
, and make the following adjustments:
Set
launchMode
ofMainActivity
tosingleTask
in order to receive intent on existingMainActivity
.Create a new
intent-filter
inside theMainActivity
entry with aVIEW
type action
Below is how your .MainActivity
activity tag should look like with the intent-filter
and launchMode
set, so you can just copy and paste it:
...
<activity
android:name=".MainActivity"
android:launchMode="singleTask">
<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="myapp" />
</intent-filter>
</activity>
...
3. Configure deep links for iOS
Include the following lines in your project's AppDelegate.m
file in order to be able to listen to incoming app links:
Copy/paste below code at the top of the file
#import <React/RCTLinkingManager.h>
Copy/paste below code inside @implementation AppDelegate
above @end
:
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
return [RCTLinkingManager application:application openURL:url options:options];
}
Now let's add the scheme to our iOS project configuration.
The easiest way to do this is again with the uri-scheme
package. Run the following command:
npx uri-scheme add myapp --ios
Again, if you want to do it manually, open up the project deepLinkApp/ios/deepLinkApp.xcworkspace
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 myapp
.
This is how it should look in Xcode:
Imge Source: react-navigation
4. Rebuild and install the app
We have made changes on the native side of our app, so you need to rebuild and install the app in your emulator, simulator, or device.
For iOS, run:
npx react-native run-ios
For Android, run:
npx react-native run-android
5. Test out the deep link (the moment of truth π)
Now we're going to use our handy uri-scheme
command line package to test out the deep link we just set up for both Android and iOS.
For iOS run:
npx uri-scheme open "myapp://any/host/and/path" --ios
For Android run:
npx uri-scheme open "myapp://any/host/and/path" --android
Running above command will launch/start-up our app on the emulator/simulator/device if it's not already running, otherwise nothing really happens. Yes nothing π.
The reason is because we didn't specify what happens next after our app is granted permission to handle the deep link.
6. Handle the deep link
We need to handle the deep link on the Javascript side of our app so that we can specify what happens next after our app is launched or foregrounded as a result of running above command, or user clicking on URL with myapp://
scheme. Fortunately, React Native provides us with a Linking
module which we can call from JavaScript to handle deep linking easily ππ.
There are two ways to handle deep links that open your app:
If the app is already open/launched, the app is foregrounded and a Linking 'url' event is fired
You can handle these events withLinking.addEventListener('url', callback)
- it callscallback({ url })
with the URL which was used to open the app.If the app is not already open/launched, it is opened and the url which was used to open the app is passed in as the
initialURL
You can handle these events withLinking.getInitialURL()
- it returns a Promise that resolves to the URL, if there is one.
To handle these cases in our app, open up App.js
and add the following code to it:
useEffect(() => {
// handles deep link when app is already open
Linking.addEventListener('url', evt => {
console.log(evt.url);
});
// handles deep link when app is not already open
Linking.getInitialURL()
.then(url => console.log('Initial URL:', url))
.catch(console.warn);
return () => {
// clears listener when component unmounts
Linking.removeAllListeners('url');
};
}, []);
Now lets' run the uri-scheme
test command one more time:
For iOS run:
npx uri-scheme open "myapp://any/host/and/path" --ios
For Android run:
npx uri-scheme open "myapp://any/host/and/path" --android
Now you should see your app opened, and "myapp://any/host/and/path" logged to the console. Bravo!! ππΊ your deep link setup is working.
Note that we're just logging the URL (which opened our app) to the console, in real apps however, you might need to parse the URL and perform further operations such as navigating the user to the appropriate screen. Luckily if you use react-navigation
package for your app navigation, there's an easy way to bind certain deep link URLs to certain screens in your app. You can read more on that here.
Summary
We've just learnt how to setup deep links for our React Native (Android and iOS) app. If you've not been doing this for your apps, you really need to consider it as it comes with so many benefits.
The technicalities involved in setting up deep links are not really that much, the lengthiness of this article can be attributed to the stretch in explanations (I was more concerned with how it worked, sorry π).
Phew! π that was a long one π . I hope you learnt something?. happy hacking π» βπ
Top comments (2)
Great one Stanley π
Thanks!