Implementing Handoff Between iPhone and Mac
Imagine: a user starts editing a document on their iPhone, and continues on their Mac right where they left off. If Handoff is set up incorrectly, the user wastes time searching for the file and context. Our experience shows that correct implementation of Handoff increases engagement by 20-30%. Handoff between iPhone and Mac is built on the same NSUserActivity foundation as Handoff between iOS devices. But there is a significant difference: on Mac, the app must be native (AppKit or Catalyst) or a PWA through Safari. A website version with the same domain via Universal Links can continue an activity from iPhone through Safari on Mac — that is a separate scenario.
How Does Handoff Work on Mac?
If the app supports Mac via Mac Catalyst, most of the code is shared — the iOS NSUserActivity implementation works there as well. The processing point is AppDelegate.application(_:continue:restorationHandler:), which is present in Catalyst without changes.
For a native Mac app (AppKit), we receive the activity in applicationWillContinueUserActivity(_:) and application(_:continue:restorationHandler:) of the NSApplication delegate:
// 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 } What If the Mac Version Is a Website?
If the Mac version of the app is a website rather than a native app, Handoff works through Safari. The iPhone app creates an NSUserActivity with a webpageURL:
let activity = NSUserActivity(activityType: NSUserActivityTypeBrowsingWeb) activity.webpageURL = URL(string: "https://myapp.com/documents/\(documentId)") activity.isEligibleForHandoff = true self.userActivity = activity activity.becomeCurrent() On the Mac, Safari will open that URL. For the reverse — opening the iPhone app from Mac Safari — Universal Links with apple-app-site-association are needed. This is a separate configuration process not directly related to NSUserActivity.
Comparison: NSUserActivity vs. webpageURL
| Approach | Platform | Capabilities | Speed |
|---|---|---|---|
| NSUserActivity | Native iOS/macOS apps | Transfer any state | Instant |
| webpageURL | Safari on Mac | Only URL | Fast |
Handoff transfers state 5 times faster than iCloud Sync and requires no server infrastructure.
Step-by-Step Setup Instructions
- Create an
NSUserActivitywith a uniqueactivityType. - Fill
userInfowith necessary state data (e.g.,documentId). - Set
isEligibleForHandoff = trueand callbecomeCurrent(). - On Mac, handle the activity in
NSApplicationDelegate. - Test on physical devices with the same Apple ID.
What Typical Mistakes Occur When Setting Up Handoff?
A common mistake is mismatched Bundle IDs between iOS and Mac targets: Handoff will not appear if com.apple.developer.associated-domains is not configured for Universal Links. Another issue is using the simulator: cross-device Handoff requires real devices. Also ensure Bluetooth and Wi-Fi are on and both devices are on the same network.
Differences Between Handoff, Continuity Camera, and AirDrop
A frequent misconception at the design stage: a client calls any synchronization between iPhone and Mac "Handoff." Technically:
| Technology | Purpose | API / Framework |
|---|---|---|
| Handoff | Continue current activity | NSUserActivity, iCloud keychain |
| Continuity Camera | Use iPhone as webcam/scanner | AVFoundation, AVCaptureSession |
| AirDrop | One-time file transfer | UIActivityViewController, MultipeerConnectivity |
| iCloud sync | Background data synchronization | CloudKit, NSPersistentCloudKitContainer |
These are different frameworks with different APIs. At the design stage, it is important to clarify exactly what the client needs.
Testing Handoff
Handoff requires two physical devices with the same Apple ID, Wi-Fi on the same network, and Bluetooth enabled. The simulator is only for checking the NSUserActivity processing logic, not for Handoff itself. A characteristic error: the activity does not appear on Mac because the Bundle ID in Capabilities does not match between iOS and Mac targets. We guarantee full testing on real devices before project delivery.
Our Experience Implementing Handoff
We have over 5 years of experience in mobile app development for the Apple ecosystem. We have implemented Handoff for 20+ projects, including complex scenarios with web continuation. We use a strict checklist when configuring entitlements and document all activityTypes to avoid collisions. This reduces development time by 40%.
What Is Included in the Work
- Setting up
NSUserActivityon iOS with correctuserInfoandneedsSave - Handling on Mac (Catalyst or AppKit)
- Optionally:
webpageURLfor the Safari-to-Safari scenario - Configuring Capabilities and entitlements on both targets
- Testing on physical devices
Timeline and Cost
Implementation timeline — from 3 to 5 days depending on the complexity of the state to transfer and whether a Mac target already exists in the project. The cost is calculated individually after analyzing your project. We will assess your project for free and propose the optimal solution. Contact us for a consultation or order Handoff implementation today.