Реализация Handoff между iPhone и Mac

Реализация Handoff между iPhone и Mac

Handoff между iPhone и Mac строится на той же основе NSUserActivity, что и Handoff между iOS-устройствами. Но есть существенная разница: на Mac приложение должно быть нативным (AppKit или Catalyst) или PWA через Safari. Веб-версия сайта с тем же доменом через Universal Links может продолжить активность с iPhone через Safari на Mac — это отдельный сценарий.

Особенности Mac-стороны

Если приложение поддерживает Mac через Mac Catalyst, большая часть кода общая — iOS-реализация NSUserActivity работает и там. Точка обработки — AppDelegate.application(_:continue:restorationHandler:), которая присутствует в Catalyst без изменений.

Для нативного Mac-приложения (AppKit) принимаем активность в applicationWillContinueUserActivity(_:) и application(_:continue:restorationHandler:) делегата NSApplication:

// NSApplicationDelegate
func application(_ application: NSApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([NSUserActivityRestoring]) -> Void) -> Bool {
  guard userActivity.activityType == "com.myapp.editing-document",
        let docId = userActivity.userInfo?["documentId"] as? String else {
    return false
  }

  DocumentManager.shared.openDocument(id: docId)
  return true
}

Handoff через браузер: Universal Links + Web Credentials

Если Mac-версия приложения — это веб-сайт, а не нативное приложение, Handoff работает через Safari. iPhone-приложение создаёт NSUserActivity с webpageURL:

let activity = NSUserActivity(activityType: NSUserActivityTypeBrowsingWeb)
activity.webpageURL = URL(string: "https://myapp.com/documents/\(documentId)")
activity.isEligibleForHandoff = true
self.userActivity = activity
activity.becomeCurrent()

На Mac Safari откроет этот URL. Для обратного — открыть iPhone-приложение с Mac Safari — нужны Universal Links с apple-app-site-association. Это отдельный процесс настройки, не связанный напрямую с NSUserActivity.

Continuity Camera и AirDrop не то же самое

Частое заблуждение на этапе проектирования: клиент называет «Handoff» любую синхронизацию между iPhone и Mac. Технически:

• Handoff — продолжение текущей активности (открытый документ, позиция в списке)
• Continuity Camera — использование iPhone как веб-камеры или сканера для Mac
• AirDrop — одноразовая передача файлов
• iCloud sync — фоновая синхронизация данных

Это разные фреймворки с разными API. На этапе проектирования важно зафиксировать, что именно нужно клиенту.

Тестирование

Handoff требует двух физических устройств с одним Apple ID, Wi-Fi в одной сети, Bluetooth включён. Симулятор — только для проверки логики обработки NSUserActivity, не для самого Handoff. Характерная ошибка: активность не появляется на Mac, потому что Bundle ID в Capabilities не совпадает между iOS и Mac-таргетами.

Что входит в работу

• NSUserActivity на iOS с правильными userInfo и needsSave
• Обработка на Mac (Catalyst или AppKit)
• Опционально: webpageURL для сценария Safari → Safari
• Настройка Capabilities и entitlements на обеих таргетах
• Тестирование на физических устройствах

Сроки

3–5 дней в зависимости от сложности состояния, которое нужно передать, и наличия Mac-таргета в проекте. Стоимость рассчитывается индивидуально.