Setting up iOS Universal Links

setting_up_ios_universal_links.md

Setting up iOS Universal Links

Table of Contents

• Resources
  • Resources General link resources
  • Validation tools
• Server configuration
  • Apple JSON Metadata file
    • Create a JSON file called apple-app-association
    • Sign the apple-app-site-association file using openssl
    • Upload the signed apple-app-site-association 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

• https://developer.apple.com/library/prerelease/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html
• https://developer.apple.com/videos/play/wwdc2015-509/
• https://medium.com/@barsh/my-first-date-with-ios-universal-links-90dfabc88bb8

Validation tools

• https://search.developer.apple.com/appsearch-validation-tool/
• https://limitless-sierra-4673.herokuapp.com/

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:

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

scp /path/to/apple-app-site-association username@example.com:~/

2. Login to the web server:

ssh username@example.com

3. 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

1. 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
}

xcode_client_setup1.jpg

xcode_client_setup2.jpg