Apple Setup

App Clips invocation URLs and the AASA appclips key

App Clips need an apple-app-site-association file with an appclips key plus configured invocation URLs. How the AASA appclips section works and the common mistakes.

By · · 7 min read

An App Clip launches from a URL — a tapped link, an App Clip Code, an NFC tag, a Smart App Banner card, Maps. For any of those to invoke your App Clip, the URL’s domain has to publish an apple-app-site-association (AASA) file with an appclips key, and the URL has to match an invocation you configured in App Store Connect. Miss either and the link just opens Safari with no App Clip.

This is how the AASA appclips section works, how it relates to invocation URLs, and the mistakes that keep App Clips from launching.

For the full submission picture, see every URL and file Apple requires for an iOS App Store submission.

Two things have to line up

App Clip invocation has two halves that must agree:

  1. The AASA file on your domain declares your App Clip’s bundle ID under an appclips key.
  2. The App Store Connect App Clip configuration declares the invocation URLs (the “Advanced App Clip Experiences” / default experience).

If the AASA says one bundle ID and App Store Connect is configured for a different URL pattern, the App Clip won’t invoke. Apple’s reference: App Clips documentation.

The AASA appclips key

It lives in the same apple-app-site-association file as your applinks (Universal Links) section, at https://yourdomain/.well-known/apple-app-site-association:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.yourcompany.app"],
        "components": [{ "/": "/article/*" }]
      }
    ]
  },
  "appclips": {
    "apps": ["ABCDE12345.com.yourcompany.app.Clip"]
  }
}

Key points:

  • appclips.apps is an array of App Clip App IDs in TEAMID.bundleid form. The App Clip bundle ID is typically your app’s bundle ID with a .Clip suffix (whatever you set in Xcode).
  • It is separate from applinks — Universal Links and App Clip invocation are different mechanisms that share the file.
  • The file’s serving rules are the same as any AASA: Content-Type: application/json, HTTPS, no redirect, under 128 KB. See Universal Links AASA without nginx for the hosting gotchas.

Invocation URLs in App Store Connect

The AASA only declares which App Clip the domain is associated with. Which URLs invoke it is configured in App Store Connect:

  • Default App Clip experience — tied to the URL you set; this is what launches from Safari Smart App Banner cards and links by default.
  • Advanced App Clip experiences — additional URL patterns (campaign-specific landing pages, location-based) registered per-experience.

The domain in every configured experience URL must have the AASA appclips association. A campaign URL on a domain whose AASA doesn’t list the Clip bundle ID won’t invoke.

The common mistakes

Teams add the App Clip, ship the AASA with only the applinks section, and wonder why the Clip never launches (Universal Links to the full app work fine). The appclips key is separate and required.

2. Wrong bundle ID suffix

The App Clip target’s bundle ID must be the parent app’s bundle ID plus a suffix (commonly .Clip or .AppClip — whatever Xcode generated). appclips.apps must list that exact ID with the Team ID prefix. A mismatch silently fails.

3. Testing the AASA cache

iOS caches the AASA file (~24h per device) and App Clips additionally go through Apple’s CDN at app-site-association.cdn-apple.com. A freshly-updated AASA may not take effect immediately. For development testing, use the App Clip “Local Experience” in Settings → Developer to bypass the cache, or the _experience debugging flow — don’t assume a just-deployed AASA change is live.

4. The default experience URL domain doesn’t match

If the App Store Connect default experience URL is https://clip.yourdomain.com/... but you only published the AASA at https://yourdomain.com/..., the subdomain has no association. Each domain/subdomain that appears in an invocation URL needs its own AASA with the appclips key.

Smart App Banner → App Clip card

To promote the App Clip from a web page, use the App Clip variant of the Smart App Banner meta tag:

<meta name="apple-itunes-app"
      content="app-id=1234567890, app-clip-bundle-id=com.yourcompany.app.Clip, app-clip-display=card">

Details in Smart App Banner: the meta tag and gotchas.

How OrbitKit handles it

OrbitKit’s AASA generator includes the appclips section — set your App Clip App IDs in the dashboard alongside your Universal Links App IDs and path patterns, and the single hosted apple-app-site-association file at the correct path covers both. The Smart App Banner App Clip card variant is supported from the same dashboard. Start free or see features.