Deep Link Doctor
Home / Developer notes

AASA app ID does not match the app

Universal links fail when the AASA appIDs value does not match your app. How to find the right Team ID prefix and bundle ID, and test the match with swcutil.

SymptomThe AASA file is valid and reachable but universal links still open Safari for every user.
Likely causeThe app ID in the file does not match the app, usually a wrong Team ID prefix, a typo in the bundle ID, or a missing prefix.
FixWrite each app ID as the Application Identifier Prefix, a dot, then the exact bundle ID from Xcode.

Short answer: iOS only uses rules whose app ID matches the installed app exactly. The value must be the Application Identifier Prefix (usually your Team ID), a dot, then the bundle ID, for example ABCDE12345.com.example.app. A bundle ID on its own, or the wrong prefix, matches nothing.

What is happening

AASA app ID: the string in appIDs (or the legacy appID) that tells iOS which app may open the URLs, written as <Application Identifier Prefix>.<Bundle Identifier>.

Apple says "the apps in the apple-app-site-association file on your website must have a matching" Associated Domains entitlement. If the ID in the file is for a different app, or is written in the wrong form, iOS treats the file as having no rules for your app.

  • The file can be perfect in every other way and still fail.
  • The file downloads with a 200, but links still open Safari on a device with the app installed, because the app ID in the file is not your app.

Why does this happen?

The prefix and bundle ID come from different places, and it is easy to copy one wrong. Staging, white-label and renamed apps often have bundle IDs that differ by a suffix.

  • Bundle ID only: com.example.app without the prefix.
  • Wrong prefix: an old Team ID, or another team's ID after an app transfer.
  • Wrong bundle: com.example.app.dev in the file while the release build is com.example.app, or the reverse.
  • Case or typo: bundle IDs are matched exactly.

How to confirm it

  1. In Xcode, open the target's Signing & Capabilities tab and note the bundle identifier and team.
  2. Find your Team ID in your Apple Developer account and check it matches the prefix in the file.
  3. Fetch the file: curl -s https://example.com/.well-known/apple-app-site-association and compare each entry in appIDs.
  4. Compare each appIDs value character by character with your Team ID and bundle ID in Xcode, then check the live file with curl -I https://example.com/.well-known/apple-app-site-association.
  5. On a Mac, run sudo swcutil verify -d example.com -j apple-app-site-association -u https://example.com/your/path. Apple's technote lists a wrong Team ID or bundle ID as a reason this fails to match.

How to fix it

  1. Build the ID as prefix, dot, bundle ID: ABCDE12345.com.example.app.
  2. Add every build that should open links, such as release and internal builds, to the same appIDs array.
  3. Check the app's entitlement lists applinks: for the same domain.
  4. Deploy the file, then reinstall the app so the device fetches the new version.
{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "ABCDE12345.com.example.app",
          "ABCDE12345.com.example.app.beta"
        ],
        "components": [{ "/": "/*" }]
      }
    ]
  }
}

Build the ID as prefix, dot, bundle ID, so the dot and prefix are always in the right place. If the ID is right but some links still fail, see path not matched or the universal links setup guide.

FAQ

Common questions

Is the Application Identifier Prefix the same as the Team ID?

For most apps, yes. Apple's current docs call it the Application Identifier Prefix, while its archived Handoff guide describes the format as `<team identifier>.<bundle identifier>`.

Can one AASA file list several apps?

Yes. Put several IDs in one `appIDs` array, or add separate `details` entries if the apps need different paths. Apple's own example lists two apps in one entry.

Do I need to change the file after transferring the app to another team?

Check it. The prefix in the file must match the app's current Application Identifier Prefix, so compare the two after any transfer and update every app ID that differs.

Why do links work on my debug build but not from TestFlight?

The builds may use different bundle IDs or signing, so only one of them matches the file. List each bundle ID that should open links, and compare against what each build actually uses.

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.