React Native - Universal link (iOS) (Dec 2024)

react_native_universal_link.md

Universal link - iOS [Dec 2024]

Right now (17/12/2024) the documentation about how to implement UL is really outdated. There isn't a full source of true. Let put all together here.

1. Select the domain/subdomain to use

Is the simpler step, but is important to understand a few things.

• You need to control domain's dns.
• the root domain is always "your-domain.com" (without www or protocol)
• The domain "www.your-domain.com" is considered like a subdomain. the subdomain is www and the domain the rest.
• Also subdomains like, "app.your-domain.com" is considered a sub domain (of course).
• If you want to use a subdomain, all the configurations must to be around the subdomain.

DEV NOTE: For this document, we will play for a subdomain app.your-domain.com

2. Create the apple-app-site-association file

When you already have your domain/subdomain selected, you need a web server running over the subdomain to serve a file required by apple.

• Create a file without extension called "apple-app-site-association" (Don't forget, without extension)
• The content of the file can be different depend of the goal, but for now I'm assuming we only want to enable UL. So, let's use this basic but valid template

{
  "applinks": {
    "apps": ["<TeamID>.<BundleId>"],
    "details": [
      {
        "appID": "<TeamID>.<BundleId>",
        "paths": ["*"]
      }
    ]
  }
}

• Now we need to replace "TeamID" and "BundleId". You can find this information in Apple developer site in different ways. Here I describe one option for each id.
• Finding TeamID: go to https://developer.apple.com/account, Scroll down until "Detalles de la membresía | Membership details" and you will see "Team ID"

• Finding BundleId: go to https://developer.apple.com/account/resources/identifiers, click in the name of your app and you will see the "Bundle id", in my case is something like "com.appname.mobile"

• After replace the ids, you need to serve this file from your web server. That means, over this url, app.your-domain.com/.well-known/apple-app-site-association the file must download. Have in mind that the server response must be a file attachment, not json or something similar. Also, the server response must to be without redirect.

• With the file already placed in you server. you can check the good response running this bash command

curl -v https://app.your-domain.com/.well-known/apple-app-site-association

# the response should include something similar
content-disposition: attachment; filename="apple-app-site-association"; filename*=UTF-8''apple-app-site-association

3. Enable Associated domain for your app

Go back to this page, and select your app again. Scroll down and there you will see a list of capabilities. Find "Associated Domains" and turning on.

4. Link your subdomain with your app

Using xcode we need to add a new capability to our app called "Associated domains". This guide show how to do it. Also, have this exclusive dor "Associated domains".

Follow the steps, find the capability "Associated domains", add it into your project and then, type your subdomain in this format applinks:YOUR_DOMAIN.

In our case is something like this applinks:app.your-domain.com

5. Enable you app to use the associated domain

At this point the environment is well configured, but your app doesn't know how to deal with the link. You need to update the AppDelegator (c++ code) to be able to receive and process the links.

Find you AppDelegator.mm (not .m, with double m) and add this code

#import "RCTLinkingManager.h"

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
  return [RCTLinkingManager application:application openURL:url
                      sourceApplication:sourceApplication annotation:annotation];
}

// Only if your app is using [Universal Links](https://developer.apple.com/library/prerelease/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html).
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
 restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler
{
 return [RCTLinkingManager application:application
                  continueUserActivity:userActivity
                    restorationHandler:restorationHandler];
}

Make sure you are not adding duplicated piece of code.

6. Add Linking library.

The first line of the previous snippet is #import "RCTLinkingManager.h". This is a native library that the snipped uses. We need to include it manually in the build process. If not, your app will crash because you are trying to use RCTLinkingManager but is not available in the system (app).

The library that we need is is called LinkingIOS. We can find in this directory you_app/node_modules/react-native/Libraries/LinkingIOS

To add this follow this steps:

• Come back to xcode
• Select you project and go to Build Settings
• In the search bar (top-right of the panel - not of the window) type Search Paths
• Inside this section, you will find a sub section called Header Search Paths. In this place you need to add the path of the library that we need, in this case LinkingIOS. You will have a list of paths for each type of builds (Debug and Release). Let's add the library to both.
• Double click in the debug list. At the end of the list in the new window add the library path in this format (including the double quotes): "$(PODS_ROOT)/../../node_modules/react-native/Libraries/LinkingIOS"
• Repeat this step for Release paths.

7. Receive the links in your code base.

Now the app build works and the app is ready to receive links. Now is time to add some code to handle those links (easy step).

import { Linking } from 'react-native';

export default function app(){
  useEffect(() => {
    (async () => {
      // Get app initial URL (when the app was closed)
      const initialUrl = await Linking.getInitialURL();
      console.info(initialUrl);
    })();

    // Listen to incoming URL (When the app is already open)
    Linking.addEventListener('url', ({ url }) => {
      console.info(url);
    });

    return () => Linking.removeAllListeners('url');
  }, []);

  return ()
}

Testing it

For this final step, start your app (in the simulator works). Make sure your hook (previous one) is running and reachable, then run this command:

npx uri-scheme open "https://app.your-domain.com/path?param=1" --ios

Running this command, your app should receive the link (finger cross).