Реалізація 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-цілі в проекті. Вартість розраховується індивідуально.