apple-app-site-association generator for Universal Links
This tool writes the apple-app-site-association JSON for iOS Universal Links, with webcredentials and App Clips if you need them. It checks your Team ID and bundle ID, supports path exclusions, and lists the hosting rules and Apple CDN caching to expect.
Updated
apple-app-site-association
{
"applinks": {
"details": [
{
"appIDs": [
"ABCDE12345.com.example.app"
],
"components": [
{
"/": "/help/website/*",
"exclude": true
},
{
"/": "/buy/*"
},
{
"/": "/help/*",
"?": {
"articleNumber": "????"
}
}
]
}
]
},
"webcredentials": {
"apps": [
"ABCDE12345.com.example.app"
]
}
}- App ID
- ABCDE12345.com.example.app
- Save the file as
- apple-app-site-association (no .json extension)
- Host it at
- https://www.example.com/.well-known/apple-app-site-association
- Serve as
- HTTPS, valid certificate, HTTP 200, no redirects, Content-Type application/json
- Xcode entitlement
- applinks:www.example.comand webcredentials:www.example.com
- Check your server
- curl -sI https://www.example.com/.well-known/apple-app-site-associationExpect 200, application/json and no Location header.
- Check what Apple's CDN holds
- curl -s https://app-site-association.cdn-apple.com/a/v1/www.example.comDevices read this copy, not your server.
- Apple's CDN requests the file within 24 hours of the first check and devices look for updates about once a week after install, so a change does not apply instantly.
- Each subdomain (example.com, www.example.com) needs its own entitlement entry and serves its own copy of this file.
What goes in an apple-app-site-association file?
Universal Links open your website's URLs in your iOS app. Your site proves it allows that by serving a JSON file named apple-app-site-association from /.well-known/ with no extension. The file lists your app by App ID, which is your Team ID, a dot and the bundle ID, and says which URLs it wants.
In the components format each rule is an object: / matches the path, ? matches query items, # matches the fragment, and exclude: true tells the system not to open matching URLs in the app. A comment key is for you and isn't used for matching. The older paths format is a list of path strings where a NOT prefix excludes.
webcredentials lists apps that may use shared web credentials, and appclips lists App Clip IDs. Since iOS 14 and macOS 11, devices don't fetch your file directly: they get it from an Apple-managed CDN, which fetches it within 24 hours, so changes are not instant.
App ID = <Team ID>.<bundle ID> e.g. ABCDE12345.com.example.app
applinks.details[].components: [{ "/": "/buy/*" }, { "/": "/help/*", "exclude": true }]What do the components keys mean?
| Key | Matches | Example |
|---|---|---|
| / | URL path; * is a wildcard | { "/": "/buy/*" } |
| ? | Query items, as name: value | { "?": { "articleNumber": "????" } } (exactly four characters) |
| # | URL fragment | { "#": "no_universal_links", "exclude": true } |
| exclude | true: do not open as a universal link | { "/": "/help/website/*", "exclude": true } |
| comment | A note for humans, not used to match | { "/": "/buy/*", "comment": "Product pages" } |
How to create an apple-app-site-association file
- 1Enter your IDsFind the 10-character Team ID in your Apple Developer membership details and the bundle ID in Xcode.
- 2List the pathsOne path per line. Prefix ! to exclude a path, and add ?name=value or #fragment after a space for components rules.
- 3Save and uploadSave the output as apple-app-site-association with no extension and upload it to /.well-known/ over HTTPS with no redirects.
- 4Add the entitlement and testAdd applinks:your-domain under Associated Domains in Xcode, then check your server and Apple's CDN copy with the curl commands.
Frequently asked questions
Should the apple-app-site-association file have a .json extension?
Why do my Universal Link changes take so long to show up?
What is the difference between the components and paths formats?
Where do I find my Apple Team ID for an app site association file?
Do I need a separate association file for www and the bare domain?
How do I stop certain URLs from opening in the app?
Sources
Need a custom dev tool for your team?
We build internal tools, dashboards, APIs, and SaaS platforms. If you can describe it, we can ship it.
Built by CountryDevs · No signup · No ads · We count visits, never what you enter