App Clips Lightweight, instantly-available versions of your iOS app for in-the-moment experiences or demos. Targets iOS 26+ / Swift 6.2 unless noted. Contents App Clip Target Setup Invocation URL Handling App Clip Experience Configuration Size Limits Invocation Methods Data Migration to Full App SKOverlay for Full App Promotion Location Confirmation Lifecycle and Ephemeral Nature Capabilities and Limitations Common Mistakes Review Checklist References App Clip Target Setup An App Clip is a separate target in the same Xcode project as your full app: File → New → Target → App Clip — Xcode creates the target with the com.apple.developer.on-demand-install-capable entitlement and a Parent Application Identifiers entitlement linking back to the full app. The App Clip bundle ID must be a suffix of the full app's: com.example.MyApp.Clip . Xcode adds an Embed App Clip build phase to the full app target automatically. Share code between targets Use Swift packages or shared source files. Add files to both targets, or use the APPCLIP active compilation condition: // In App Clip target Build Settings → Active Compilation Conditions: APPCLIP
if
! APPCLIP // Full-app-only code (e.g., background tasks, App Intents)
else
// App Clip specific code
endif
Prefer local Swift packages for shared modules — add the package as a dependency of both targets.
Shared asset catalogs
Create a shared asset catalog included in both targets to avoid duplicating images and colors.
Invocation URL Handling
App Clips receive an
NSUserActivity
of type
NSUserActivityTypeBrowsingWeb
on launch. Handle it with
onContinueUserActivity
:
@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
}
// Extract path/query to determine context
let
locationID
=
components
.
queryItems
?
.
first
(
where
:
{
$0
.
name
==
"location"
}
)
?
.
value
// Update UI for this location
}
}
For UIKit scene-based apps, implement
scene(:willConnectTo:options:)
for cold launch and
scene(:continue:)
for warm launch.
Key rule:
The full app
must
handle all invocation URLs identically — when a user installs the full app, it replaces the App Clip and receives all 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)
Provide: header image, subtitle (≤56 chars), call-to-action verb
App Store Connect generates a
default App Clip link
:
https://appclip.apple.com/id?=
Data Migration to Full App When a user installs the full app, it replaces the App Clip. Use a shared App Group container to migrate data: // In both targets: add App Groups capability with the same group ID // App Clip — write data func saveOrderHistory ( _ orders : [ Order ] ) throws { guard let containerURL = FileManager . default . containerURL ( forSecurityApplicationGroupIdentifier : "group.com.example.myapp.shared" ) else { return } let data = try JSONEncoder ( ) . encode ( orders ) let fileURL = containerURL . appendingPathComponent ( "orders.json" ) try data . write ( to : fileURL ) } // Full app — read migrated data func loadMigratedOrders ( ) throws -> [ Order ] { guard let containerURL = FileManager . default . containerURL ( forSecurityApplicationGroupIdentifier : "group.com.example.myapp.shared" ) else { return [ ] } let fileURL = containerURL . appendingPathComponent ( "orders.json" ) guard FileManager . default . fileExists ( atPath : fileURL . path ) else { return [ ] } let data = try Data ( contentsOf : fileURL ) return try JSONDecoder ( ) . decode ( [ Order ] . self , from : data ) } Shared UserDefaults // Write (App Clip) let shared = UserDefaults ( suiteName : "group.com.example.myapp.shared" ) shared ? . set ( userToken , forKey : "authToken" ) // Read (Full app) let shared = UserDefaults ( suiteName : "group.com.example.myapp.shared" ) let token = shared ? . string ( forKey : "authToken" ) Keychain sharing Starting iOS 15.4, App Clip keychain items are accessible to the corresponding full app via the parent-application-identifiers and associated-appclip-app-identifiers entitlements. Use distinct kSecAttrLabel values to distinguish App Clip vs. full app entries. Sign in with Apple Store the ASAuthorizationAppleIDCredential.user in the shared container so the full app can silently verify without re-prompting login. SKOverlay for Full App Promotion Display an overlay recommending the full app from within the App Clip: SwiftUI struct OrderCompleteView : View { @State private var showOverlay = false var body : some View { VStack { Text ( "Order placed!" ) Button ( "Get the full app" ) { showOverlay = true } } . appStoreOverlay ( isPresented : $showOverlay ) { SKOverlay . AppClipConfiguration ( position : . bottom ) } } } UIKit func displayOverlay ( ) { guard let scene = view . window ? . windowScene else { return } let config = SKOverlay . AppClipConfiguration ( position : . bottom ) let overlay = SKOverlay ( configuration : config ) overlay . delegate = self overlay . present ( in : scene ) } SKOverlay.AppClipConfiguration automatically resolves to the parent app. Available iOS 14.0+. Never block the user's task to force installation — show the overlay after task completion. Location Confirmation Use APActivationPayload to verify a user's physical location without requesting full location access: import AppClip import CoreLocation func verifyLocation ( from activity : NSUserActivity ) { guard let payload = activity . appClipActivationPayload , let url = activity . webpageURL else { return } // Build the expected region (up to 500m radius) let center = CLLocationCoordinate2D ( latitude : 37.334722 , longitude : - 122.008889 ) let region = CLCircularRegion ( center : center , radius : 100 , identifier : "store-42" ) payload . confirmAcquired ( in : region ) { inRegion , error in if let error = error as ? APActivationPayloadError { switch error . code { case . doesNotMatch : // URL doesn't match registered App Clip URL break case . disallowed : // User denied location, or invocation wasn't NFC/visual code break @unknown default : break } return } if inRegion { // Confirmed — user is at the expected location } else { // User is not at expected location (e.g., NFC tag was moved) } } } Enable location confirmation in Info.plist : < key
NSAppClip </ key
< dict
< key
NSAppClipRequestLocationConfirmation </ key
< true /> </ dict
This is lightweight — the system verifies location without granting your App Clip continuous access. The App Clip card shows a note that the clip can verify location. Available iOS 14.0+. Lifecycle and Ephemeral Nature No Home Screen icon — App Clips appear in the App Library and recent apps Automatic removal — the system deletes the App Clip and its data after a period of inactivity (typically ~30 days, system-determined) No persistent state guarantee — treat App Clip storage as ephemeral; migrate important data to the shared container or a server Relaunching — returning to a previously launched App Clip from the App Library uses the last invocation URL; returning from the App Switcher launches without an invocation URL (restore saved state) Notifications — App Clips can request ephemeral notification permission (up to 8 hours) via Info.plist ; set NSAppClipRequestEphemeralUserNotification to true Location access — requestWhenInUseAuthorization() only; resets daily at 4:00 AM Capabilities and Limitations Available to App Clips SwiftUI, UIKit, Core Location (when-in-use), Sign in with Apple, Apple Pay, CloudKit (public database read-only, iOS 16+), Background Assets, StoreKit ( SKOverlay ), Keychain, App Groups, Push Notifications (ephemeral), Live Activities (iOS 16.1+) Not available / no-op at runtime App Intents, Background Tasks, CallKit, Contacts, CoreMotion, EventKit, HealthKit, HomeKit, MediaPlayer, Messages, NearbyInteraction, PhotoKit, SensorKit, Speech, SKAdNetwork, App Tracking Transparency Additional restrictions No background URL sessions No background Bluetooth No multiple scenes on iPad No on-demand resources No custom URL schemes No in-app purchases (reserve for full app) UIDevice.name and identifierForVendor return empty strings Common Mistakes Exceeding App Clip size limit // ❌ DON'T: Include large frameworks or bundled assets // Importing heavyweight frameworks like RealityKit or large ML models // pushes the App Clip well over 10–15 MB. // ✅ DO: Use Asset Catalog thinning, exclude unused architectures, // strip debug symbols, and split shared code into lean Swift packages. // Measure with App Thinning Size Report after every change. Not testing invocation URLs locally // ❌ DON'T: Only test App Clip with a direct Xcode launch // This skips invocation URL handling and misses bugs. // ✅ DO: Use the _XCAppClipURL environment variable in the scheme, // or register a Local Experience in Settings → Developer → Local Experiences // to test with realistic invocation URLs and App Clip cards. Not handling the full app replacing the App Clip // ❌ DON'T: Assume only the App Clip receives invocations // When the user installs the full app, ALL invocations go to it. // ✅ DO: Share invocation-handling code between both targets. // The full app must handle every invocation URL the App Clip supports.
if
! APPCLIP // Full app can additionally show richer features for the same URL
endif
Storing critical data only in App Clip storage // ❌ DON'T: Store important data in the App Clip's sandboxed container let fileURL = documentsDirectory . appendingPathComponent ( "userData.json" ) // This data is DELETED when the system removes the App Clip. // ✅ DO: Write to the shared App Group container or sync to a server guard let shared = FileManager . default . containerURL ( forSecurityApplicationGroupIdentifier : "group.com.example.shared" ) else { return } let fileURL = shared . appendingPathComponent ( "userData.json" ) Missing associated domains configuration // ❌ DON'T: Configure App Clip experiences in App Store Connect // without setting up associated domains and the AASA file. // Invocations from your website and advanced experiences will fail. // ✅ DO: Add the Associated Domains entitlement with: // appclips:example.com // AND host /.well-known/apple-app-site-association on your server: // { // "appclips": { // "apps": ["TEAMID.com.example.MyApp.Clip"] // } // } Review Checklist App Clip target bundle ID is a suffix of the full app's bundle ID Parent Application Identifiers entitlement is set correctly Shared code uses Swift packages or compilation conditions ( APPCLIP ) onContinueUserActivity(NSUserActivityTypeBrowsingWeb) handles invocation URLs Full app handles all invocation URLs the App Clip supports App Thinning Size Report confirms binary is within size limits for target iOS Associated Domains entitlement includes appclips:yourdomain.com (if using custom URLs) AASA file hosted at /.well-known/apple-app-site-association (if using custom URLs) Default App Clip experience configured in App Store Connect Shared App Group container used for data the full app needs SKOverlay / appStoreOverlay shown after task completion, never blocking NSAppClipRequestLocationConfirmation set in Info.plist if using location verification No reliance on background processing, restricted frameworks, or persistent local storage Tested with Local Experiences (Settings → Developer) and _XCAppClipURL env var Handles launch without invocation URL (App Switcher / notification re-entry) References App Clips framework Creating an App Clip with Xcode Configuring App Clip experiences Responding to invocations Choosing the right functionality Confirming a person's physical location Sharing data between App Clip and full app Recommending your app to App Clip users APActivationPayload SKOverlay.AppClipConfiguration NSUserActivityTypeBrowsingWeb Creating App Clip Codes Distributing your App Clip App Clips HIG