iOS Universal Links

iOS Universal Links: publish and troubleshoot an AASA file

A website’s AASA file specifies which apps may handle its links. Set up both the website and the signed app, then verify an included and an excluded path on the device.

Content updated: · Maintained by Hung Chi-Hsueh · corrections

Get the identifier from the signed app

On your Mac, run codesign --display --entitlements - --xml YourApp.app on the signed build and find application-identifier in the output. Its first 10 characters are the Application Identifier Prefix, followed by a period and the Bundle ID. The prefix can differ from the Team ID. Copy only these identifiers into the generator.

This tool writes appIDs and components for one app using the format introduced in iOS 13. It generates path rules only. Legacy paths files, query or fragment matches, App Clips and shared web credentials require separate configuration.

Place narrow exceptions first

Apple uses the first matching components entry. In the example, /shop/help/contact matches the exclusion, so it stays on the web. /shop/order/42 matches the second rule and can open the app after the association is verified. Reversing the rules lets the broader /shop/* win. Excluding a path only changes link handling. Enforce access in your app and on your server.

This tool reads * and ? as path wildcards. Use the path alone, leaving out the URL’s query and fragment. Replace $() substitution variables with explicit patterns. For non-ASCII paths, use percent escapes as they appear in the URL, such as /caf%C3%A9/*. Check the actual matched URLs on the device.

Merge, serve, and configure the entitlement

For a first setup, save the file as apple-app-site-association with no extension. For an existing AASA using appIDs and components, review applinks.details. Update an entry dedicated to this app or add an entry for it. If the app shares an entry with other apps, separate this app’s ID before changing its rules. Keep the other IDs with their original components and retest the priority of the resulting entries. Preserve services such as webcredentials and appclips.

If the file uses legacy appID and paths, migrate those rules and verify their behavior before merging. Apple recommends keeping the formats separate.

Serve the reviewed JSON at https://example.com/.well-known/apple-app-site-association using your own hostname. It should return HTTP 200 with application/json over HTTPS with a valid certificate and no redirect. If your entitlement lists example.com and www.example.com explicitly, serve a file on both hosts. In Xcode, add Associated Domains and the matching applinks:example.com entry. Use the hostname without a scheme, path or trailing slash.

Check on a device with the signed app

Try both paths from Notes with the signed app installed. Apple also documents Universal Links Diagnostics in the device’s Developer settings. Typing a URL directly into a browser tests browser navigation. Apple’s CDN and the device can take time to fetch changes, so inspect the live response and the deployed entitlement before changing your rules again.

The generator checks the submitted format and preserves the rule order. Apple verifies the association using the signed app and the deployed website. The generator does not contact either.

Example
{
  "applinks": {
    "details": [{
      "appIDs": ["ABCDE12345.com.example.shop"],
      "components": [
        {"/": "/shop/help/*", "exclude": true},
        {"/": "/shop/*"}
      ]
    }]
  }
}

Data provenance

Sources