Deep Link Doctor
Home / Developer notes

AASA file has no applinks section

An AASA file without an applinks key gives iOS no universal link rules. Why it happens when only webcredentials is set, and how to add applinks correctly.

SymptomPassword autofill or App Clips work for the domain but universal links never open the app.
Likely causeThe apple-app-site-association file only has webcredentials or appclips keys and no applinks key.
FixAdd an applinks object with a details array listing your app IDs and the URL patterns to open.

Short answer: The same apple-app-site-association file serves several Apple services. If it has webcredentials or appclips but no applinks key, password autofill may work while universal links never do. Add an applinks section with your app IDs and paths.

What is happening

Missing applinks: an apple-app-site-association file with no applinks key, so iOS has no universal link rules for the domain even if other services in the file work.

Apple's Associated Domains entitlement supports four services: applinks, webcredentials, activitycontinuation (Handoff) and appclips. Each one reads its own key from the same file. A file built for one service does nothing for the others.

  • Shared web credentials can work while links fail, which looks contradictory.
  • The file downloads with curl -I https://example.com/.well-known/apple-app-site-association, but sudo swcutil verify never prints Pattern "..." matched., even if webcredentials or appclips is present.

Why does this happen?

The file was usually created for a different feature first, often password autofill, and universal links were added to the app later without updating the file. Sometimes the entitlement has applinks:example.com but the file was never extended to match.

  • Built for autofill: only webcredentials exists.
  • Built for App Clips: only appclips exists.
  • Typo: appLinks or app_links instead of applinks.

How to confirm it

  1. Fetch the file: curl -s https://example.com/.well-known/apple-app-site-association.
  2. Look for a top-level applinks key, spelled exactly in lower case.
  3. Check the app's entitlement in Xcode under Signing & Capabilities > Associated Domains. It should list applinks:example.com.
  4. Run sudo swcutil verify on a Mac against a real URL.

How to fix it

  1. Add a top-level applinks object next to the existing keys.
  2. Inside it, add a details array with one entry per set of apps.
  3. List your app IDs in appIDs, in the form <Application Identifier Prefix>.<Bundle Identifier>.
  4. List the URL patterns in components, with exclusions first.
  5. Make sure the entitlement includes applinks: for every domain that should open the app. Apple says not to include a path, query or trailing slash.
  6. Deploy the file and reinstall the app on a test device.
{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [{ "/": "/*" }]
      }
    ]
  },
  "webcredentials": { "apps": ["ABCDE12345.com.example.app"] }
}

Write both sections from your Team ID and bundle ID, as shown in the universal links setup guide. Once applinks is in place, check the app ID format next, and see the universal links setup guide for the app side.

FAQ

Common questions

Can one file serve universal links and password autofill?

Yes. The `applinks`, `webcredentials` and `appclips` keys sit side by side in the same file, and each service reads only its own key.

Do I need the webcredentials key for universal links?

No. Universal links only read `applinks`. Add `webcredentials` only if you also want shared web credentials for password autofill.

Does the entitlement need applinks too?

Yes. Apple says the apps in the file must have a matching Associated Domains entitlement, so the app needs `applinks:example.com` as well as the file needing an `applinks` key.

Will a rule of /* open every page in the app?

It claims every path on that domain, so links to pages the app cannot show will also open the app. Add `exclude` rules for those paths above the catch-all rule.

What are UTM parameters?

UTM parameters are tags added to the end of a link, such as utm_source and utm_campaign, that tell analytics tools where a visit came from. They let you see which campaign, channel and ad brought each visitor.

Which UTM parameters are required?

Use utm_source, utm_medium and utm_campaign on every campaign link. utm_term and utm_content are optional and help you compare keywords or ad variants.