App Clip Routing and Experiences

Use this when implementing invocation URL routing, App Store Connect experiences, Local Experiences, Safari Smart App Banners, QR/NFC/App Clip Codes, AASA, or associated domains.

Contents

• Invocation URL Handling
• App Clip Experience Configuration
• Invocation Methods
• Safari Smart App Banner
• Local Testing

Invocation URL Handling

App Clips receive an NSUserActivity of type NSUserActivityTypeBrowsingWeb. Route from the invocation URL and keep the same router available to the full app.

SwiftUI

@main
struct DonutShopClip: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
                    handleInvocation(activity)
                }
        }
    }

    private func handleInvocation(_ activity: NSUserActivity) {
        guard let url = activity.webpageURL,
              let components = URLComponents(url: url, resolvingAgainstBaseURL: true)
        else { return }

        let locationID = components.queryItems?
            .first(where: { $0.name == "location" })?.value

        routeToLocation(id: locationID)
    }
}

UIKit scenes

For UIKit scene-based apps, distinguish notification from handling:

• Cold launch: inspect connectionOptions.userActivities in scene(_:willConnectTo:options:).
• Continued activity: handle the actual NSUserActivity in scene(_:continue:).
• Relaunch warning: scene(_:willContinueUserActivityWithType:) can tell you a continuation is coming, but it does not provide the activity or URL.

Key rule: The full app must handle every invocation URL the App Clip supports. After a user installs the full app, it replaces the App Clip and receives future invocations.

App Clip Experience Configuration

Configure experiences in App Store Connect after uploading a build containing the App Clip.

Default App Clip experience

• Required for every App Clip.
• Provide: header image, subtitle, and call-to-action verb.
• App Store Connect generates a default App Clip link with an appclip.apple.com URL.
• Supports web and shared-link invocation; QR and NFC can encode links, but count as physical triggers for size-policy decisions.

Demo App Clip link

• Auto-generated by App Store Connect for demo versions of your app.
• Supports NFC tags and QR codes for testing physical invocations.
• App Clip Codes require the short version of the demo App Clip link.
• Does not replace Maps, Smart App Banners, or website App Clip cards.
• Can use the larger current App Clip binary limit.
• Cannot contain URL parameters.

Advanced App Clip experiences

• Required for: Maps integration, location association, per-location card imagery, and precise physical-place routing.
• Normal production path for App Clip Codes; demo App Clip Codes require the short demo link.
• Each experience has its own invocation URL, header image, and metadata.
• URL prefix matching lets one registered URL cover many sub-paths.
• Use the App Store Connect API to manage large numbers of experiences programmatically.

Associated domains

For custom URLs, add entries to the Associated Domains entitlement on both the full app and App Clip targets, and host an AASA file:

appclips:example.com

Invocation Methods

Safari Smart App Banner

Add this meta tag to your website to show the App Clip banner:

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

Use app-clip-display=card when the webpage should display the App Clip card in Safari or SFSafariViewController on iOS 15+. Do not rely on app-argument for App Clips; Apple documents app-argument for full-app Smart App Banners, not App Clip launches.

Local Testing

Test the invocation path, not just direct Xcode launch:

// Use the _XCAppClipURL environment variable in the scheme,
// or register a Local Experience in Settings → Developer → Local Experiences.

A direct Xcode launch can skip the invocation path and hide routing bugs.