Deep Link Doctor
Home / Developer notes

AASA entry has no paths or components

An AASA details entry with no components or paths claims no URLs, so universal links never open the app. How to add rules that match the URLs you need.

SymptomThe app ID is correct but no URL on the domain ever opens the app.
Likely causeThe details entry has an empty or missing components or paths array, so it claims no URLs.
FixAdd components rules for the URLs the app should open, with exclusions listed first.

Short answer: Each details entry needs URL patterns. Without a components array (or the legacy paths array), or with an empty one, the entry claims no URLs and every link opens the browser. Add at least one rule, such as { "/": "/product/*" }.

What is happening

AASA components: the array of pattern dictionaries in a details entry that tells iOS which URLs open the app, matching on path (/), query (?) and fragment (#).

An entry with app IDs but no patterns is valid JSON and has the right app, but it applies to nothing. Apple's components reference describes each pattern key and its default, and a URL must match "all the components that a components object specifies".

  • sudo swcutil verify on a Mac never prints Pattern "..." matched. for any URL you test.
  • An empty paths array in the legacy format has the same effect.

Why does this happen?

The rules are often left out while the file is set up "for later", or removed when someone tries to stop links opening the app. Templates that use placeholder arrays also cause it.

  • Placeholder file: "components": [] left from a template.
  • Deliberate removal: emptying the rules to pause universal links, then forgetting to restore them.
  • Wrong key: component or path instead of components or paths.

How to confirm it

  1. Fetch the file: curl -s https://example.com/.well-known/apple-app-site-association.
  2. Check every details entry has a non-empty components array (or paths in the legacy format).
  3. On a Mac, test a real URL with sudo swcutil verify -d example.com -j apple-app-site-association -u https://example.com/product/1 and look for Pattern "..." matched.

How to fix it

  1. List the URL groups the app can show, for example product pages and user profiles.
  2. Write one components rule per group, using * for any run of characters.
  3. Add exclude rules for pages that must stay on the web, above the broader rules. Apple says "the first match wins".
  4. Use components only, without a paths key in the same entry.
  5. Deploy the file and reinstall the app on a test device.
{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [
          { "/": "/account/billing", "exclude": true },
          { "/": "/product/*" },
          { "/": "/u/*" }
        ]
      }
    ]
  }
}

Each key in a rule has a default of * for /, ? and #, so a rule with only / matches any query and fragment. The universal links setup guide shows a working file, and path not matched covers rules that exist but miss some URLs.

FAQ

Common questions

What is the simplest rule to open every URL?

`{ "/": "/*" }` claims every path on the domain. Add exclusions above it for pages the app cannot show, such as checkout or help pages.

Can I use paths instead of components?

The legacy `paths` array is still described in Apple's technote, with `NOT` as a prefix for exclusions. Apple warns against mixing it with `components` in the same file.

Does an empty components array stop links for one app only?

Only for the app IDs in that entry. Other entries in `details` keep their own rules, so a second app can still open links.

Is there a quick way to pause universal links without breaking the file?

Replace the rules with a single exclude-all rule, such as `{ "/": "*", "exclude": true }`, rather than deleting the array. Remember that devices only pick up the change when they next fetch the file.

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.