Skill v1.0.1
currentLLM-judged scan95/100+3 new
version: "1.0.1" name: appmigrationkit description: "Transfer app data to or from other platforms using AppMigrationKit. Use when implementing system-orchestrated one-time migration between iOS and Android or another platform, building an AppMigrationExtension, packaging transportable resources with ResourcesArchiver, importing resources on the destination device, reporting import progress, handling migration errors and app group cleanup, checking MigrationStatus, or testing migration code with AppMigrationTester."
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.3.
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
- Architecture Overview
- Setup and Entitlements
- App Migration Extension
- Exporting Resources
- Importing Resources
- Migration Status
- Progress Tracking
- Testing
- Common Mistakes
- Review Checklist
- References
Architecture Overview
AppMigrationKit operates through three layers:
- App extension -- An
AppMigrationExtensionconforming type that the
system invokes during migration. It handles data export and import.
- System orchestration -- The OS manages the device-to-device session,
transport, and scheduling. The extension does not control when it runs.
- Containing app -- After migration completes, the app checks
MigrationStatus.importStatus on first launch to determine whether migration occurred and whether it succeeded.
Key types:
| Type | Role | |
|---|---|---|
AppMigrationExtension | Protocol for the app extension entry point | |
ResourcesExportingWithOptions | Protocol for exporting files via archiver | |
ResourcesExporting | Simplified export protocol (no custom options) | |
ResourcesImporting | Protocol for importing files on the destination | |
ResourcesArchiver | Streams files into the export archive | |
MigrationDataContainer | Access to the containing app's data directories | |
MigrationStatus | Check import result from the containing app | |
MigrationPlatform | Identifies the other device's platform (e.g., .android) | |
MigrationAppIdentifier | Identifies the source app by store and bundle ID | |
AppMigrationTester | Test-only actor for validating export/import logic |
Setup and Entitlements
Entitlement
The app extension requires the com.apple.developer.app-migration.data-container-access entitlement. Its value is a single-element string array containing the bundle identifier of the containing app:
<key>com.apple.developer.app-migration.data-container-access</key><array><string>com.example.myapp</string></array>
No other values are valid. This entitlement grants the extension read access to the containing app's data container during export and write access during import. The entitlement itself is available on iOS 26.1+, iPadOS 26.1+, and Mac Catalyst 26.1+, even though the core AppMigrationKit APIs are available on iOS 26.0+ and iPadOS 26.0+.
Extension Target
Add a new App Extension target to the Xcode project. The extension conforms to one or more of the migration protocols (ResourcesExportingWithOptions, ResourcesExporting, ResourcesImporting).
App Migration Extension
The extension entry point conforms to AppMigrationExtension. During migration, the system prevents launching the containing app and its other extensions to ensure exclusive data access.
Accessing the Data Container
The extension accesses the containing app's files through appContainer:
import AppMigrationKitstruct MyMigrationExtension: ResourcesExporting {var resourcesSizeEstimate: Int { estimateTotalExportSize() }var resourcesVersion: String { "1.0" }var resourcesCompressible: Bool { true }func exportResources(to archiver: sending ResourcesArchiver,request: MigrationRequest) async throws {let container = appContainer// container.bundleIdentifier -- app's bundle ID// container.containerRootDirectory -- root of the app container// container.documentsDirectory -- Documents/// container.applicationSupportDirectory -- Application Support/}}
MigrationDataContainer provides containerRootDirectory, documentsDirectory, and applicationSupportDirectory as URL values pointing into the containing app's sandbox.
Exporting Resources
Conform to ResourcesExportingWithOptions (or ResourcesExporting for no custom options) to package files for transfer. The system calls exportResources(to:request:) with a ResourcesArchiver and a MigrationRequestWithOptions.
Declaring Export Properties
struct MyMigrationExtension: ResourcesExportingWithOptions {typealias OptionsType = MigrationDefaultSupportedOptionsvar resourcesSizeEstimate: Int {// Return estimated total bytes of exported datacalculateExportSize()}var resourcesVersion: String {"1.0"}var resourcesCompressible: Bool {true // Let the system compress during transport}}
resourcesSizeEstimate-- Estimated total bytes. The system uses this for
progress UI and free-space checks.
resourcesVersion-- Format version string. The import side receives this
to handle versioned data formats.
resourcesCompressible-- Whentrue, the archiver may compress files
during transport.
Implementing Export
func exportResources(to archiver: sending ResourcesArchiver,request: MigrationRequestWithOptions<MigrationDefaultSupportedOptions>) async throws {let docsDir = appContainer.documentsDirectory// Check destination platform if neededif request.destinationPlatform == .android {// Platform-specific export logic}// Append files one at a time -- make continuous progresslet userDataURL = docsDir.appending(path: "user_data.json")try await archiver.appendItem(at: userDataURL)// Append with a custom archive pathlet settingsURL = docsDir.appending(path: "settings.plist")try await archiver.appendItem(at: settingsURL, pathInArchive: "preferences/settings.plist")// Append a directorylet photosDir = docsDir.appending(path: "photos")try await archiver.appendItem(at: photosDir, pathInArchive: "media/photos")}
The archiver streams files incrementally. Call appendItem(at:pathInArchive:) repeatedly as each resource is ready. The system may terminate the extension if it appears hung, so avoid long gaps between append calls.
Cancellation
ResourcesArchiver handles task cancellation automatically by throwing cancellation errors. Do not catch these errors -- doing so causes the system to kill the extension.
Migration Platform
MigrationRequestWithOptions exposes destinationPlatform as a MigrationPlatform value. Use this to tailor exported data:
if request.destinationPlatform == .android {// Export in a format the Android app expects}
MigrationPlatform provides .android as a static constant. Custom platforms can be created with MigrationPlatform("customPlatform").
Importing Resources
Conform to ResourcesImporting to receive transferred files on the destination device. The system calls importResources(at:request:) after app installation but before the app is launchable.
struct MyMigrationExtension: ResourcesImporting {func importResources(at importedDataURL: URL,request: ResourcesImportRequest) async throws {let sourceVersion = request.sourceVersionlet sourceApp = request.sourceAppIdentifier// sourceApp.platform -- e.g., .android// sourceApp.bundleIdentifier -- source app's bundle ID// sourceApp.storeIdentifier -- e.g., .googlePlay// Copy imported files into the app containerlet docsDir = appContainer.documentsDirectorylet userData = importedDataURL.appending(path: "user_data.json")if FileManager.default.fileExists(atPath: userData.path()) {try FileManager.default.copyItem(at: userData,to: docsDir.appending(path: "user_data.json"))}}}
Error Handling During Import
On import error, the system clears the containing app's data container to prevent partial state. However, app group containers are not cleared. The import implementation should clear any app group containers before writing imported content:
func importResources(at importedDataURL: URL,request: ResourcesImportRequest) async throws {// Clear shared app group data firstlet groupURL = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: "group.com.example.myapp")if let groupURL {try? FileManager.default.removeItem(at: groupURL.appending(path: "shared_data"))}// Then importtry await performImport(from: importedDataURL)}
Source App Identifier
ResourcesImportRequest provides sourceAppIdentifier as a MigrationAppIdentifier with three properties:
platform-- The source device's platform (e.g.,.android)bundleIdentifier-- The source app's bundle identifierstoreIdentifier-- The app store (e.g.,.googlePlay)
Migration Status
After migration completes, the containing app checks the result on first launch:
import AppMigrationKitfunc application(_ application: UIApplication,didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {if let status = MigrationStatus.importStatus {switch status {case .success:showMigrationSuccessUI()MigrationStatus.clearImportStatus()case .failure(let error):showMigrationFailureUI(error: error)MigrationStatus.clearImportStatus()}}return true}
MigrationStatus.importStatusisnilif no migration occurred.- Call
clearImportStatus()after handling the result to prevent showing
the notification on subsequent launches.
- The enum has two cases:
.successand.failure(any Error).
Progress Tracking
The import side exposes a Progress object via resourcesImportProgress. The system uses this to display transfer progress to the user. Update completedUnitCount incrementally during import:
struct MyMigrationExtension: ResourcesImporting {private let importProgress = Progress(totalUnitCount: 100)var resourcesImportProgress: Progress { importProgress }func importResources(at importedDataURL: URL,request: ResourcesImportRequest) async throws {let files = try FileManager.default.contentsOfDirectory(at: importedDataURL, includingPropertiesForKeys: nil)let increment = Int64(100 / max(files.count, 1))for file in files {try processFile(file)importProgress.completedUnitCount += increment}importProgress.completedUnitCount = 100}}
Testing
AppMigrationTester is a test-only actor for validating migration logic in unit tests hosted by the containing app. Do not use it in production.
import Testingimport AppMigrationKit@Test func testExportImportRoundTrip() async throws {let tester = try await AppMigrationTester(platform: .android)// Exportlet result = try await tester.exportController.exportResources(request: nil, progress: nil)#expect(result.exportProperties.uncompressedBytes > 0)// Import the exported datatry await tester.importController.importResources(from: result.extractedResourcesURL,importRequest: nil, progress: nil)try await tester.importController.registerImportCompletion(with: .success)}
DeviceToDeviceExportProperties on the result exposes uncompressedBytes, compressedBytes (nil if not compressible), sizeEstimate, and version.
See references/appmigrationkit-patterns.md for additional test patterns.
Common Mistakes
DON'T: Catch cancellation errors from ResourcesArchiver
// WRONG -- system kills the extension if cancellation is swallowedfunc 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 propagatefunc 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 itfunc exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {let allFiles = gatherAllFiles() // Takes 30 secondsfor file in allFiles {try await archiver.appendItem(at: file)}}// CORRECT -- interleave file preparation with archivingfunc 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 copiesfunc exportResources(to archiver: sending ResourcesArchiver, request: ...) async throws {let converted = try convertToJSON(originalDatabase) // Doubles disk usagetry await archiver.appendItem(at: converted)}// CORRECT -- export files as-is, convert on import side if neededfunc 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 errorfunc 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 importingfunc 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 launchif let status = MigrationStatus.importStatus {showMigrationResult(status)// Missing clearImportStatus()}// CORRECTif let status = MigrationStatus.importStatus {showMigrationResult(status)MigrationStatus.clearImportStatus()}
Review Checklist
- [ ] Extension target added with
com.apple.developer.app-migration.data-container-accessentitlement - [ ] Entitlement array contains exactly one string: the containing app's bundle identifier
- [ ] Extension conforms to
ResourcesExportingWithOptionsorResourcesExportingfor export - [ ] Extension conforms to
ResourcesImportingfor import - [ ]
resourcesSizeEstimatereturns a reasonable byte estimate - [ ]
resourcesVersionis set and will be checked on import for format compatibility - [ ] Export calls
appendItemincrementally without long pauses - [ ] Cancellation errors from
ResourcesArchiverare not caught - [ ] Import clears app group containers before writing new data
- [ ] Containing app checks
MigrationStatus.importStatuson first launch - [ ]
clearImportStatus()called after handling the migration result - [ ]
AppMigrationTesterused in unit tests to validate export and import - [ ] Files are exported as-is without intermediate format conversion on the export side
- [ ]
sourceVersionfrom import request used to handle versioned data formats
References
- Extended patterns (combined extension, versioned migration, file enumeration, error recovery): references/appmigrationkit-patterns.md
- AppMigrationKit framework
- AppMigrationExtension
- ResourcesExportingWithOptions
- ResourcesImporting
- ResourcesArchiver
- MigrationStatus
- MigrationDataContainer
- AppMigrationTester
- Data container entitlement