Universal Links: Troubleshooting and FAQ


If you're interested in setting up Universal Links so clicking an email on mobile will open the app, start by referring to our documentation page:

If you're still not seeing the app open, please take a look at the suggested troubleshooting steps: 

  • Is your Apple App Site Association (AASA) file signed? If your app is not signed, the Content-type may be the issue. The resource here suggests a signed file should have the Content-type application/pkcs7-mime and an unsigned AASA file should be application/json.
  • Going to should not have any redirects on click through or copy-paste into the browser.
  • We suggest you whitelist only the "/click" path and explicitly blacklist the "/view", "/o" and "/oc" paths for your Sailthru link domain. This will ensure that Hosted Pages and – most importantly – your Sailthru hosted optout page direct to a functional user preference or opt-out page.
  • Your paths should not have any "special characters", such as a non-standard quotation mark. Opening the AASA file may reveal the quotation looks normal, but a curl on the file URL can show if the quote is a non-standard character. 


  • You can check to make sure the file is in proper json format with:
  • Test to make sure your AASA url passes all the checks in this validation tool:
  • Make sure Associated Domain is enabled and added in the proper format:
  • The App prefix and ID in the AASA file must match what is in your project.
  • Has your app been coded to support Universal Links? These resources may help:

Notably the "Step 6 or 7 failed" section - When you long-pressed on the link that you emailed, the "Open in <your app>" option was not presented. There are multiple reasons why this might happen.


If you instantiate a SFSafariViewController, WKWebView, or UIWebView object to handle a universal link, iOS opens your website in Safari instead of opening your app. However, if the user taps a universal link from within an embedded SFSafariViewController, WKWebView, or UIWebView object, iOS opens your app.


To handle the link inside your app when it is opened by Universal Link just implement

application:continueUserActivity:restorationHandler: on your AppDelegate.
if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
       NSURL *url = userActivity.webpageURL;
       // do something with the URL

   return true;


  • My email has URLs outside of the website that the app is opening (such as Facebook). How can I stop this? 

There currently isn't a way to control which URLs open in the app. The AASA file is tied to the link domain and all the links in the email have this domain; it's all or nothing. We did whitelist / blacklist some paths, but all links appear as "" so we can't specifically see which one is the Facebook page, for example.

You can force a URL to not be rewritten for click tracking. This will ensure the URL will not open in the app, but clicks on the URL also will not be tracked. Keep in mind some email clients may not support this, but you can stop link tracking by removing the quotations around the URL in the href:

no strings or zephyr around the url:<br>
<a href=>click here</a><br><br>

zephyr with strings inside bracket:<br>
<a href={""}>click here</a><br><br>

This creates a clickable url that was not rewritten in Gmail. In Gmail this redirects fine, however this may not be supported across all email clients as both of these render without quotes around the URL in the email headers. Here is how the above code renders in Gmail email headers:

no strings or zephyr:<br>
<a href=>click here</a><br><br>
zephyr with strings inside bracket:<br> <a href=>click here</a><br><br>


  • How do I ensure my app opens to the appropriate section in the app if I can't see the source of the URL due to it being behind the link domain?

By design, 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 actions to enable your app to directly request this URL when it is received. This request will ensure proper click attribution in your Sailthru stats while also redirecting to the intended destination URL on your site. The redirected URL can then return data that your app may require to identify the user and their intended destination.

The Universal Links documentation goes into extra detail how to do this:

Specifically the "Preparing Your App to Handle Universal Links" section.

After you specify your associated domains, adopt the UIApplicationDelegate methods for Handoff (specifically application:continueUserActivity:restorationHandler:) so that your app can receive a link and handle it appropriately.

When iOS launches your app after a user taps a universal link, you receive an NSUserActivity object with an activityType value of NSUserActivityTypeBrowsingWeb. The activity object's webpageURL property contains the URL that the user is accessing. The webpage URL property always contains an HTTP or HTTPS URL, and you can use NSURLComponents APIs to manipulate the components of the URL.

You would resolve the link you get from iOS; that link will be the rewritten link. Call it in the background. Get the response for what the intended URL was. Then the app determines where to go based on that.

If the original link was:

Apple will pass off the link to the app, replacing the start of the string like this:


The app can replace that string back with the link domain:


The app could then use iOS (NSURLSession most likely) to do a GET on that modified URL. Doing this will cause Sailthru to register the click and the app can rely on the redirect received from the server call to Sailthru to determine where to point the app.


  • Are there any workarounds other clients have used to control which URLs do and do not open within the app? 

Sure thing! While we cannot help troubleshoot or set this up, or promise that these will fit with your set up, clients have shared with us their workarounds that worked for them. If your emails are using the URLs* instead of*, you can use this URL to designate when a link should not redirect to the app. Then, tell your AASA file to only redirect links that contain* via the base64 version of the string.

You can look at the base64 version of the URL containing the subdomain because most URLs will vary in length. However, you can make the safe assumption that the beginning of a URL will have consistent base64 encoding. 

Another workaround is to create a subdomain like that redirects to the correct URL and you tell your apple-app-site-association file to exclude those links.

If you have any workarounds that have worked for you, please share with We will log it here to help future clients!


  • I have requested and it was confirmed the AASA file was removed for my production app, but customers are still reporting the app opens. Is there a cache? How do we stop the app from opening?

We can confirm that once the AASA file is removed, there is no cache on the Sailthru-side that is causing the AASA file to still be accessed. This can be checked by visiting your AASA URL (e.g., and seeing if the AASA file is downloaded when you hit the page. 

Since the device fetches the AASA file, it's possible the file is still on the device and saved because of the entitlement preference to open the app instead of the website. If the device fetched the AASA file each time, it would hit the 404 error on the above page.

The above article suggests the AASA file is fetched once on install and any new updates to the app. After that, it uses the version that has been fetched.

Other forums that suggest the same:

Based on the above resources, the device still holds on to the AASA file until the app is updated or uninstalled.