English · Türkçe · 简体中文 · 日本語 · 한국어 · Español · Deutsch · Français · Português (Brasil) · Русский
A Swift package for iOS App Clips and the apps they belong to. It validates the invocation URL
the system passes at launch and routes it to your screens the way App Store Connect routes it to
App Clip experiences, confirms the person is where the code is, and hands the App Clip's data to
the full app. Its appclipstudio command-line tool checks what App Store Connect and the system
will check before you upload: each variant's size, App Clip Code URLs, the
apple-app-site-association file and Associated Domains entries. The package has no
dependencies.
- Invocation routing with Apple's matching rule — patterns such as
/table/:numberand/shop/*; the most specific prefix wins, as in App Store Connect, and a fallback covers the rest of a registered prefix, which Apple requires an App Clip and its full app to handle. Default App Clip links (https://appclip.apple.com/id?p=…) are recognized. - Untrusted input stays bounded — invocation URLs are checked for scheme, host, length,
path and query size, and
./..components before your code sees them; numbers parse without trapping; size reports rejectnan,infand1e999; files are read with a limit; the folder scan doesn't follow symbolic links; output never echoes control characters. - Size checks per variant — Apple's 10, 15 and 100 MB limits applied to each variant of
Xcode's
App Thinning Size Report.txtby iOS version, deployment target and invocation type, with an exit status for CI. - Website association — generate and validate
apple-app-site-association, checkappclips:/applinks:entitlement entries, and lint App Clip Code URLs against Apple's encoding rules. - The moment after the task — location confirmation with a validated 500 m region, the App
Store overlay for the full app, and
HandoffStore, which passes a versioned, expiring, size-limited value to the full app through the shared App Group. - Tested — 119 Swift Testing tests run on macOS and an iPhone simulator, including the edge cases above and the quick start below.
- An example that builds — Examples/CoffeeShop is an app and its App Clip from the same sources; CI builds it, and the Usage samples are copied from it.
1. Add the package
In Xcode, choose File › Add Package Dependencies… and enter the repository URL:
https://github.com/muhittincamdali/AppClipsStudio.git
Leave Dependency Rule at Up to Next Major Version from 2.0.0 and click Add
Package. In the next window, choose your App Clip target next to AppClipsStudio and click
Add Package again. (If your project has no App Clip yet, add one with File › New ›
Target… › App Clip; add the package to the full app target too.)
2. Route the invocation
Replace everything in the App Clip's ContentView.swift with:
import AppClipsStudio
import SwiftUI
enum Screen: Equatable {
case welcome
case table(Int)
}
struct ContentView: View {
@State private var screen = Screen.welcome
var body: some View {
Group {
switch screen {
case .welcome: Text("Scan a table tag")
case .table(let number): Text("Table \(number)")
}
}
.font(.largeTitle)
.onInvocation { invocation in
screen = (try? Self.router.route(invocation)) ?? .welcome
}
}
static let router: InvocationRouter<Screen> = {
var router = InvocationRouter<Screen>()
try? router.add("/table/:number") { match in
match.integer("number").map(Screen.table)
}
router.fallback { _ in .welcome }
return router
}()
}3. Run it with an invocation URL
Choose Product › Scheme › Edit Scheme…, select Run › Arguments, and set the
_XCAppClipURL environment variable (Xcode adds it to every App Clip scheme) to
https://appclip.example.com/table/12. Choose an iPhone simulator and press Run (⌘R). The
App Clip shows "Table 12"; with /table/twelve or no path it shows "Scan a table tag".
The same code is compiled and tested in
Tests/AppClipsStudioTests/ReadmeQuickStartTests.swift.
Add the library to your App Clip and full app targets in Xcode as in the quick start, or in
Package.swift:
dependencies: [
.package(url: "https://github.com/muhittincamdali/AppClipsStudio.git", from: "2.0.0")
],
targets: [
.target(name: "YourAppFeature", dependencies: [
.product(name: "AppClipsStudio", package: "AppClipsStudio")
])
]git clone https://github.com/muhittincamdali/AppClipsStudio.git
cd AppClipsStudio
swift build -c release
cp .build/release/appclipstudio /usr/local/bin/ # or run it with `swift run appclipstudio`Version 2.0.0 (October 2026) is the first release of this code. The earlier release, 1.0.0 (February 2026), described modules that were never implemented; in June 2026 they were reduced to stubs, and in October 2026 the package was rewritten from Apple's App Clip documentation. CHANGELOG.md lists what changed.
The samples below are copied from the example app in
Examples/CoffeeShop, which CI builds.
From Shared/CoffeeRoutes.swift: a table tag,
a poster code and the default App Clip link, with the menu for every other URL.
var router = InvocationRouter<CoffeeScreen>(
allowedHosts: ["appclip.example.com", "example.com", Invocation.defaultLinkHost]
)
try router.add("/table/:number") { match in
guard let number = match.integer("number"), (1...99).contains(number),
let store = match.queryInteger("p").flatMap(Catalog.store(id:)) else { return nil }
return .table(store, number: number)
}
try router.add("/order") { match in
match.queryInteger("p").flatMap(Catalog.drink(id:)).map(CoffeeScreen.drink)
}
try router.add("appclip.apple.com/id") { match in
match.queryInteger("drink").flatMap(Catalog.drink(id:)).map(CoffeeScreen.drink)
}
router.fallback { _ in .menu }A handler that returns nil (an unknown store, a table number out of range) lets the next
route try, and finally the fallback.
From Shared/CoffeeModel.swift. A person who
returns from a notification or the App Switcher launches the App Clip without a URL, so each
invocation is saved and restored:
func handle(_ invocation: Invocation) {
do {
screen = try router.route(invocation) ?? .menu
lastInvocation.save(invocation)
rejection = nil
} catch {
rejection = error
}
}From Shared/RootView.swift, App Clip only (the
APPCLIP compilation condition):
.onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
guard let invocation = try? Invocation(userActivity: activity) else { return }
model.handle(invocation)
if let payload = activity.appClipActivationPayload {
Task { await model.confirmLocation(with: payload) }
}
}
.fullAppOverlay(isPresented: $model.showsFullAppOverlay)func confirmLocation(with payload: APActivationPayload) async {
guard case .table(let store, _) = screen else { return }
confirmation = await payload.confirm(store.location)
}Each store's location is an ExpectedLocation, which only accepts finite coordinates in
range and a radius greater than 0 and at most 500 meters, Apple's limit.
func placeOrder() {
var order = PlacedOrder(drinkIDs: cart.map(\.id), placedAt: Date())
if case .table(let store, let number) = screen {
order.storeID = store.id
order.table = number
}
try? handoff?.save(order, expiresAfter: 30 * 24 * 60 * 60)
placedOrder = order
cart = []
#if APPCLIP
showsFullAppOverlay = true
#endif
}
/// In the full app: takes the order the App Clip left, once.
func importHandoff() {
importedOrder = try? handoff?.take()
}handoff is a HandoffStore<PlacedOrder> on the App Group's UserDefaults suite, shared by
both targets.
Check every variant of an exported App Clip (the exit status is 1 when one is over its limit):
$ appclipstudio size "App Thinning Size Report.txt" --deployment-target 16.0
App Clip size check (iOS 16+, physical and digital invocations)
ok ExampleClip-a.ipa 14.60 MB of 15.00 MB
OVER ExampleClip-b.ipa 15.20 MB of 15.00 MB
1 of 2 variants are over the limit.
Check URLs for App Clip Codes:
$ appclipstudio check-url https://www.example.com/products/
https://www.example.com/products/
suggestion: Remove the "www" subdomain if your site allows it.
suggestion: Remove the trailing "/".
Generate and validate the association file, and check entitlement entries:
appclipstudio aasa generate --app ABCDE12345.com.example.MyApp \
--app-clip ABCDE12345.com.example.MyApp.Clip --path "/table/*" > apple-app-site-association
appclipstudio aasa validate apple-app-site-association --app-clip ABCDE12345.com.example.MyApp.Clip
appclipstudio check-domain appclips:appclip.example.com applinks:example.comEvery command takes --json. appclipstudio help lists the options.
The example App Clip opened with a table tag URL and a poster URL:
| Table tag (light) | Table tag (dark) | Poster (light) | Poster (dark) |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
The screenshots are captured on an iPhone simulator by
scripts/capture-screenshots.sh. In the simulator the
system passes no activation payload, so the badge reads "Location not checked on this launch".
To try it yourself, open CoffeeShop.xcodeproj in Examples/CoffeeShop,
choose the CoffeeShopClip scheme and an iPhone simulator, and press Run.
Examples/README.md has the details.
- API reference
(DocC, published to GitHub Pages from
master) - Build it locally in Xcode with Product › Build Documentation, or from the command line:
xcodebuild docbuild -scheme AppClipsStudio -destination 'generic/platform=iOS Simulator'- Getting Started — add the package to both targets, route the invocation and test it (source).
- Routing Invocations — what is checked, the pattern syntax and which route wins (source).
- Checking App Clip Size
— Apple's limits, the size report and the
sizecommand (source). - Associating Your Website
— entitlement entries,
apple-app-site-associationand App Clip Code URLs (source). - Handing Off to the Full App
— location confirmation, the App Store overlay, notifications and
HandoffStore(source).
| Platform | Minimum version |
|---|---|
| iOS | 16 (location confirmation and the overlay are iOS only) |
| macOS | 13 (the command-line tool and the platform-neutral checks) |
| Toolchain | Swift 6.2 · Xcode 26+ |
CI builds with the default Xcode of GitHub's macos-26 runner image. The package is developed
with Xcode 27. The example app targets iOS 17.
Sources/AppClipsStudiois the library, one folder per task:Invocation,Routing,Size,AppClipCode,Association,Handoff,LocationandPromotion. Everything except the SwiftUI modifiers and theAPActivationPayloadextension is value types and pure functions, so it runs and is tested on macOS too.- Errors are typed (
throws(InvocationError),throws(ThinningReportError), …) so callers can switch over every case. Sources/AppClipsStudioToolholds the command-line tool's commands as a library, so the tests call them directly;Sources/appclipstudioonly forwards the arguments.- CI runs
swift teston macOS andxcodebuild teston an iPhone simulator, builds the example app and publishes the DocC documentation.
Run the tests locally:
swift test # macOS
xcodebuild test -scheme AppClipsStudio-Package \
-destination 'platform=iOS Simulator,name=iPhone 17'- Add the package to the Swift Package Index;
.spi.ymlis already in the repository. - Read sizes from an exported
.ipadirectly, without the size report. - An App Clip experience list for the App Store Connect API (advanced experiences per location).
Contributions are welcome. Read the contributing guide and the code of conduct before opening a pull request. Report security issues privately as described in the security policy.
Released under the MIT license. See LICENSE.



