Deep Link Doctor
Home / Developer notes

Some URLs open the app and others do not

Some universal links open the app and others open Safari. Learn how AASA components matching works, why the first match wins and how to test a URL with swcutil.

SymptomSome universal links open the app while others on the same domain open Safari.
Likely causeThe URL is not covered by any components rule, an earlier exclude rule wins, or the case does not match.
FixReorder rules so exclusions come first, widen the pattern, or set caseSensitive to false where needed.

Short answer: iOS checks components rules in order and stops at the first match. If an exclude rule above your path matches first, or no rule covers the URL, or the case differs, that link opens Safari. Test the exact URL with sudo swcutil verify on a Mac.

What is happening

Path matching: the process in which iOS compares a tapped URL against the components rules in order and uses the first rule that matches, opening the app unless that rule has exclude: true.

Apple's components reference says: "The order that you use to specify the patterns in the array determines the order the system follows when looking for a match. The first match wins." So rule order matters as much as rule content.

  • A URL must match every key a rule specifies. Apple's example {"/":"abc","?":"def","#":"*"} matches /abc?def but not /abc on its own.
  • Matching is case-sensitive by default (caseSensitive defaults to true).
  • percentEncoded also defaults to true, so keep that in mind for URLs with encoded characters.

Why does this happen?

Usually a broad rule sits above a narrow one, or a rule requires a query that real links do not carry. Mixed-case URLs from marketing tools are another common source.

  • Order: { "/": "/*", "exclude": true } at the top blocks everything below it.
  • Too narrow: /product/* does not match /products/1.
  • Query required: a rule with "?": { "id": "?*" } fails for URLs without id.
  • Case: /Promo/summer does not match /promo/* unless case sensitivity is off.

How to confirm it

  1. On a Mac, run sudo swcutil verify -d example.com -j apple-app-site-association -u <failing URL>. It prints Pattern "..." matched. or blocked match., so you can see whether a rule claims the URL.
  2. On a device with Developer Mode on, open Settings > Developer > Universal Links > Diagnostics and enter the URL.
  3. Paste the link into Notes and long-press it. If the menu offers to open the app, the rule matches.

How to fix it

  1. Move every exclude rule above the broader rules it carves out.
  2. Widen patterns that are too specific, using * for any run of characters and ?* for at least one character.
  3. Remove query or fragment requirements that real links do not always include.
  4. For mixed-case URLs, add "caseSensitive": false to the rule, or set it in defaults.
  5. Deploy and reinstall the app on the test device, then retest each URL.
{
  "applinks": {
    "defaults": { "caseSensitive": false },
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [
          { "/": "/product/*/print", "exclude": true },
          { "/": "/product*/*" },
          { "/": "/promo/*" }
        ]
      }
    ]
  }
}

If only links typed into Safari fail, the file is fine; see typed links open Safari. List exclusions first when you write rules.

FAQ

Common questions

Does iOS use the most specific rule?

No. It uses the first rule in the array that matches, regardless of how specific later rules are. Put narrow exclusions above broad includes.

Do query strings affect matching?

Only if a rule sets the `?` key. The default for `?` is `*`, so a rule with just a path matches that path with or without a query.

How do I match one or more characters but not zero?

Use `?*`. Apple defines `*` as zero or more characters, `?` as exactly one, and `?*` as one or more.

Why does the same URL work on one device and not another?

The devices may hold different versions of the file, since they check for updates roughly once a week. A user may also have chosen to open the domain in the browser, which changes that device's default.

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.