Deep Links Setup

This guide describes how to configure Iterable to send deep links in your email and SMS campaigns, so your links will open in your mobile app if a user has it installed, and a web browser otherwise.

# Table of contents

# Email and SMS setup

Before setting up deep links, read:

• Email Setup
• SMS Link Shortening and Click Tracking
• HTTPS for Click Tracking

These guides describe how to set up tracking domains and link shortening domains, and how to use HTTPS with these domains. These are necessary steps for sending deep links in email and SMS campaigns.

# Instructions

To configure your Iterable project to use deep links, follow these steps:

# Step 1: Set up a custom tracking domain and enable HTTPS

To enable deep linking, you'll need an HTTPS-enabled custom link tracking domain, rather than Iterable's default link tracking domain (http://links.iterable.com). There are a few reasons for this:

• Apple requires that iOS apps pull apple-app-site-association files from an HTTPS-enabled endpoint, without redirects. Since Iterable hosts this file for your app, (as configured by your site's DNS), you'll need to enable HTTPS.

• Android requires that assetlinks.json files are served with HTTPS. Since Iterable hosts this file for your app, (as configured by your site's DNS), you'll need to enable HTTPS.

• Iterable hosts each tracking domain's aggregate apple-app-site-association file at https://<YOUR_TRACKING_DOMAIN>/apple-app-site-association, and assetlinks.json file at https://<YOUR_TRACKING_DOMAIN>/.well-known/assetlinks.json. It is not possible for Iterable's default tracking domain (http://links.iterable.com) to host these files for all the various Iterable projects that use it as a tracking domain.

# Step 2: Decide which links your mobile apps should open

Determine the precise link patterns your mobile app should open. Once you've made this decision, build apple-app-site-association and assetlinks.json files (if you don't already have them).

For more information, see Iterable's iOS Universal Links and Android App Links guides

# Step 3: Configure your mobile apps to support deep links

To enable deep links in your mobile apps, follow these instructions:

• Configure your iOS app to support Universal Links (the iOS implementation of deep links).
• Configure your Android App to support App Links (the Android imlementation of deep links).

# Step 4: Set up destination domains and paths in Iterable

Destination domains and their paths make it possible to specify that an app should open some links—but not others—for a particular tracking domain.

For each of your tracking domains, you can define multiple destination domains. Iterable uses these destination domains, along with the the paths listed in their associated apple-app-site-association files, to determine which links to rewrite as deep links.

# Example deep link scenario

For example, consider a project that has the following setup:

• A links.example.com tracking domain
• A support.example.com destination domain for that tracking domain
• An associated apple-app-site-association file that specifies /product/* as a path

Now, consider what happens when this project sends an email that contains a link to https://support.example.com/product/widget, from a sender whose sending domain is associated with the links.example.com tracking domain mentioned above.

Since this link URL matches the destination domain (support.example.com) and path (/product/widget matches /product/*), Iterable will rewrite the link as a deep link before sending it. The deep link will look something like https://links.example.com/a/click?_t=7dd2086... (the /a/ denotes that it's a deep link).

On the other hand, a link to https://support.example.com/news/today will not be rewritten as a deep link. The destination domain matches the URL, but the apple-app-site-association file has no match for the path.

# Setting up destination domains

To set up destination domains and their paths:

1. Navigate to Settings > Domains.

2. On the tracking domain you'd like to configure, click Edit.

   

3. On the Tracking Domain screen, click New Destination Path.

   

4. Specify the destination domain for which you'd like your app to open at least some links, and click Create.

5. The destination domain will now be listed in the table. To modify it, click its Edit button.

6. On the Destination Domain screen, use the Edit Configuration buttons to upload the apple-app-site-association and assetlinks.json files you created above. After uploading the files, click Save Changes in each section.

   

   IMPORTANT

   • Each tracking domain has a single assetlinks.json file. Uploading an assetlinks.json file for any of that tracking domain's destination domains overwrites it for all of that tracking domain's destination domains.
   • Upload standard apple-app-site-association files. Iterable previously required apple-app-site-association files that contained an iterable section, and which explicitly called out the /a/ path which Iterable uses to denote deep links. However, this is no longer required. The legacy file format still works, but will cause Iterable to rewrite links that contain /a/ as deep links.
   • To enable or disable a particular destination domain for a tracking domain, navigate to the Tracking Domain screen for the tracking domain in question, click the down arrow next to the destination domain in question, and choose Enable or Disable.

# Step 5. Test your deep link configuration

To test your deep link configuration, follow these steps:

1. Check to make sure that Iterable exposes your tracking domain's aggregate apple-app-site-association file at https://<YOUR_TRACKING_DOMAIN>/apple-app-site-association. This file is a combination of all the apple-app-site-association files uploaded to destination domains associated with the relevant tracking domain.

2. Check to make sure that Iterable exposes your assetlinks.json file at https://<YOUR_TRACKING_DOMAIN>/.well-known/assetlinks.json.

3. Send an email campaign to yourself, from a sender who's ultimately associated with the tracking domain to which you just added a destination domain. In the email, include test links—some that should be rewritten as normal links (which include /u/ after Iterable rewrites them), and some that should be rewritten as deep links (which include /a/ after Iterable rewrites them).

4. When you receive the message, inspect the link URLs to make sure that they've been rewritten as you expect.

5. Test opening these same links in your mobile app, to ensure that the app responds as you expect.

# Viewing deep link files

The configuration enhancements release removes the the apple-app-site-association and assetlinks.json files from the Settings > Project Settings screen. To view the Iterable-hosted versions of these files, navigate to:

• https://<YOUR_TRACKING_DOMAIN>/apple-app-site-association
• https://<YOUR_TRACKING_DOMAIN>/.well-known/assetlinks.json

# Troubleshooting deep links

If your deep links open in a web browser instead of your mobile app, make sure that:

• You've enabled HTTPS for your tracking domain.
• Your apple-app-site-association file is properly formatted.
• Your mobile app is configured to use deep linking, as described in iOS Universal Links and Android App Links.

If your deep link open your app, but to the wrong content, review:

• The URL handling methods in your app's code (iOS, Android).
• The contents of your apple-app-site-association file.

# Deep link configuration enhancements: migration instructions

The deep linking configuration enhancements release introduced various changes to the configuration of deep links in Iterable. These changes make it possible to:

• Define the specific domains and paths that Iterable will (and will not) rewrite as deep links for a given tracking domain (by defining destination domains and giving each one an apple-app-site-association file). This allows you to decide on the subdomains for which a tracking domain should rewrite links as deep links.

• Upload and manage apple-app-site-association and assetlinks.json files directly in Iterable, without contacting your customer success manager.

# Before the configuration enhancements release

Before the configuration enhancements release, for projects with deep links enabled, the tracking domain associated with an email campaign's sender caused Iterable to rewrite as deep links all links that shared a root domain with that tracking domain.

For example, a tracking domain of links.example.com caused Iterable to rewrite links to support.example.com, docs.example.com and app.example.com all as deep links.

# After the configuration enhancements release

After the configuration enhancements release, this same behavior remains in effect for tracking domains already configured to send deep links. On the Settings > Domains screen, Iterable marks these tracking domains as Legacy, and they continue to rewrite deep links for all links that point to the tracking domain's root domain, using your existing apple-app-site-association file.

However, once you manually add a new destination domain to a legacy tracking domain, Iterable no longer respects the original configuration. At that point, you'll need to define a destination domain for each domain or subdomain for which you'd like Iterable to rewrite deep links, and upload an apple-app-site-association file for each (to define the specific paths for that domain or subdomain for which links should be rewritten as deep links).

For example, to configure tracking domain links.example.com to rewrite deep links for in-email links that point to support.example.com, docs.example.com or app.example.com, you'll need to add three destination domains to that tracking domain.

# Further reading

• HTTPS for Click Tracking
• Iterable's Deep Links guides
• Apple's Universal Links documentation
• Android's App Links documentation