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.

This new functionality allows a standard “https://” link to open straight to a registered app, as opposed to embedding deep-link protocol links in emails.

Note: Third-party messaging apps may not yet support Universal Links and may continue directing users to a web browser. All links rewritten in your message will open inside your app, including social share and external site links. Currently, there is no workaround to this.

You must provide Sailthru one (1) file to successfully enable Universal Links using your Sailthru Link Domain:

  • An Apple App Site Association file

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

Enabling app links from your link domain requires a small JSON file called the Apple App Site Association (AASA) file to be accessible on your domain. The file provides permissions to iOS to open links directly in apps. Your AASA file can provide permissions for multiple apps, including development and staging versions, if they have their own app IDs. For example, it may resemble this sample:

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

Points to remember for your AASA file:

  • Sailthru can host this file for you at your established link domain.
  • Apple requires the AASA file to be accessible via https.
    • By default, Sailthru serves rewritten links and link domain pages using https.
  • You may upload as many 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.

See Establishing Universal Links with Sailthru Email Link Rewrites for more information on adding your AASA file to your account.

Link Parsing and Tracking

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 steps to enable your app to directly request this URL when it is received. This request ensures proper click attribution in your Sailthru stats while also redirecting to the intended destination URL. The URL then returns data that your app may require to identify the user and their intended destination.

Establishing Universal Links with Sailthru Email Link Rewrites

  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.
    • Only the “/click” path
    • Blacklist the “/view”, “/o” and “/oc” paths for your Sailthru link domain. This will ensure that Hosted Pages and – most importantly – your Sailthru hosted opt out page direct to a functional user preference or opt-out page.
  2. Using the my.sailthru.com Universal Links settings page or API, upload your AASA file.
    Screen Shot 2016-05-02 at 4.23.50 PM
  3. Test the AASA file by entering your link domain in Apple’s App Search API Validation Tool and by using links to your app.

Enable Opening Links in the Native Browser

To enable this free feature on your account, contact Sailthru Support or your CSM.

  1. Check that your Apple App Site Association File is uploaded to Sailthru.
  2. Blacklist the “/external” path in addition to the “/view”, “/o”, and “/oc” paths.
  3. When a user clicks the link, Sailthru parses it in one of the following ways:
    • If the link matches the Sailthru link domain, then we use the “/click/” path and open the link in the app.
    • If the link doesn’t match the Sailthru link domain (for example, Instagram), then we use the “/external/” path and open the link in the browser.
    • If you added “?noapp=true” to any URL value, we rewrite the link as “/external/” and open the link in the browser.

The SDK is set up to receive the link, parse it to the original destination, and also call back to Sailthru to report the tracked link click.

Top