To have more context before start, my team had previously integrated Universal Links, and it worked as expected. However, recently, it stopped working entirely. The team, particularly the iOS developers, are unsure why the Universal Links integration no longer functions as before.
This post is not focused on guiding you through the process of integrating Universal Links into your app. Instead, it focuses on troubleshooting issues with Universal Links. If you are looking for help with setting up Universal Links, you can check this page from Apple.
Ideally, when implementing Universal Links in your application, your project should already created a two-way association between your app and your websites, specifying the URLs that you app handles.
On your website, you should have the apple-app-site-association file hosted at the endpoint /.well-known/apple-app-site-association, and Associated Domains with applinks configuration in your Xcode project.
Let’s get started and identify the issues you’re experiencing!
If your phone opens the app, but it only opens the home screen, not a specific screen. This means you’ve configured Universal Links correctly for your project. However, to open a specific screen, the iOS developer needs to handle the URL and ensure it opens the appropriate screen (or flow) based on the endpoint.
If your phone opens Safari instead of the app. If you are certain your app worked correctly with the previous configuration, there may be an issue with the apple-app-site-association (AASA) file. Let’s debug it!
To debug your Universal Links, I recommend using the Notes app. Add as many URLs as you want to test, then long-press on the link to see your options.
If Universal Links are configured correctly, you should see two options:
Open in {Your App Name}Open in SafariThis testing approach allows you to set the default behavior for your device when Universal Links from this domain are pressed in the future. You can change this default choice by repeating the same steps and selecting a different option.
If you do not see the option Open in {Your App Name}, move to the next check which is take a closer look at the AASA file’s accessibility.
Run this command in the Terminal to check:
curl -v https://{you-domain}/.well-know/apple-app-site-associationIf you see a 301 or 302 HTTP status code, your website is doing a redirect, which is not supported when hosting the AASA file. The file must be directly reachable without any redirects.
Please note: Redirection is allowed in cases where Universal Links are triggered from another app. If the user presses a link that redirects to a Universal Link, they will first see Safari, and then your app will open.
If you see a 403 or 404 HTTP status code, your website is denying access. This often happens when the AASA file is not publicly accessible, or your site is blocked for some other reason.
This was an issue I encountered. In my case, Cloudflare blocked all bot traffic to the website, and it flagged requests to the AASA file as bot traffic. You need to ensure your web configuration allows direct access to the AASA file from all geographical locations and IP addresses.
Finally, you can verify what AASA file Apple’s CDN has cached for your domain.
Open this link in your browser: https://app-site-association.cdn-apple.com/a/v1/{your-domain}
Or, run this command in the Terminal:
curl -v https://app-site-association.cdn-apple.com/a/v1/{your-domain}The content of the AASA file from Apple’s CDN is what applies to your app.
When your app is installed on a device, the device downloads the AASA file from the CDN immediately. It checks for updates approximately once a week after the app is installed. To download a newer version of the AASA file, you need to reinstall the app, as there is no direct CDN invalidation option.
Hopefully, by the time you’ve reached this point, you’ve resolved your issues 🙈. If you’re still facing problems with Universal Links, I recommend checking this resource from Apple: TN3155: Debugging universal links