Free tools

Apple App Site Association Validator

Check that your apple-app-site-association file is valid, see the copy Apple's CDN actually serves to iPhones, and test whether a URL opens your app.

  • Free
  • No account needed
  • Results you can share

The host in your Associated Domains entitlement, without applinks:. A full URL works too.

For example /product/123. We tell you whether this URL opens the app, using Apple's matching rules.

Try:

What happens when someone taps your link

Every stage has to pass for the app to open. Run a check to see where your link stops.

  1. Someone taps your link on an iPhone

    In Messages, Mail, Notes or another app.

  2. Your server hands over the file

    Apple fetches https://your-domain/.well-known/apple-app-site-association. It must answer HTTP 200, with no redirect.

  3. The file can be read

    Valid JSON, with an applinks section.

  4. The file names your app

    Your Team ID and bundle ID, and which paths open the app.

  5. Apple's CDN has the same copy

    iPhones download the file from Apple, not from your server.

  6. Your app opens

    On the screen the link points to.

What this validator checks

  • The file loads over HTTPS at /.well-known/apple-app-site-association with HTTP 200 and no redirects. Apple does not follow redirects.
  • It is 128 KB or smaller and parses as JSON.
  • The applinks section has details entries, each with appID or appIDs in the TEAMID.bundle.id format.
  • Every entry has components or paths, so it matches at least some URLs.
  • Apple's CDN has a copy, and that copy matches what your server returns.
  • Optionally, whether a specific URL opens the app, using Apple's matching rules: entries in order, first match wins, excludes included.

How Universal Links are verified

A Universal Link is an ordinary HTTPS URL that iOS opens in your app instead of Safari. For that to happen, two things must agree. Your app declares the domain in its Associated Domains entitlement (applinks:links.example.com), and the domain publishes an apple-app-site-association file naming your app and the URLs it handles.

When the app is installed or updated, iOS fetches that file through Apple's CDN and stores it. If the file was missing or invalid at that moment, links keep opening in Safari until the next refresh, even after you fix it. That is why this tool checks the CDN copy as well as your server.

A minimal valid file

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [
          { "/": "/admin/*", "exclude": true },
          { "/": "/*" }
        ]
      }
    ]
  }
}

Frequently asked questions

Where does the apple-app-site-association file go?
Serve it at https://your-domain/.well-known/apple-app-site-association with no file extension. It must load over HTTPS with a valid certificate, return HTTP 200 and not redirect. Each domain and subdomain in your Associated Domains entitlement needs its own file.
Why does my Universal Link open Safari instead of my app?
The most common causes are a file that redirects or fails to load, an app ID with the wrong Team ID, a path that no components entry matches, or a missing applinks entry in the app's Associated Domains entitlement. iOS also opens the browser when a link is typed into the address bar, or when it is tapped on a page from the same domain.
Why does iOS still use my old AASA file?
Since iOS 14, devices download the file from Apple's CDN rather than from your server, and the CDN refreshes on its own schedule, usually within a day. This tool shows whether the CDN copy matches yours. During development, add ?mode=developer to the associated domain to fetch from your server directly.
Does the file need Content-Type application/json?
Apple does not strictly require it, but serving application/json avoids problems with CDNs, proxies and older iOS versions, so it is the safe choice.
What is the difference between paths and components?
paths is the original format: a list of path patterns, with NOT to exclude. components, supported since iOS 13, matches the path, query string and fragment separately and can exclude entries or ignore case. Apple recommends components for new apps.
Still stuck?

More free tools

Skip the hosting work

Ulinkly hosts and serves your apple-app-site-association and assetlinks.json files on your link domain, and gives you deep links that open the app on iOS and Android.

Start free