What the iOS Universal Link Builder does
This builder generates the apple-app-site-association (AASA) file and the Associated Domains entitlement for iOS Universal Links from your Team ID, bundle IDs, domains and link rules. It writes the modern components format with exclusions, query and fragment matching, optional webcredentials and App Clip sections, and a hosting checklist, and it lets you test any URL against the rules before you ship.
Universal Links need two halves that agree: the entitlement inside the app lists the domains, and each domain serves a JSON file listing the app. Most failures come from the file - a wrong Team ID prefix, a redirect, or an exclusion placed after a rule that already matched.
How to use it
- Enter your 10-character Team ID and one or more bundle IDs. The app IDs in the file are the two joined with a dot.
- List the domains your links use, one per line.
- Write the rules in order, one per line: include or exclude, a path pattern, and optionally ?query and #fragment. Put exclusions before the broader rules they carve out of.
- Choose webcredentials for Password AutoFill, an App Clip bundle ID if you have one, and developer mode while testing.
- Test a few URLs, then copy or download the file and the entitlement and follow the hosting checklist.
Reading the results
The URL tester applies Apple's matching: rules are checked from the top, the first match decides, and an excluded match keeps the link in Safari. A URL that matches nothing also stays in the browser.
In patterns, * matches any run of characters, including none, and ? matches exactly one, so ?* means at least one. A query rule written as q=?* requires a q parameter with a non-empty value; other parameters are ignored.
Findings flag rule-order mistakes, invalid IDs and missing domains. Notes explain choices such as the legacy paths section, which only iOS 12 and earlier read.
Worked example: a shop that keeps account pages on the web
The shop example uses Team ID ABCDE12345, bundle ID com.example.shop and the domains example.com and www.example.com. The rules exclude /account/* and /help/*, then include /products/*, /search when it has a non-empty q parameter, and /o/*/track.
The generated file has one applinks detail with the app ID ABCDE12345.com.example.shop and five components in that order, plus a webcredentials section for the same app ID. The entitlement lists applinks: and webcredentials: entries for both domains.
Testing https://www.example.com/search?q=boots opens the app through the fourth rule. https://example.com/search without a query, and https://example.com/account/orders, stay in the browser.
Why order matters in components
Apple evaluates the components array from top to bottom and stops at the first component that matches. An include rule of * followed by exclude /account/* therefore opens the account pages in the app anyway, because * matched first. The builder flags an exclusion that can never be reached.
The same logic applies to the legacy paths array, where exclusions are written as NOT /path. The builder can write both, since iOS 13 and later read components and ignore the older section.
Limitations: what the result does not prove
- It writes the file and checks its logic; it cannot see your server. Once hosted, check it with the Apple App Site Association Validator.
- Apple's CDN caches the file, so a corrected file may take time to reach devices. Developer mode, on a device with Associated Domains Development enabled, fetches it directly.
- Percent-encoding and case options follow Apple's documented defaults (case-sensitive, percent-encoded); the builder does not set per-rule overrides.
Privacy: where your data goes
Everything you paste, type or drop is processed in this browser tab. It is not uploaded, logged, stored or sent to analytics. Session recording and tag-manager scripts are switched off on this page.
Standards and sources
- Apple Developer - Supporting associated domains - checked 19 Sep 2026
- Apple Developer - applinks (components, exclude, query and fragment keys)
- Apple Developer - Associated Domains entitlement
Frequently asked questions
Where do I host the apple-app-site-association file?
At https://your-domain/.well-known/apple-app-site-association, with no .json extension, served over HTTPS with a valid certificate, a 200 response, no redirects and the application/json content type. Each domain and subdomain in the entitlement needs its own copy.
What is the app ID in an AASA file?
It is your Team ID, a dot and the bundle ID, such as ABCDE12345.com.example.app. The Team ID is on the Membership page of your Apple Developer account. A wrong prefix is one of the most common reasons links do not open the app.
How do I stop some URLs opening my app?
Add a component with exclude set to true, before any broader rule that would otherwise match. For example, exclude /account/* first, then include /*. Rules are checked in order and the first match wins.
Can Universal Links match query parameters?
Yes, since iOS 13. A component's ? key can be a pattern for the whole query, or a dictionary of parameter names and value patterns that must all match. Parameters not named in the dictionary are ignored.
What does ?mode=developer do in the entitlement?
It makes a development device fetch the file directly from your server instead of Apple's CDN, so you see changes immediately. It needs Associated Domains Development turned on in the device's developer settings, and is ignored in App Store builds.
Do I still need the paths array?
Only to support iOS 12 and earlier. iOS 13 and later read appIDs and components. The builder can add a legacy entry with paths and NOT exclusions if you tick the option.
Last reviewed by the A2Z.Tools team against the sources listed above.
