Introduction
The apple-app-site-association file connects a web site to an Apple app. Apple’s documentation (“Supporting associated domains”) says to “create a file named
apple-app-site-association (without an extension)”, to place it in the site’s .well-known directory, so that the URL is
https://<fully qualified domain>/.well-known/apple-app-site-association, and to “host the file using https:// with a valid certificate and with no redirects”. Shared web
credentials, universal links, Handoff and App Clips all use it. Each subdomain needs its own file. Since macOS 11 and iOS 14 apps no longer ask the web server directly: they ask an Apple-managed content
delivery network, which requests the file “within 24 hours”, and devices check for updates “approximately once per week after app installation”.
Structure
{
"applinks": {
"details": [
{
"appIDs": [ "ABCDE12345.com.example.app", "ABCDE12345.com.example.app2" ],
"components": [
{ "#": "no_universal_links", "exclude": true, "comment": "Matches any URL with a fragment that equals no_universal_links." },
{ "/": "/buy/*", "comment": "Matches any URL with a path that starts with /buy/." },
{ "/": "/help/website/*", "exclude": true },
{ "/": "/help/*", "?": { "articleNumber": "????" } }
]
}
]
},
"webcredentials": { "apps": [ "ABCDE12345.com.example.app" ] },
"appclips": { "apps": [ "ABCDE12345.com.example.MyApp.Clip" ] }
}
The file is one JSON object whose keys are services. The example is Apple’s. Application identifiers have the form <Application Identifier Prefix>.<Bundle Identifier>.
| Key | Meaning (Apple) |
|---|---|
applinks | The universal links service. details: an array of objects, each naming the apps (appID for one, appIDs for several) and optionally components and defaults.
defaults (also directly under applinks): the pattern-matching defaults for the domain; the more specific level overrides the less specific. substitutionVariables: names that map to arrays of strings
that replace $(name) in patterns; predefined variables include $(alpha), $(upper), $(lower), $(alnum), $(digit), $(xdigit), $(region) and $(lang). |
details[].components[] | A dictionary of patterns that must all match for the rule to apply: "/" the path, "?" the query (a pattern, or a dictionary of query item names to patterns), "#" the fragment; each
defaults to *, which matches everything. exclude (default false): when the URL matches, stop and do not open it as a universal link. comment: text the system ignores.
caseSensitive and percentEncoded (both default true). In patterns * matches zero or more characters (greedy) and ? matches any single character; ?* matches one or more.
The order of the array is the order of matching: the first match wins. |
webcredentials | Shared web credentials: apps lists the application identifiers. |
appclips | App Clips: apps lists the App Clip identifiers. |
In the explorer
A file named apple-app-site-association opens here when it is a JSON object with at least one service key (applinks, webcredentials, appclips or
activitycontinuation), each holding what that service holds (applinks: details, apps, defaults or substitutionVariables; the others: an apps array). Any other file with that
name opens as before. The tree names every key with what Apple says it is; the Apps tab lists the application identifiers and the Components tab the URL patterns in the order the system matches them. A problem is an identifier
that is not prefix.bundle, a details entry that names no app, a boolean that is not a boolean, a query that is neither a string nor a dictionary, a substitution variable that is not an array of strings, or a service
without its apps or details. A key the Apple pages read do not describe is labelled, not called an error. Nothing is fetched: the entitlement in the app, the CDN, the certificate and the redirect rule are not checked.
Of 32 public files found, 31 were claimed. The 32nd, Pinterest’s, is not JSON at all: it is a binary CMS (PKCS#7) signed wrapper around the JSON, the older signed form of the file. It is not recognised and opens as before.
Not described
Known, not yet covered
- Reference: the
activitycontinuation(Handoff) service, the older file form (appIDwithpaths, andapps: []) and the signed binary form are not described: the Apple pages read name Handoff and do not describe the key or the older form, and the signed form is not JSON. - Reference: the full syntax of the predefined substitution variables ($(region) and $(lang) take ISO codes) is named, not tabulated.
- Viewer: the application identifier is checked for the shape “prefix.bundle” only; Apple’s page does not give the length of the prefix. The patterns are not evaluated against a URL (no “test a URL” option yet).
- Viewer: the signed (PKCS#7) form is not read.
Unknown
- Reference: a size limit for the file: the pages read give none.
Links
Reference
- Supporting associated domains – Apple developer documentation
- applinks – the universal links service object, with details, components, defaults and substitution variables
- Allowing apps and websites to link to your content – universal links