After following Expo's guide on how to use Universal Links found here:
and Configuring Deep Linking for React Navigation with the following guides:
I had deep links working but did not have Universal Links working. I could link into my application with some arbitrary scheme such as:
1
pokemon://pokemon/1
Which I had defined to point to my application by setting it in the app.json file in my expo project. (Read more about URL schemes here: https://docs.expo.dev/versions/latest/config/app/#scheme).
If I would use a URL like: https://pokemon-web-chi.vercel.app/pokemon/1 . Even though I followed the Expo guide very closely on how to configure my website and application to be associated. In terms, of the desired behavior: This link would not open in my application as I would like. However, it would launch inside my web browser; which it should not be doing.
After much trial and error I found the solution to be - Expo in their guide suggest you to add a list of associated domains leading with "applinks" so apple knows they are universal links inside the ios object of your app.json like the following:
1
2
3
4
5
6
7
8
"ios": {
//....
"bundleIdentifier": "com.cjoshmartin.pokemon",
"associatedDomains": [
"applinks:pokemon-web-chi.vercel.app"
],
//...
}
However not listed in the expo guides but a requirement to make this work, you also need to add an entitlement for associated domains that you want to use, which should look like the following:
1
2
3
4
5
6
7
8
9
10
11
12
13
"ios": {
//....
"bundleIdentifier": "com.cjoshmartin.pokemon",
"associatedDomains": [
"applinks:pokemon-web-chi.vercel.app"
],
"entitlements": {
"com.apple.developer.associated-domains": [
"applinks:pokemon-web-chi.vercel.app"
]
},
//...
}
As a note, for the client I am doing this work for they have multiple environments for their deployments and I have tried prefixing a wildcard (*) selector for their multiple subdomains like "dev", "staging", or "web". For me that doesn't seem to get picked up and it is better just to list out all the subdomains in the entitlements array and the associatedDomains array.
After adding the entitlements for associated domains it seemed to work fine for me! I was able to click on a URL and it would jump into my test application with no issue.
Which is great! And if you were stuck like I was probably all you need for now and you can find the code at the bottom of this post... if you are still confused and want to get a little deeper please keep reading this article.
In the rest of this blog post we will dig a little deeper into what Deep links are and the full process to setup for you to use them in your next react native application.
Starting off the baseline for linking into your app are deep links. As defined by wikipedia, Deep links are links to a specific location within in a mobile application usually defined by a unique uniform resource identifier (URI) created by the application itself. Such as these ones:
- fb:// is the iOS URI to launch Facebook's mobile app
- YouTube:// is the iOS URI to launch YouTube's mobile app
You can link into a specific page inside the mobile application or pass data as you open the app like the following:
1
fb://profile/33138223345
This will open the Facebook app to a profile that has the ID of "33138223345".
The downside of this self defined URI structure is that it doesn't go with the standard URL HTTP structure we are use to using because of the web making these deep links less flexible then normal URLs.
To give us the flexibility we are use to with URLs, this is where Universal Links come into play for the IOS platform. Universal Links are a protocol that build on top of the URIs of Deep Linkings but allow app developers of IOS apps to use the "HTTPS" Protocol that they are already using for their web application to link into their IOS app using the same path scheme. For example this deep linking URI:
1
fb://profile/33138223345
Would look like the following (as a Universal Link):
1
https://facebook.com/profile/33138223345
This is done by creating a two way association between your website and your IOS application.
Lets dive a little deeper into creating this two way association with the following steps:
- In the deep linking guide provided by React Navigation, the first step is to define the deep linking URI in your "app.json" file like the following:
1
2
3
4
5
6
7
{
"expo": {
// ...
"scheme": "pokemon",
// ...
}
}
1
npx expo install expo-linking
2. In the App.tsx we need to update our linking object to have the permutations of our deep link URI and our web URL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
const prefix = Linking.createURL('/');
export function App() {
const colorScheme = useColorScheme();
const theme = colorScheme === 'dark' ? DarkTheme : DefaultTheme
return (
<Navigation
theme={theme}
linking={{
enabled: 'auto',
prefixes: [
// Change the scheme to match your app's scheme defined in app.json
prefix,
'pokemon://',
'http://pokemon-web-chi.vercel.app',
'https://pokemon-web-chi.vercel.app',
'https://pokemon-web-chi.vercel.app/pokemon/*',
'http://pokemon-web-chi.vercel.app/pokemon/*',
],
}}
onReady={() => {
SplashScreen.hideAsync();
}}
/>
);
}
Here I try to add all the forms of the URLs I am wanting to pick up. I am not sure if that is necessary and maybe there is some trial and error to be done here but when I don't add all the links and paths it does not seem to work for me.
you can view the full file here: https://github.com/cjoshmartin/pokemon-mobile/blob/main/src/App.tsx
At this point we can link into our application using the deep link URI of "pokemon://", for example we can link into the first Pokemon with the follow URI scheme:
1
pokemon://pokemon/1
3. Set your bundle Identifier in your "app.json" and publish to Apple Connect
1
2
3
4
5
6
7
{
"expo": {
"ios": {
"bundleIdentifier": "com.cjoshmartin.pokemon"
}
}
}
1
npx setup-safari
The example of the "apple-app-site-association" that it will give you will look like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
"applinks": {
"details": [
{
"appIDs": [
"HJXLN2SCZS.com.cjoshmartin.pokemon"
],
"components": [
{
"/": "*",
"comment": "Matches all routes"
}
]
}
]
},
"activitycontinuation": {
"apps": [
"HJXLN2SCZS.com.cjoshmartin.pokemon"
]
},
"webcredentials": {
"apps": [
"HJXLN2SCZS.com.cjoshmartin.pokemon"
]
}
}
One change I made was to change the components object to a paths object which just shows an array of URL paths you want your app to handle:
1
2
3
4
5
6
7
8
9
10
{
"applinks": {
"details": [
{
"appID": "HJXLN2SCZS.com.cjoshmartin.pokemon",
"path": ["/pokemon/*"]
}
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
{
"expo": {
"ios": {
"associatedDomains": ["applinks:pokemon-web-chi.vercel.app"],
"entitlements": {
"com.apple.developer.associated-domains": [
"applinks:pokemon-web-chi.vercel.app"
]
}
}
}
}
Make sure to list out all permutations of your domains in these arrays such as dev, prod, stage or other subdomains that you want to open links in your application.
After this we just need to build the application and submit it, to register it with the associated domains. Using the following command can do that for us:
1
eas build --platform=ios --profile=production --non-interactive && eas submit -p ios --latest
We can download the latest build via testflight and test it out:
And Boom! It works great!
you can find the code here:
