AppMigrationKit
One-time cross-platform data transfer for app resources. Enables apps to
export data to or import data from another platform (for example, Android)
during device setup or onboarding. AppMigrationKit APIs are iOS 26.0+ /
iPadOS 26.0+; the data-container entitlement is iOS 26.1+ / iPadOS 26.1+ /
Mac Catalyst 26.1+. Swift 6.4.
Beta-sensitive. AppMigrationKit is new in iOS 26 and may change before GM.
Re-check current Apple documentation before relying on specific API details.
AppMigrationKit uses an app extension model. The system orchestrates the
transfer between devices. The app provides an extension conforming to export
and import protocols, and the system calls that extension at the appropriate
time. The app itself never manages the network connection between devices.
Contents
Workflow
- Confirm platform availability, migration entitlement, extension target, and shared-container layout.
- Inventory transportable resources, stable paths, size limits, versioning, and source-app identity.
- Export directly through
ResourcesArchiver with bounded gaps, progress, and cancellation propagation.
- Import transactionally, validate every resource, preserve recoverable evidence, and clean app-group state after success or failure.
- Verify with
AppMigrationTester, cancellation, partial archives, version skew, low storage, retry, and status clearing.
Route by Task
- Read core implementation details for architecture, entitlements, export/import, status, progress, testing, and error recovery.
- Read extended AppMigrationKit patterns for combined extensions, versioned migration, enumeration, and complex recovery flows.
Core Decisions
- Archive original resources directly instead of converting them during export.
- Propagate archiver cancellation and avoid long pauses between append operations.
- Validate imported paths and content before committing destination state.
- Clear migration/import status only after the app has durably handled the result.
Common Mistakes
DON'T: Catch cancellation errors from ResourcesArchiver
// WRONG -- system kills the extension if cancellation is swallowed
func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {
do {
try await archiver.appendItem(at: fileURL)
} catch is CancellationError {
// Swallowing this causes termination
}
}
// CORRECT -- let cancellation propagate
func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {
try await archiver.appendItem(at: fileURL)
}
DON'T: Leave long gaps between archiver append calls
// WRONG -- system may assume the extension is hung and terminate it
func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {
let allFiles = gatherAllFiles() // Takes 30 seconds
for file in allFiles {
try await archiver.appendItem(at: file)
}
}
// CORRECT -- interleave file preparation with archiving
func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {
for file in knownFilePaths() {
try await archiver.appendItem(at: file)
}
}
DON'T: Convert files to intermediate format during export
// WRONG -- may exhaust disk space creating temporary copies
func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {
let converted = try convertToJSON(originalDatabase) // Doubles disk usage
try await archiver.appendItem(at: converted)
}
// CORRECT -- export files as-is, convert on import side if needed
func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {
try await archiver.appendItem(at: originalDatabase)
}
DON'T: Ignore app group containers during import error recovery
// WRONG -- system clears app container but not app groups on error
func importResources(at url: URL, request: ResourcesImportRequest) async throws {
try writeToAppGroup(data)
try writeToAppContainer(data) // If this throws, app group has stale data
}
// CORRECT -- clear app group data before importing
func importResources(at url: URL, request: ResourcesImportRequest) async throws {
try clearAppGroupData()
try writeToAppGroup(data)
try writeToAppContainer(data)
}
DON'T: Forget to clear import status after handling it
// WRONG -- migration UI shows every launch
if let status = MigrationStatus.importStatus {
showMigrationResult(status)
// Missing clearImportStatus()
}
// CORRECT
if let status = MigrationStatus.importStatus {
showMigrationResult(status)
MigrationStatus.clearImportStatus()
}
Review Checklist
References
1---2name: appmigrationkit3description: "Builds one-time cross-platform app-data transfers with AppMigrationKit. Use for AppMigrationExtension setup, ResourcesArchiver export/import, transportable resources, progress, cancellation, MigrationStatus, app-group cleanup, recovery, or AppMigrationTester verification."4metadata:5 source: https://skillmd.com/skills/thiennc-tesoglobal/appmigrationkit6---78# AppMigrationKit910One-time cross-platform data transfer for app resources. Enables apps to11export data to or import data from another platform (for example, Android)12during device setup or onboarding. AppMigrationKit APIs are iOS 26.0+ /13iPadOS 26.0+; the data-container entitlement is iOS 26.1+ / iPadOS 26.1+ /14Mac Catalyst 26.1+. Swift 6.4.1516> **Beta-sensitive.** AppMigrationKit is new in iOS 26 and may change before GM.17> Re-check current Apple documentation before relying on specific API details.1819AppMigrationKit uses an app extension model. The system orchestrates the20transfer between devices. The app provides an extension conforming to export21and import protocols, and the system calls that extension at the appropriate22time. The app itself never manages the network connection between devices.2324## Contents2526- [Workflow](#workflow)27- [Route by Task](#route-by-task)28- [Core Decisions](#core-decisions)29- [Common Mistakes](#common-mistakes)30- [Review Checklist](#review-checklist)31- [References](#references)3233## Workflow34351. Confirm platform availability, migration entitlement, extension target, and shared-container layout.362. Inventory transportable resources, stable paths, size limits, versioning, and source-app identity.373. Export directly through `ResourcesArchiver` with bounded gaps, progress, and cancellation propagation.384. Import transactionally, validate every resource, preserve recoverable evidence, and clean app-group state after success or failure.395. Verify with `AppMigrationTester`, cancellation, partial archives, version skew, low storage, retry, and status clearing.4041## Route by Task4243- Read [core implementation details](references/core-implementation.md) for architecture, entitlements, export/import, status, progress, testing, and error recovery.44- Read [extended AppMigrationKit patterns](references/appmigrationkit-patterns.md) for combined extensions, versioned migration, enumeration, and complex recovery flows.4546## Core Decisions4748- Archive original resources directly instead of converting them during export.49- Propagate archiver cancellation and avoid long pauses between append operations.50- Validate imported paths and content before committing destination state.51- Clear migration/import status only after the app has durably handled the result.5253## Common Mistakes5455### DON'T: Catch cancellation errors from ResourcesArchiver5657```swift58// WRONG -- system kills the extension if cancellation is swallowed59func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {60 do {61 try await archiver.appendItem(at: fileURL)62 } catch is CancellationError {63 // Swallowing this causes termination64 }65}6667// CORRECT -- let cancellation propagate68func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {69 try await archiver.appendItem(at: fileURL)70}71```7273### DON'T: Leave long gaps between archiver append calls7475```swift76// WRONG -- system may assume the extension is hung and terminate it77func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {78 let allFiles = gatherAllFiles() // Takes 30 seconds79 for file in allFiles {80 try await archiver.appendItem(at: file)81 }82}8384// CORRECT -- interleave file preparation with archiving85func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {86 for file in knownFilePaths() {87 try await archiver.appendItem(at: file)88 }89}90```9192### DON'T: Convert files to intermediate format during export9394```swift95// WRONG -- may exhaust disk space creating temporary copies96func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {97 let converted = try convertToJSON(originalDatabase) // Doubles disk usage98 try await archiver.appendItem(at: converted)99}100101// CORRECT -- export files as-is, convert on import side if needed102func exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {103 try await archiver.appendItem(at: originalDatabase)104}105```106107### DON'T: Ignore app group containers during import error recovery108109```swift110// WRONG -- system clears app container but not app groups on error111func importResources(at url: URL, request: ResourcesImportRequest) async throws {112 try writeToAppGroup(data)113 try writeToAppContainer(data) // If this throws, app group has stale data114}115116// CORRECT -- clear app group data before importing117func importResources(at url: URL, request: ResourcesImportRequest) async throws {118 try clearAppGroupData()119 try writeToAppGroup(data)120 try writeToAppContainer(data)121}122```123124### DON'T: Forget to clear import status after handling it125126```swift127// WRONG -- migration UI shows every launch128if let status = MigrationStatus.importStatus {129 showMigrationResult(status)130 // Missing clearImportStatus()131}132133// CORRECT134if let status = MigrationStatus.importStatus {135 showMigrationResult(status)136 MigrationStatus.clearImportStatus()137}138```139140## Review Checklist141142- [ ] Extension target added with `com.apple.developer.app-migration.data-container-access` entitlement143- [ ] Entitlement array contains exactly one string: the containing app's bundle identifier144- [ ] Extension conforms to `ResourcesExportingWithOptions` or `ResourcesExporting` for export145- [ ] Extension conforms to `ResourcesImporting` for import146- [ ] `resourcesSizeEstimate` returns a reasonable byte estimate147- [ ] `resourcesVersion` is set and will be checked on import for format compatibility148- [ ] Export calls `appendItem` incrementally without long pauses149- [ ] Cancellation errors from `ResourcesArchiver` are not caught150- [ ] Import clears app group containers before writing new data151- [ ] Containing app checks `MigrationStatus.importStatus` on first launch152- [ ] `clearImportStatus()` called after handling the migration result153- [ ] `AppMigrationTester` used in unit tests to validate export and import154- [ ] Files are exported as-is without intermediate format conversion on the export side155- [ ] `sourceVersion` from import request used to handle versioned data formats156157## References158159- Extended patterns (combined extension, versioned migration, file enumeration, error recovery): [references/appmigrationkit-patterns.md](references/appmigrationkit-patterns.md)160- [AppMigrationKit framework](https://sosumi.ai/documentation/appmigrationkit)161- [AppMigrationExtension](https://sosumi.ai/documentation/appmigrationkit/appmigrationextension)162- [ResourcesExportingWithOptions](https://sosumi.ai/documentation/appmigrationkit/resourcesexportingwithoptions)163- [ResourcesImporting](https://sosumi.ai/documentation/appmigrationkit/resourcesimporting)164- [ResourcesArchiver](https://sosumi.ai/documentation/appmigrationkit/resourcesarchiver)165- [MigrationStatus](https://sosumi.ai/documentation/appmigrationkit/migrationstatus)166- [MigrationDataContainer](https://sosumi.ai/documentation/appmigrationkit/migrationdatacontainer)167- [AppMigrationTester](https://sosumi.ai/documentation/appmigrationkit/appmigrationtester)168- [Data container entitlement](https://sosumi.ai/documentation/bundleresources/entitlements/com.apple.developer.app-migration.data-container-access)169- [Core implementation details](references/core-implementation.md) -- setup, API wiring, and focused implementation recipes moved out of the entrypoint.