Skip to content

dpearson2699/swift-ios-skills / skills/app-clips

app-clips

Verified

Build iOS App Clips with invocation URLs, App Clip Codes, NFC, QR codes, Safari banners, Maps, Messages, target setup, App Store Connect experiences, size/capability constraints, NSUserActivity routing, SKOverlay promotion, App Group/keychain handoff, ephemeral notifications, location confirmation, and full-app migration. Use when creating App Clips or wiring App Clip invocation, experience configuration, or full-app handoff.

references/routing-and-experiences.md

View on GitHub
# 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](#invocation-url-handling)
- [App Clip Experience Configuration](#app-clip-experience-configuration)
- [Invocation Methods](#invocation-methods)
- [Safari Smart App Banner](#safari-smart-app-banner)
- [Local Testing](#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

```swift
@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:

```text
appclips:example.com
```

## Invocation Methods

| Method | Requirements |
|---|---|
| **App Clip Codes** | Advanced experience for production; short demo App Clip link for demo codes; NFC-integrated or scan-only |
| **NFC tags** | Encode invocation URL in an NDEF payload; physical trigger for size-policy decisions |
| **QR codes** | Encode invocation URL; physical trigger for size-policy decisions |
| **Safari Smart App Banners** | Associate the App Clip with the website and add the banner meta tag |
| **Maps** | Advanced experience with place association |
| **Messages** | Share invocation URL as text; demo links have limited preview behavior |
| **Siri Suggestions** | Location-based; requires advanced experience for location suggestions |
| **Other apps with Link Presentation** | Can surface App Clip experiences through rich link metadata |
| **Other apps using SwiftUI `Link` / `UIApplication.open(_:)`** | Open default, associated-website, or demo-link URLs; advanced App Clip experiences are not supported for this launch path |

## Safari Smart App Banner

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

```html
<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:

```swift
// 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.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall