Appmigrationkit

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

• Workflow
• Route by Task
• Core Decisions
• Common Mistakes
• Review Checklist
• References

Workflow

1. Confirm platform availability, migration entitlement, extension target, and shared-container layout.
2. Inventory transportable resources, stable paths, size limits, versioning, and source-app identity.
3. Export directly through ResourcesArchiver with bounded gaps, progress, and cancellation propagation.
4. Import transactionally, validate every resource, preserve recoverable evidence, and clean app-group state after success or failure.
5. 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

• Extension target added with com.apple.developer.app-migration.data-container-access entitlement
• Entitlement array contains exactly one string: the containing app's bundle identifier
• Extension conforms to ResourcesExportingWithOptions or ResourcesExporting for export
• Extension conforms to ResourcesImporting for import
• resourcesSizeEstimate returns a reasonable byte estimate
• resourcesVersion is set and will be checked on import for format compatibility
• Export calls appendItem incrementally without long pauses
• Cancellation errors from ResourcesArchiver are not caught
• Import clears app group containers before writing new data
• Containing app checks MigrationStatus.importStatus on first launch
• clearImportStatus() called after handling the migration result
• AppMigrationTester used in unit tests to validate export and import
• Files are exported as-is without intermediate format conversion on the export side
• sourceVersion from 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
• Core implementation details -- setup, API wiring, and focused implementation recipes moved out of the entrypoint.