Marigold Engage by Sailthru supports the validation requirements of Apple's Universal Links functionality for our customers who use white-labeled link domains in 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.
You must provide one (1) file to successfully enable Universal Links using your 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:
- Marigold Engage by Sailthru can host this file for you at your established link domain.
- Apple requires the AASA file to be accessible via https.
- By default, Marigold Engage by 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 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 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.
The Mobile SDKs automatically interpret email link rewrites and can give the native application the original link's destination. Mobile App developers should read the Mobile SDK documentation/ReadMe for information on setting up this functionality.
Establishing Universal Links with Email Link Rewrites
- 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.- Add the "/click" and "/click/*" path to your safelist.
- Add the "/view", "/o" and "/oc" paths to your blocklist for your Marigold Engage by Sailthru link domain. This will ensure that Hosted Pages and - most importantly - your hosted opt out page direct to a functional user preference or opt-out page.
- Using the my.sailthru.com Universal Links settings page or API, upload your AASA file.
- Test the AASA file. Check this Stack Overflow answer for help with testing.
Enable Opening Links in the Native Browser
To enable this free feature on your account, contact Support.
- Check that your Apple App Site Association File is uploaded to Marigold Engage by Sailthru.
- Add the "/external" path to your blocklist in addition to the "/oc" path.
- When a user clicks the link, the system parses it in one of the following ways:
- If the link matches the Marigold Engage by Sailthru link domain, then we use the "/click/" or "/click/*" path and open the link in the app.
- If the link doesn't match the Marigold Engage by 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.
Examples
The following examples show how Marigold Engage by Sailthru parses links.Link domain: link.example.com
Apple App Site File: safelist: /click/ and /click/* blocklist: /oc/, /external/
Marketer adds this link: https://www.example.com/products/product-name?psrc=browse:category
System rewrites it to: https://link.example.com/click/<hash>
App Will Open: Yes
Why: The original root domain "example.com" matches a link domain in the account and used the /click/ path as a result.
Marketer adds this link: facebook.com/example
System rewrites it to: https://link.example.com/external/<hash>
App Will Open: No
Why: The original root domain "facebook.com" does not match the link domain and the link rewrite used the /external/ path as a result.
Marketer adds this link: https://www.example.com/how-example-works.htm?noapp=true
System rewrites it to: https://link.example.com/external/<hash>
App Will Open: No
Why: The original root domain "example.com" did match the link domain, however the marketer adding the "noapp=true" query param and the link rewrite used the /external/ path as a result.
