How to map a custom protocol to an application on the Mac?

brd6644_41754 0
Viewed 36250

I'm trying to register a custom protocol to an application on the Mac, i.e:

  1. User clicks on link with "abcdef://some/url/here"
  2. An installed application is launched with the above string passed as the first param

I've done this successfully on Windows using the information from this question:

how do I create my own URL protocol? (e.g. so://...)

I would prefer to find something that is browser-independent, in other words at the OS level. I would also like to automate this registration through a shell script, so hopefully there is a way to do this that doesn't involve the GUI.

Thanks!

protocol-handler custom-url-protocol macos protocols
7 Answers

I've not had occasion to use it, but some time ago I bookmarked OS X URL handler to open links to local files which is exactly what you're looking for.

The important part of the linked procedure is adding an appropriate CFBundleURLTypes to your application's Info.plist that describes the scheme. The example given there looks like this:

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>Local File</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>local</string>
        </array>
    </dict>
</array>
Jay_208400

This question is a decade old(!) but a Google search brought me here so I wanted to mention something I just discovered.

Platypus is an open source tool that allows you to create standalone "Applications" from a shell script or other scripting language. Although it's really just a script wrapper, it does enable some cool things like dialog boxes and menu bar items.

Critically, it even enables you to register your "app" as a handler for your own custom URL scheme. From the docs:

Register as URI scheme handler makes the app register as a handler for URI schemes. These can be either standard URI schemes such as http or a custom URI schemes of your choice (e.g. myscheme://). If your app is the default handler for a URI scheme, it will launch open every time a URL matching the scheme is opened. The URL is then passed to the script as an argument.

Setup is dead simple. Just provide your script, enter your desired scheme name on the advanced settings page and then click to build the app (it's all automated). Everything after the scheme and forward slashes will be passed as the argument to your script.

For example, you could use the following bash script as a handler for the "speak://" protocol.

#!/usr/bin/env bash
# The 'say' command on macOS will speak the provided text through the speaker
say $1

You could invoke it by entering speak://say-something-funny into your browser or by using the open command on the command line:

$ open "speak://hello-from-the-command-line"
user_3081450

The important part of the linked page in Jay's answer is the entry in the Info.plist.

I think with Launch Services it will automatically open this app if it is the only one that can handle a particular URL scheme, else you'll need to use the trick that Charlie Martin describes.

I'm not sure what the defaults command that needs to be executed is, or if it is a launchctl command.

user_1880

Digging up the details is difficult, but there is a preference pane called RCDefaultApp that will handle it for you. I'd still love to know how it works, will continue digging.

user_350920

I am not experienced much with Mac so any help would be appreciated.

Trying to add my custom protocol with the help of duti run in the post-install script of the Packages installer:

#!/bin/sh
## 
##  add_handlers.sh -- register UTI handlers for the MyApp
##
##  Requires the duti tool
##

./duti -s MyApp myapp

The handler appears in the RCDefaultApp preference pane, but when invoked from my other application, it opens Safari with that protocol in the address bar asking "Do you want to allow this page to open “MyApp”? and when clicked Allow shows error:

Safari can’t open the specified address. Safari can’t open “myapp://” because macOS doesn’t recognise internet addresses starting with “myapp:”.

Also when trying to open from the terminal:

deploy@mini-mac-mini ~ % open myapp://

LSOpenURLsWithRole() failed with error -10810 for the URL myapp://.

user_2089180
Related