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.

Workflow
Route by Task
Core Decisions
Common Mistakes
Review Checklist
References

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

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
Core implementation details -- setup, API wiring, and focused implementation recipes moved out of the entrypoint.