Appy

Deep linking

What is Associated Domains?

Short answer

Associated Domains is an Apple capability and entitlement that lists the web domains an app is connected to. Each entry pairs a service with a domain, such as applinks:example.com. Together with the apple-app-site-association file on that domain, it enables Universal Links, shared web credentials, Handoff and App Clips.

What the entitlement contains

The entitlement is a list of strings in the form service:domain. Apple defines four services. applinks is for Universal Links. webcredentials lets the app use passwords saved for the website. activitycontinuation is for Handoff. appclips ties an App Clip to a domain.

The domain is written bare: no https://, no path, no trailing slash, and according to Apple’s technote no port number either. Each subdomain is its own entry. For every service except appclips, a prefix of *. matches all subdomains, as in applinks:*.example.com.

How it pairs with the file on the domain

The entitlement is one half of a two-way check. The app claims a domain, and the domain confirms the claim by listing the app’s ID in its apple-app-site-association (AASA) file. If either half is missing, the service stays off and iOS reports nothing to the user.

When the app is installed, the system downloads the file for each listed domain. Since iOS 14 that request goes to an Apple-managed CDN instead of your server. Apple’s documentation says the CDN requests the file within 24 hours and devices check for updates about once a week.

Setting it up and testing it

In Xcode, open the target’s Signing & Capabilities tab, add the Associated Domains capability and enter one line per domain. This also switches the feature on for the App ID. An App Clip needs the same entry on both the app target and the App Clip target.

For a server that isn’t reachable from the public internet, add ?mode=developer to the entry. Devices in developer mode then fetch the file directly, and only builds signed with a development profile can use it. A second mode, managed, serves devices enrolled in mobile device management. Remove the suffix before you ship: a release build should go through the CDN like everyone else’s phone does. Apple’s technote also describes a quick check on the device: with Associated Domains Development switched on in the Developer settings, a Diagnostics screen tells you whether a given address is valid for an installed app.

ExampleEntitlement entries
applinks:example.com, webcredentials:example.com

Try it here

Generate the file for your app

Enter your Team ID and bundle ID, or your package name and signing fingerprint. You get an apple-app-site-association or assetlinks.json file ready to put on your server.

Apps

Add every app that should open links on this domain. Each one becomes an entry in appIDs.

  1. App 1

    10 characters, in your Apple Developer account under Membership details.

    From your app target in Xcode, for example com.example.app.

Paths that open the app

Rules are checked from top to bottom and the first match wins, so put exclusions above broader rules. * matches any characters, ? exactly one.

  1. Rule 1

    name=value pairs joined by &

Other services

Your file

apple-app-site-association

Example. Fill in your details to replace it.

{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "ABCDE12345.com.example.app"
        ],
        "components": [
          {
            "/": "/*"
          }
        ]
      }
    ]
  }
}

Generated in your browser. Nothing is sent anywhere.

Where to host it

Where the file goes

  1. Upload it to https://your-domain/.well-known/apple-app-site-association, without a .json extension.
  2. Serve it over HTTPS with a valid certificate and a direct 200, with no redirects.
  3. Send the header Content-Type: application/json.
  4. Repeat on every host in your links: example.com and www.example.com each need the file and an applinks: entry.
  5. Apple’s CDN fetches a new file within 24 hours. Test with ?mode=developer in the meantime.
Check a domain with the validator

Rather not host files yourself? Smart links are free, and on Enterprise Appy serves both files on your app’s link domain.

Create a free link
Read moreComplete Guide to Universal Links for iOS and AndroidWhere the Associated Domains entry fits in a full Universal Links and App Links setup, step by step.

Frequently asked questions

What is the difference between Associated Domains and Universal Links?

Associated Domains is the mechanism. Universal Links are one feature built on it. The entitlement can also enable shared web credentials, Handoff and App Clips. For Universal Links specifically, you add an applinks: entry and list the app under applinks in the file on your domain.

Can I use a wildcard in Associated Domains?

Yes. Prefix the domain with *. to match all of its subdomains, for example applinks:*.example.com, and host the file on the root domain. The wildcard is not allowed for the appclips service, and it doesn’t cover the root domain itself, which needs its own entry.

Why isn’t my Associated Domains entry working?

Check the three usual suspects. The entry includes a scheme, path or port. The domain in the entry and the host serving the file differ, for example example.com against www.example.com. Or the file redirects or is blocked, so Apple’s CDN never gets a copy.

  • Universal Links

    Universal Links are Apple’s https links that open an installed iOS app directly instead of the website, available since iOS 9. They need the Associated Domains entitlement in the app, such as applinks:example.com, and an apple-app-site-association file on the domain. Without the app, the same link simply opens the website.

  • apple-app-site-association (AASA)

    The apple-app-site-association (AASA) file is a JSON file on your domain that tells iOS which apps may open which links there. It lives at /.well-known/apple-app-site-association, must be served over HTTPS without redirects, and lists each app by its Team ID and bundle ID together with the paths it handles.

  • App Clip

    An App Clip is a lightweight version of an iOS app that people can use without installing the full app. It launches from an invocation such as an App Clip Code, QR code, NFC tag, a link in Messages or a banner in Safari, does one focused task, and can then offer the full app.

All glossary terms

One link for every phone

Create a free smart link and QR code that sends iPhones to the App Store, Android phones to Google Play and desktops to your website.