What the Apple checks are based on
The rules come from Apple's
Supporting associated domains
page, the applinks reference
and TN3155: Debugging universal links.
- The file lives at
https://domain/.well-known/apple-app-site-association, with no extension, over HTTPS with a valid certificate and no redirects. - Every subdomain in your entitlement needs its own file.
applinks:*.example.comreads the file fromexample.com. - App IDs are
TEAMID.bundle.id, for exampleABCDE12345.com.example.app. The team ID is the 10-character prefix from your developer account. - Apple's current pages do not name a required content type. The page warns on
anything other than
application/json, since the file is JSON. - Since iOS 14 and macOS 11, devices get the file from Apple's CDN, not from your
server. The CDN requests it within 24 hours, and devices check for updates about
once a week. To skip the CDN while developing, add
?mode=developerto the entitlement, for exampleapplinks:example.com?mode=developer.
How the URL test matches
For each app, the page walks the details entries that list it, in order,
and each entry's components in order. The first component that matches
decides. If it has "exclude": true, the link stays in the browser. If no
component matches, the link stays in the browser too.
- A component matches when every key it sets matches:
/against the path,?against the query,#against the fragment. A missing key matches anything. *matches zero or more characters,?matches exactly one, and?*matches one or more./buy/*matches/buy/and/buy/shoes, not/buy.- When
?is a dictionary, each key is a query item name and its value is a pattern for that item's value. Other query items in the URL are ignored. caseSensitiveandpercentEncodeddefault totrue. You can change them inapplinks.defaults(whole domain), in adetailsentry'sdefaults(that entry), or on a single component. The most specific one wins.- Substitution variables such as
$(lang),$(region),$(digit)or your own names fromsubstitutionVariablesare expanded. For$(lang)and$(region)the page accepts any 2 or 3 letter code and any 2 letter code, not Apple's exact lists. - The older
appIDpluspathsformat is still read. A path starting withNOTexcludes. TN3155 asks you not to mix the two formats.
On a Mac you can check the same thing with Apple's own tool:
sudo swcutil verify -d example.com -j ./apple-app-site-association -u https://example.com/buy/shoes
On an iPhone with Developer Mode on, Settings > Developer > Universal Links has an Associated Domains Development switch and a Diagnostics screen that tests a URL against the apps installed.
What the Android checks are based on
The rules come from Configure website associations and Troubleshoot App Links.
- The file lives at
https://domain/.well-known/assetlinks.json, served asapplication/json, over HTTPS even if your intent filters declare onlyhttp, with no 301 or 302 redirect. - Each host in your intent filters needs its own file. A redirect from
example.comtowww.example.comfails verification forexample.com. - The file is a JSON array of statements. A statement verifies App Links when its
relationarray containsdelegate_permission/common.handle_all_urlsand its target hasnamespaceandroid_app, thepackage_name(yourapplicationId) andsha256_cert_fingerprints. - Fingerprints are 32 bytes in upper case hex, separated by colons. A lower case fingerprint is a common reason verification fails.
- With Play App Signing, the build users install is signed by Google's key. Use the fingerprint from Play Console, not the one from your local keystore. Add the debug or upload key fingerprint too if you test those builds.
Dynamic rules on Android 15
On Android 15 (API 35) and higher, with Google services installed, a statement can
carry relation_extensions with dynamic_app_link_components.
These rules narrow what your manifest declares; they cannot add hosts or paths the
manifest does not cover. Rules are checked in order and the first match wins. A URL
that matches no rule does not open the app. If any field is malformed or empty,
Android drops all the dynamic rules and uses only the manifest. Android 14 and lower
ignore them.
The URL test on the Android tab runs only these dynamic rules. Android's
* stops at the first occurrence of the character that follows it in the
pattern, so /a*b does not match /axbyb. Apple's
* does match that.
Why loading the file in the browser usually fails
A web page can only read a response from another domain if that server sends CORS
headers, and most servers do not send them for files in .well-known.
Phones do not care about CORS, so a blocked request here says nothing about whether
your file works. Run the curl command and paste the output instead.
Google's Digital Asset Links API does allow requests from browsers.