Universal Links and Your iOS App

Sailthru supports the validation requirements of Apple’s Universal Links functionality for our customers who use white-labeled link domains in Sailthru templates (for example, link.yourdomain.com).

About Universal Links

This functionality facilitates a streamlined end-user experience within iOS, allowing users to click a link in an email or SMS and have it directly open to a registered native app. Previously, users were sent to the App Store or to a Safari redirect that ultimately opened the app, depending on the link type used. The benefit of the new functionality is that a standard “http://” link can open straight to a registered app, as opposed to embedding deep-link protocol links in emails which desktop and Android users may not be able to use.

Note that while Universal Links opened in iOS apps such as Mail and Messages will open the intended app directly, third-party messaging apps may not yet support Universal Links and may continue directing users to a web browser. Please also note that all links rewritten in your message will open inside your app, including social share and external-site links. We do not currently offer a workaround to this. 

You must provide Sailthru three (3) files to successfully enable Universal Links using your Sailthru Link Domain:

  1. An Apple App Site Association file
  2. An https certificate for your link domain (this cannot be a wildcard certificate)
  3. An https key to match the certificate

If you’re ready to go, you can upload these files through the Universal Links settings page in my.sailthru.com. If you’re looking for details on these files, please continue reading.

Authentication

In order to protect rogue links from hijacking your app, Apple has developed an authentication and validation process. You can read more about the process and the full specification for this file here.

In short, in order to enable app links from your link domain, a small JSON file called the Apple App Site Association (AASA) file must be accessible on that domain. This file provides the permissions to iOS to have links directly open in apps. For your domain, your AASA file can optionally provide permissions for multiple apps. This includes development and staging versions of your app, if they have their own app IDs. For example:

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID":"65142EJ7UT.com.example.site",
                "paths": [ "/*" ]
            },
            {
                "appID":"4M1LSA993E.com.example.Staging",
                "paths": [ "/*" ]
            },
            {
                "appID": "4M1LSA993E.com.example.Development",
                "paths": [ "/*" ]
            },
        ]
    }
}

Sailthru can host this file for you at your established link domain. Apple requires the AASA file be accessible via https, which means you must provide an https certificate to Sailthru for your link domain. This file cannot be a wildcard certificate and must match your link domain.

You may upload as many cert/key pairs and AASA files as you have established link domains in the Sailthru link settings page. Once a link domain is saved in the “Link Domain” settings page, it will be made available in the Universal Links setting page and API.

Link Parsing and Tracking

By design, when Universal Links to your domain are clicked within supported apps (for example, iOS Mail), and your app is installed on the device, these links bypass the browser and hand the clicked URL directly to the app. You must take additional development actions to enable your app to directly request this URL when it is received. This request will ensure proper click attribution in your Sailthru stats while also redirecting to the intended destination URL on your site. The redirected URL can then return data that your app may require to identify the user and their intended destination.

HTTPS Certificate Details

Please adhere to these guidelines when providing your certificate:

  • Include in the cert the respective link domain you wish to use.
  • The certificate should include the intermediary certificates.
  • The ‘key’ upload is for the private key for the certificate.
  • The key and certificates should be in the PEM format.
  • As a reminder, wildcard certificates are not allowed.

Step-by-Step: Universal Links and Sailthru

  1. Create a signed apple-app-site-association (AASA) file matching Apple’s specifications using the Apple Universal Link Documentation and the Apple Shared Web Credential Documentation.
    • We suggest you whitelist only the “/click” path and explicitly blacklist the “/view”, “/o” and “/oc” paths for your Sailthru link domain. This will ensure that Hosted Pages and – most importantly – your Sailthru hosted optout page direct to a functional user preference or opt-out page.
  2. Obtain an https certificate and key for your link domain(s). This must explicitly match the link domain (as configured on the Domains Setup page) and cannot be a wildcard certificate.
  3. Using the my.sailthru.com Universal Links settings page or API, upload all three files.
    Screen Shot 2016-05-02 at 4.23.50 PM
  4. Test the AASA file by entering its new URL in Apple’s App Search API Validation Tool, and, of course, by using links to your app!
 
Top