01 · Get the file

Run this and paste the whole output, headers included, in step 02:


            
    02 · Paste the file or the curl -i output
    03 · Checks

    Paste a file above to see the checks.

    04 · Test URLs

    One URL per line. Start a line with + if it should open the app, or - if it should stay in the browser, and the result is marked as expected or not.

      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.com reads the file from example.com.
      • App IDs are TEAMID.bundle.id, for example ABCDE12345.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=developer to the entitlement, for example applinks: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.
      • caseSensitive and percentEncoded default to true. You can change them in applinks.defaults (whole domain), in a details entry's defaults (that entry), or on a single component. The most specific one wins.
      • Substitution variables such as $(lang), $(region), $(digit) or your own names from substitutionVariables are 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 appID plus paths format is still read. A path starting with NOT excludes. 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 as application/json, over HTTPS even if your intent filters declare only http, with no 301 or 302 redirect.
      • Each host in your intent filters needs its own file. A redirect from example.com to www.example.com fails verification for example.com.
      • The file is a JSON array of statements. A statement verifies App Links when its relation array contains delegate_permission/common.handle_all_urls and its target has namespace android_app, the package_name (your applicationId) and sha256_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.

      Last updated · November 2026

      Copied