How to configure universal links to work from a web browser to a Mac app 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?!?

Farcy

It's not available on MacOS. It would be an epic annoyance, and would only work on Safari; which would limit it's usability. – Fuhrman

On iOS it's not limited to Safari and it can be turned off even on a per domain basis... But I was expecting the answer would be no :( – Farcy

Not available on macOS. However, you could use a custom URI scheme redirect. It's more work and a less good user experience, but this is how apps like Spotify currently do it. – Pernod

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.

Cloudburst

I'm not seeing swcd anywhere, is it supposed to just run once I hit debug in Xcode? – Keeshakeeshond

Actually never mind, my issue was that I didn't have Safari as my default browser – Keeshakeeshond

Hey, another comment question! When you talk about having a hard getting it to pick up the association, does that happen to mean the UL runs the app, but doesn't run application(_:continue:restorationHandler:)? That's what's happening for me right now, and it doesn't really sound like the same thing you're describing, but I thought I'd check. I still don't have anything come up when searching swcd in Console, but I expect that's a red herring at this point anyway, now that the UL opens the app... – Keeshakeeshond

@ZAD-Man: When your app is opened, but the handler is not run, then the system does know about the association and the issue is likely something in your app (e.g., does the handler really have the correct signature, is it implemented in the correct class, something like that). – Cloudburst

Makes sense, and that's what I've been assuming...can't see what I could have done wrong though :/ – Keeshakeeshond

Aha! You set me on the right track - in the docs, it says to use restorationHandler: @escaping ([NSUserActivityRestoring]) -> Void, but if you just type "application" and go through the autocomplete options, it comes up with restorationHandler: @escaping ([Any]) -> Void, which was called when I clicked the UL! – Keeshakeeshond

Did anybody got this working? I also had trouble getting swcd to reliably re-request the file. This started to work when I would use 'applinks:<domain>?mode=developer' in macOS Catalina after deleting the built app from the Products folder in the Finder (swcd seems to react on that/on re-creation of the binary by the Xcode build). But I could not get the link to work from the Notes app even though /.well-known/apple-app-site-association seems correct. I am wondering: Does this work from Xcode? Does anybody have a apple-app-site-association file thats known to work? Any tipps? – Vinery

I've got swcd to re-download the file, just moving the binary to another folder. It triggers an event: "Entry { s = applinks, a = <app id>, d = de….ch….chat, ua = unspecified, sa = approved } needs its JSON updated because the app PI changed" – Watterson

After some research I've found that deep links works on Mac OS ONLY if Safari is default browser. It makes this technology completely useless. Better to stick to custom schemas. – Watterson

Answer 2

As an additional debugging step (additional to the list by DarkDust), also try incrementing your app's version and/or build numbers in Xcode and re-building. That caused my system to finally start picking up the app link and redirecting to my app's debug build.

(This should be a comment on DarkDust's answer, but I don't have enough reputation points to do that apparently.)

Contractual