ivmos/setting_up_ios_universal_links.md

Setting up iOS Universal Links

Resources
- Resources General link resources
- Validation tools
Server configuration
- Apple JSON Metadata file
- Modifying the Content-type of the apple-app-site-association file
  - Apache configuration
  - nginx configuraiton
Client configuration
- Associated domains
- Implement the corresponding AppDelegate methods
  - iOS 9.0 and earlier
  - iOS 9.1 and later

Resources

Here are some good URLs that might be of assistance:

Resources General link resources

Validation tools

Server configuration

Follow these steps to setup Universal app linking on the web server. In this example we use Apache2 as our web server but the same rules apply for nginx or IIS.

Apple JSON Metadata file

Create a JSON file called "apple-app-association":

Below you'll find a template with a few examples:

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "<TEAM_DEVELOPER_ID>.<BUNDLE_IDENTIFIER>",
                "paths": [ "*" ]
            },
            {
                "appID": "<TEAM_DEVELOPER_ID>.<BUNDLE_IDENTIFIER>",
                "paths": [ "/articles/*" ]
            },
            {
                "appID": "<TEAM_DEVELOPER_ID>.<ANOTHER_APP_BUNDLE_IDENTIFIER>",
                "paths": ["/blog/*","/articles/*"]
            }
        ]
    }
}

PLEASE NOTE!

The "apps": JSON key must be left as an empty array.
The SSL generated apple-app-site-association JSON file must not have a .json file extension.

Sign the apple-app-site-association file using openssl: (not needed in last iOS versions)

openssl smime -sign -nodetach 
-in "unsigned.json"
-out "apple-app-site-association" -outform DER 
-inkey /path/to/server.key 
-signer /path/to/server.crt

Upload the signed "apple-app-association" file:

Upload the signed apple-app-site-association file to the server:

scp /path/to/apple-app-site-association [email protected]:~/

Login to the web server:

ssh [email protected]

Move the file to the root of the webserver (This might be another directory on your server)

mv apple-app-site-association /var/www/

Modifying the Content-type of the apple-app-site-association file

The apple-app-association-file needs to be returned with the following Content-Type:

Content-type: "application/pkcs7-mime".

(Update: application/json is fine since some time)

Below you'll find instructions on how to do this for your web server.

Apache configuration

Modify the /etc/apache2/sites-available/default-ssl (or equivalent) file to include the <Files> snippet:

<Directory /path/to/root/directory/>
...
<Files apple-app-site-association>
Header set Content-type "application/pkcs7-mime"
</Files>
</Directory>

nginx configuraiton

Modify the /etc/nginx/sites-available/ssl.example.com (or equivalent) file to include the location /apple-app-assocation snippet:

server {
   ...
   location /apple-app-site-association {
      default_type application/pkcs7-mime;
   }
}

Client configuration

Associated domains

In Xcode go to <MyApp>.xcodeproj/<Build target>/Capabilities and turn on Associated domains.

2. Enter the domains you want the iOS app to respond to.

This will generate a <AppName>.entitlements file that needs to be included in the project.
Please note that you need to enter subdomains specifically.

Implement the corresponding `AppDelegate` methods

iOS 9.0 and earlier

If you already have a custom URI scheme i.e myAppScheme://, this method will already be implemented.
We have noticed that devices running iOS 9.0.x responds to this older method of handling app links.
If you want to support iOS 9.0.x or earlier like iOS8/iOS7 you will need to implement this method and add a JavaScript iframe redirect to your website.

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation;

iOS 9.1 and later

Devices running iOS 9.1 or later supports Apple's Universal Links and to handle the incoming URL you need to implement the following method.

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray *))restorationHandler {
    NSURL *url = userActivity.webpageURL;
    // handle url
}