Universal Links failing for some users but working for others

Thank you so much for the post.

To start I would like to let you know the location for the AASA is incorrect AASA: https://www.gartner.com/apple-app-site-association

I recommend that you review the Universal Tech Note, which provides guidance on the appropriate hosting location for the AASA file.

Example: https://example.com/.well-known/apple-app-site-association

Tech Note: TN3155: Debugging universal links | Apple Developer Documentation

I also recommend to follow the guidelines and use the troubleshooting in that tech note as well.

Hope this helps.

Albert  WWDR

Thank you for your response and for sharing

The AASA URL included in my post was provided as a reference. We do host the AASA file in the supported location (/.well-known/apple-app-site-association) and have verified that it is accessible and valid.

Our primary challenge is that Universal Links are working correctly for the majority of users, but a small subset of users experience failures where the same links open in Safari instead of the app. Since the issue is intermittent and user-specific, we have been unable to reliably reproduce it. We are particularly interested in understanding:

Whether there are known device-level or user-level conditions that can cause Universal Links to stop working. How to determine if the AASA association has become stale or invalid on specific devices. Any diagnostic logs or troubleshooting steps that can help identify why Universal Links are failing only for certain users.

We will review the troubleshooting guidance in TN3155, but any insights into debugging intermittent, user-specific Universal Link failures would be greatly appreciated. Thank you.

Thank you for your response. The user can also opt out of Universal Links by declining to open the app when requested, and the device will remember the user’s intention. I recommend checking the swutil file for registration and the user’s declining to open the app, as this will cause the app to open in the Safari browser as the user intended.

So it's not a link failure but is part of the system. Requesting their sysdiagnose will help you to figure it out what the user intention was.

Albert  WWDR

We're investigating an intermittent Universal Links behavior and would appreciate a review of our AASA (Apple App Site Association) configuration to determine whether there is anything missing or misconfigured that could explain what we're seeing. When we test internally, Universal Links work as expected:

Tested across multiple devices. Tested with fresh installs and reinstalls. Universal Links consistently open the app when expected. No issues reproduced on devices available to us.

However, some of our analytics/tracking tools have flagged a few user journeys that appear unusual. Specifically, we see cases where:

A user starts their journey in the mobile browser. At nearly the same timestamp (or immediately afterward), an app session is initiated. In several cases, the entry point appears to be a Branch.io link.

Because the behavior is difficult to reproduce, we're trying to determine whether there could be an AASA-related issue impacting only certain devices, iOS versions, or installation states. Below is the current AASA response from: https://www.gartner.com/apple-app-site-association HTTP/2 200 content-type: binary/octet-stream content-length: 1747 notice any issues or missing configuration in the AASA file that could cause Universal Links to behave inconsistently across a subset of users? Is there any concern with having both paths and components defined for the same app entry? Could the entry "community.gartner.com/*" under paths be problematic since it appears to include a hostname rather than a path? Are there any known iOS behaviors where Universal Link attribution can result in browser and app sessions appearing to start almost simultaneously, particularly when using Branch.io links?

Any insights, best practices, or troubleshooting suggestions would be greatly appreciated.

Thank you for your response. However, I am unable to comprehend the nature of your inquiry. You have provided a link that is inaccurate and does not contain an AASA file.

 curl -v https://www.gartner.com/apple-app-site-association 

The AASA file should be hosted at:

 curl -v https://www.gartner.com/.well-known/apple-app-site-association

Still not AASA returns when I requested.

Have you read the documentation how to implement Universal Links as well as our tech note?

TN3155: Debugging universal links | Apple Developer Documentation

https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app

Hope this helps. Looking forward to your reply.

Albert  WWDR

Thank you for your response. I have reviewed the Universal Links documentation and Tech Notes that were referenced. From my side, I am able to access and download the AASA file successfully from both locations: https://www.gartner.com/apple-app-site-association & https://www.gartner.com/.well-known/apple-app-site-association

Because the file is accessible and returns valid content in my testing, I am wondering whether the issue could be related to request filtering, bot protection, WAF rules, CDN rules, or user-agent restrictions that may be preventing Apple services from retrieving the file in certain scenarios. I found Apple's recent update regarding hosted AASA file user-agent policies: https://developer.apple.com/search/?q=2025-05-15+Added+User-Agent+policies+for+the+hosted+AASA+file To help us validate our server configuration, could you please confirm the user agents and request patterns that Apple services may use when retrieving the AASA file?

should we explicitly allow any of the following user agents (or others)?

AASA-Bot AASA-Bot/1.0.0 CFNetwork Apple app-site-association swcd

Our objective is to ensure that no security controls, CDN rules, bot mitigation policies, or user-agent filtering on our servers inadvertently block AASA retrieval requests from Apple. Could you please provide guidance on:

The current user-agent string(s) Apple uses to fetch AASA files. Whether Apple recommends allowlisting specific user-agents. Whether there are any additional IP ranges, headers, or request characteristics that should be considered. Any diagnostics that can help verify that Apple is successfully downloading and processing the AASA file.

Any clarification would be greatly appreciated as we are trying to rule out server-side filtering as a potential cause of the Universal Links behavior we are investigating. Thank you for your help.

There is no AASA file still at

curl -v https://www.gartner.com/.well-known/apple-app-site-association

When I make a request to that file I get HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
<title>Just a moment... | Gartner</title>

That request should return an AASA file without any redirect nor HTML.

If you have any filtering for user agents or IP address that does not return the AASA file your solution won't work. Please let me know when your server starts returning the AASA file from any IP and user-agent.

Thanks

Albert  WWDR

Thanks, Albert. We investigated this with our infrastructure team and found that requests to the AASA endpoint are currently subject to security controls, which explains why your request received an HTML response instead of the AASA file.

We also reviewed Apple's guidance regarding hosted AASA files and understand that the endpoint should accept requests from all user agents, including AASA-Bot and CFNetwork.

To ensure we align our configuration with Apple's requirements, could you please confirm whether there are any additional Apple user agents, services, or request sources that may be used to retrieve or validate the AASA file beyond AASA-Bot and CFNetwork?

As per our team, we are allowing for only AASA-Bot/1.0.0 now. So help us rightly on this for which user agent we should allow for this AASA request. Thanks, Nethaji

@Nethaji426 The URL still produces the same issue when we request the AASA file

curl -v https://www.gartner.com/.well-known/apple-app-site-association

We can't go beyond this unless you comply with the requirements. You need to allowed all IP addresses and all user-agents. Wish you luck on your solution.

Albert  WWDR