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.
In this article
- Email and SMS setup
- Viewing deep link files
- Troubleshooting deep links
- Deep link configuration enhancements: migration instructions
- Want to learn more?
Email and SMS setup
Before setting up deep links, read:
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.
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
(something other than
links.eu.iterable.com). There are
a few reasons for this:
Apple requires that iOS apps pull
apple-app-site-associationfiles 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.
Iterable hosts each tracking domain's aggregate
https://<YOUR_TRACKING_DOMAIN>/apple-app-site-association, and your
Step 2: Decide which links your mobile apps should open
Even if you don't have an iOS app, you'll need to create an
file. Iterable uses this file to determine the paths to rewrite as deep links.
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 implementation 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 paths listed in
apple-app-site-association files, to determine which links
to rewrite as deep links.
Consider a project with the following setup:
support.example.comdestination domain for that tracking domain
- An associated
apple-app-site-associationfile that specifies
/product/*as a path
Now, consider what happens when this project sends an email that contains a link
https://support.example.com/product/widget, from a sender whose sending
domain is associated with the
links.example.com tracking domain mentioned
Since this link URL matches the destination domain (
/product/*), Iterable will rewrite the link as
a deep link before sending it. The deep link will look something like
/a/ denotes that it's a
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.
- The sender you select for an email campaign determines its sending domain.
- The sending domain determines the tracking domain.
- The tracking domain has a set of destination domains.
- Each destination domain has an
apple-app-site-associationfile, which specifies URL patterns your app can handle for that destination domain.
Because of this, the sender you select for an email campaign ultimately determines which links Iterable rewrites as deep links.
Setting up destination domains
To set up destination domains and their paths:
Go to Settings > Domains.
Click Edit to configure one of your tracking domains.
On the Tracking Domain screen, click New Destination Path.
Specify the destination domain for which you'd like your app to open at least some links, and click Create.
The destination domain will now be listed in the table. To modify it, click its Edit button.
On the Destination Domain screen, use the Edit Configuration buttons to upload the
assetlinks.jsonfiles you created above. After uploading the files, click Save Changes in each section.
- Each tracking domain has a single
assetlinks.jsonfile. Uploading an
assetlinks.jsonfile 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-associationfiles. Iterable previously required
apple-app-site-associationfiles that contained an
iterablesection, 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, go to the Tracking Domain screen for the tracking domain, click the down arrow next to the destination domain, and choose Enable or Disable.
- Each tracking domain has a single
Step 5. Test your deep link configuration
To test your deep link configuration, follow these steps:
Check to make sure that Iterable exposes your tracking domain's aggregate
https://<YOUR_TRACKING_DOMAIN>/apple-app-site-association. This file is a combination of all the
apple-app-site-associationfiles uploaded to destination domains associated with the relevant tracking domain.
Check to make sure that Iterable exposes your
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).
When you receive the message, inspect the link URLs to make sure that they've been rewritten as you expect.
Open these same links in your mobile app to ensure that the app responds as you expect.
To verify that your tracking domain's destination domains are enabled, go to Settings > Domains, open the tracking domain, and make sure the table of destination domains lists them as Enabled. If not, click the down arrow next to each destination domain and select Enable.
Viewing deep link files
The configuration enhancements release
assetlinks.json files from
the Settings > Project Settings screen. To view the Iterable-hosted versions
of these files, go to:
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.
apple-app-site-associationfile 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, check:
- The URL handling methods in your app's code (iOS, Android).
- The contents of your
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 won't rewrite as deep links for a given tracking domain (by defining destination domains and giving each one an
apple-app-site-associationfile). This allows you to decide on the subdomains for which a tracking domain should rewrite links as deep links.
Upload and manage
assetlinks.jsonfiles directly in Iterable, without contacting your customer success manager.
If your Iterable project already used deep links prior to the release, your existing configuration will continue to work as expected. However, to take advantage of the new enhancements, you'll need to modify your project's configuration.
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
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
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
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
app.example.com, you'll need to add three destination domains to that
For any tracking domain, you can enable either your legacy destination domain (which rewrites all links that share the tracking domain's root domain), or you can enable any subset of its new destination domains. You cannot enable both at the same time.
Want to learn more?
For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!