dpearson2699/swift-ios-skills / skills/app-clips
app-clips
VerifiedBuild 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.3 KB |
| evals/evals.json | config | 5.6 KB |
| references/data-handoff-notifications-location.md | markdown | 6.1 KB |
| references/routing-and-experiences.md | markdown | 5.2 KB |
| references/size-capabilities-and-promotion.md | markdown | 8.9 KB |
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |