Universal Links on macOS

Question

Since iOS9, universal links work on iOS, but I am wondering if there is something like that on macOS? We have an application that is a macOS-App with a corresponding Web-App, and we would love links clicked by the user to open in the Mac-App instead of opening the browser with the target-link.

Is that anyhow possible on macOS? I just found samples for iOS, but none for macOS?!?

Answer 1

Supporting Universal Links on macOS requires support from both your app and your website (and macOS 10.15+).

See Apple's documentation Allowing Apps and Websites to Link to Your Content for details (the article deals with iOS, tvOS and macOS deep links), and its sub-articles Enabling Universal Links as well as Handling Universal Links.

Quick overview:

Basically, it's the same as on iOS: you need to create an apple-app-site-association file that is hosted on your server either in the root directory or in the .well-known directory (described in "Enabling Universal Links" linked above). It describes which URL paths can be passed to your app. It's important that this file is valid JSON (validate it!) and is served via HTTPS with a valid certificate and without any redirects!

You need to enable the "Associated Domains" capability in your provisioning profile. Details depend on whether Xcode manages your profiles or not. In your entitlements file (usually editable via the "Signing & Capabilities" tab of your target in Xcode) you need add the corresponding associated domain, like applinks:my.domain.example (no https:// or anything, just the raw domain name).

Then you need to implement application(_:continue:restorationHandler:) in your app delegate to handle the Universal Link.

It can be annoying to make macOS pick up the association for the first time during development. Debugging hints:

• Open Console.app and filter for swcd, that's the daemon responsible for associated web credentials and Universal Links. Sometimes you see hints why it did not work (like refusing the apple-app-site-association file).
• Also I had to kill the swcd daemon to make it get restarted by launchd and then pick up changes/fixes I did to the apple-app-site-association file. Both iOS and macOS should usually reload this file on "app installation"¹ (haven't seen this getting specified more clearly; I guess they mean App Store installs/updates but I don't know about when this is loaded for macOS apps distributed outside the App Store).
• Also, be aware that entering a Universal Link in Safari will not hand off to your app: Apple has stated in the dev forums² that they believe if a user is already in the browser environment they want to stay there and not suddenly move to an app. Therefor, to test the Universal Link, open Notes.app, create a new note and enter/paste the Universal Link you want to test there. You can then click it and get asked whether you want to open this in your app.

---

1) Sorry, don't have a dev forum link where I read this.

2) Again, sorry, don't have a link right now. Saw this stated at least two times by Apple employees, both cited the Notes trick. Even though they were talking about iOS there, this behaviour is the same on macOS as well.