Link resolution

You need to set up link resolution for deep linking via email, SMS, QR codes, and platforms that shorten links. If you do not set up link resolution for such cases, a redirect from a universal link sends all users to the App Store, even if they have your app installed. With link resolution, the redirect to the universal link occurs within your app, and existing users are not sent to the App Store.

How it works

Link resolution is only applicable when users that have your app installed click on a redirect URL. You need to configure the domain in the redirect URL as a universal link domain in your app.

This is how link resolution works:

1. When an existing user clicks a redirect link, iOS opens your app.
2. Your app passes the redirect URL to the resolveLinkWithUrl link resolution method in the Adjust SDK.
3. The link resolution method in the Adjust SDK compares the domain in the redirect URL against the link resolution domain that the developer has set in the Adjust SDK, and one of the following happens:

• Domains do not match - The method returns the deep link URL as is.
• Domains match - The method resolves the link and returns the resulting deep link.

The Adjust SDK will follow up to ten redirects when attempting to resolve a URL. If there are more than ten redirects, the SDK will return the tenth redirect URL.

1. Your app receives the returned URL and opens deep link content and displays it to the user. Your app also calls the appWillOpenUrl method in the Adjust SDK with the returned URL. This sends the resolved URL to the Adjust backend for tracking.

Use cases

Link resolution is applicable for the following cases:

• Email marketing
• Platforms that shorten URLs

Email marketing

When email marketers run campaigns, the email marketing platform typically wraps all links in the emails with its own click tracking redirect URL. This lets email marketers view click-through statistics in the email marketing platform. However, if the emails contain universal links, the redirect URL causes iOS to not resolve the universal links properly.

Setup

1. Create a domain or a subdomain on your domain that is dedicated to email tracking. If you already have a domain or subdomain for email tracking, we recommend that you create a new one so that you can complete this implementation without disrupting existing campaigns. After you complete and test this implementation, you can switch this implementation to your existing email redirect domain.

Example: email.example.com

1. Add the email redirect domain to your Associated Domains configuration in Xcode.

Example: applinks:email.example.com

1. Set up your universal links.

2. Ensure that you have added your email redirect domain to resolveUrlSuffixArray of the resolveLinkWithUrl link resolution method.

3. Configure your email redirect domain as a custom tracking domain with your email marketing platform / ESP.

4. Set up a content delivery network (CDN), such as Amazon CloudFront, CloudFlare, or Fastly, to handle incoming requests to your email redirect domain. On the CDN, you need to set up the following:

   1. SSL certificate - iOS requires that universal links use only HTTPS. So, an SSL certificate is required for your email redirect domain.
   2. AASA (Apple-App-Site-Association) file - Depending on your email partner, you need to either host your own AASA file or upload the AASA file to the email partner system. For information on hosting an AASA file, refer to your email partner's documentation.

   You can download the AASA file for your universal link that is hosted on this path - https://example.go.link/.well-known/apple-app-site-association. Replace the domain with your universal link domain. You can copy the Adjust Universal Link AASA file and use it for your email redirect domain AASA file. If your email partner requires you to host your own AASA file, your CDN needs to serve it from the corresponding path on your email redirect domain - https://email.example.com/.well-known/apple-app-site-association

   1. Point all requests to the email redirect domain (except for the AASA file, if applicable) to the email partner’s redirect server.

   Example: redirect.example.net

5. Configure the DNS for your email redirect domain to point to your CDN.

For partner-specific instructions that correspond to the above instructions, refer to our ESP integrations section in the Help Center.

Support for email partners

In order to use link resolution, your email partner needs to let you to set up the redirection domain (or subdomain) as a universal link domain. If this is the case, you can point their redirection service to your own custom domain.

Examples:

• Braze - Depending on which ESP Braze has assigned, set up your redirect domain with SendGrid or SparkPost, and point your own custom domain to it. You can then configure your custom domain as a universal link domain.

• Iterable - Iterable provides the URL redirection service that supports custom domains.

• Mailchimp - Link resolution is not available because Mailchimp does not allow you to configure their redirect domain as a universal link.

URL shorteners

When marketers run certain types of campaigns, sometimes a short URL is required. For example, SMS has a 160 character limit. Sometimes, customers want to shorten a link and share it on team communication platforms, such as Slack. However, if the short URL redirects to a universal link, iOS does not resolve the universal link properly.

Setup

1. Create a domain or subdomain on your domain that is dedicated as a URL shortener.

If you already have a domain or subdomain as a URL shortener, we recommend that you create a new one so that you can complete this implementation without disrupting existing campaigns. After you complete and test this implementation, you can switch this implementation to your existing URL shortener domain.

1. Add the URL shortener domain to your Associated Domains configuration in Xcode.

Example: applinks:short.example.com

1. Set up your universal links.
2. Ensure that you have added your email redirect domain to resolveUrlSuffixArray of the resolveLinkWithUrl link resolution method.
3. Set up a URL shortener service that supports universal links. Adjust does not provide any URL shortening services.

Example: short.io

1. Configure your URL shortener domain as a custom domain on the URL shortener service. You need to configure the DNS for your URL shortener domain to point to the URL shortener service’s servers. (Reference documentation to add a custom domain in short.io).
2. Configure universal links on the URL shortener service. (Reference documentation to configure universal links in short.io).