AppMigrationKit

One-time cross-platform data transfer for app resources. Enables apps to export data from one platform (e.g., Android) and import it on iOS during device setup or onboarding. iOS 26+ / iPadOS 26+ / 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:

1. App extension -- An

   AppMigrationExtension

   conforming type that the system invokes during migration. It handles data export and import.
2. System orchestration -- The OS manages the device-to-device session, transport, and scheduling. The extension does not control when it runs.
3. Containing app -- After migration completes, the app checks

   MigrationStatus.importStatus

   on first launch to determine whether migration occurred and whether it succeeded.

Key types:

AppMigrationExtension

ResourcesExportingWithOptions

ResourcesExporting

ResourcesImporting

ResourcesArchiver

MigrationDataContainer

MigrationStatus

MigrationPlatform

.android

MigrationAppIdentifier

AppMigrationTester

Setup and Entitlements

Entitlement

The app extension requires the

com.apple.developer.app-migration.data-container-access

<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.

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

Accessing the Data Container

The extension accesses the containing app's files through

appContainer

import AppMigrationKit

struct MyMigrationExtension: ResourcesExportingWithOptions, ResourcesImporting {
    // Access the containing app's directories
    let container = appContainer

    // container.bundleIdentifier     -- app's bundle ID
    // container.containerRootDirectory -- root of the app container
    // container.documentsDirectory    -- Documents/
    // container.applicationSupportDirectory -- Application Support/
}

MigrationDataContainer

containerRootDirectory

documentsDirectory

applicationSupportDirectory

URL

Exporting Resources

Conform to

ResourcesExportingWithOptions

ResourcesExporting

exportResources(to:request:)

ResourcesArchiver

MigrationRequestWithOptions

Declaring Export Properties

struct MyMigrationExtension: ResourcesExportingWithOptions {
    typealias OptionsType = MigrationDefaultSupportedOptions

    var resourcesSizeEstimate: Int {
        // Return estimated total bytes of exported data
        calculateExportSize()
    }

    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

  -- When

  true

  , 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 needed
    if request.destinationPlatform == .android {
        // Platform-specific export logic
    }

    // Append files one at a time -- make continuous progress
    let userDataURL = docsDir.appending(path: "user_data.json")
    try await archiver.appendItem(at: userDataURL)

    // Append with a custom archive path
    let settingsURL = docsDir.appending(path: "settings.plist")
    try await archiver.appendItem(at: settingsURL, pathInArchive: "preferences/settings.plist")

    // Append a directory
    let photosDir = docsDir.appending(path: "photos")
    try await archiver.appendItem(at: photosDir, pathInArchive: "media/photos")
}

The archiver streams files incrementally. Call

appendItem(at:pathInArchive:)

Cancellation

ResourcesArchiver

Migration Platform

MigrationRequestWithOptions

destinationPlatform

MigrationPlatform

if request.destinationPlatform == .android {
    // Export in a format the Android app expects
}

MigrationPlatform

.android

MigrationPlatform("customPlatform")

Importing Resources

Conform to

ResourcesImporting

importResources(at:request:)

struct MyMigrationExtension: ResourcesImporting {
    func importResources(
        at importedDataURL: URL,
        request: ResourcesImportRequest
    ) async throws {
        let sourceVersion = request.sourceVersion
        let 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 container
        let docsDir = appContainer.documentsDirectory

        let 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 first
    let groupURL = FileManager.default.containerURL(
        forSecurityApplicationGroupIdentifier: "group.com.example.myapp"
    )
    if let groupURL {
        try? FileManager.default.removeItem(at: groupURL.appending(path: "shared_data"))
    }

    // Then import
    try await performImport(from: importedDataURL)
}

Source App Identifier

ResourcesImportRequest

sourceAppIdentifier

MigrationAppIdentifier

• platform

  -- The source device's platform (e.g.,

  .android

  )

• bundleIdentifier

  -- The source app's bundle identifier

• storeIdentifier

  -- The app store (e.g.,

  .googlePlay

  )

Migration Status

After migration completes, the containing app checks the result on first launch:

import AppMigrationKit

func 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.importStatus

  is

  nil

  if no migration occurred.
• Call

  clearImportStatus()

  after handling the result to prevent showing the notification on subsequent launches.
• The enum has two cases:

  .success

  and

  .failure(any Error)

  .

Progress Tracking

The import side exposes a

Progress

resourcesImportProgress

completedUnitCount

var resourcesImportProgress: Progress {
    Progress(totalUnitCount: 100)
}

func importResources(
    at importedDataURL: URL,
    request: ResourcesImportRequest
) async throws {
    let progress = resourcesImportProgress
    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)
        progress.completedUnitCount += increment
    }
    progress.completedUnitCount = 100
}

Testing

AppMigrationTester

import Testing
import AppMigrationKit

@Test func testExportImportRoundTrip() async throws {
    let tester = try await AppMigrationTester(platform: .android)

    // Export
    let result = try await tester.exportController.exportResources(
        request: nil, progress: nil
    )
    #expect(result.exportProperties.uncompressedBytes > 0)

    // Import the exported data
    try await tester.importController.importResources(
        from: result.extractedResourcesURL,
        importRequest: nil, progress: nil
    )
    try await tester.importController.registerImportCompletion(with: .success)
}

DeviceToDeviceExportProperties

uncompressedBytes

compressedBytes

sizeEstimate

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 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