A URL Scheme is like “http://…” or “ftp://…”. Those seem like a very low-level concept that you don’t have much control over, but actually, you do! What sounds like an exotic topic is not so exotic at all: we are constantly using different URL Schemes, on any given day. For example when we’re clicking a link to an iPhone app that launches the AppStore. Or when a friend sends us a link to a playlist and it opens in the Spotify desktop app.
In the following short tutorial, we’ll look at how custom URL schemes work on macOS and iOS.
URL Schemes and Document Types
Any macOS or iOS application can register itself as a handler for any URL scheme (like “http” or “https”) or document type (like “txt” files). Apart from those classics, however, an app can also register its own, custom URL scheme or document format.
If an app wants to indicate that it supports a certain document type or URL scheme, its “Info.plist” file has to be configured appropriately: the
CFBundleDocumentTypes key lists the document types that the app supports, while
CFBundleURLTypes is used for supported URL schemes.
In your own app, you can configure this easily via Xcode’s project settings: the “Info” tab offers sections for both “Document Types” and “URL Types”. The URL scheme can be any string we like (as long as it remains a valid URL format).
This enables the application to work with the configured types, for example, when opening files from Finder with “Open With” or handing off documents from one application to another on iOS.
Use Cases for Custom URL Schemes
In general, registering your own custom scheme allows you to route events directly to your application. When the user opens a URL with this scheme. As an example, let’s look at Tower, the Git desktop client that my team makes: opening the link “gittower://openRepo/http://github.com/jquery/jquery.git” on your machine will launch Tower and open the “Clone” dialog, with the appropriate clone URL pre-filled:
Another use case for us is to make registering Tower easier for our users. After purchasing a license, our customers receive an email that contains a link like this one: “gittower://activateLicense/CODE/NAME”
This will launch Tower (or bring it to front) and open the registration dialog with the license information pre-filled. This is much for comfortable than fumbling with copy and paste (only to notice that you missed a character or included unwanted ones…).
On iOS, the use cases are very similar: applications also make use of custom URL schemes to launch an application and then display a certain screen inside the app.
To make a long story short: custom URLs are a great way to deep-link into your application!
An Example App
Let’s get our hands dirty and create our own application that handles a custom URL scheme. Let’s call the app
CustomURLScheme and have it handle a scheme called (of course!)
The sample code for this little tutorial can be found here.
Registering Our Custom URL Scheme
The first step is to register the application as a handler for our custom URL scheme, in our project’s Info.plist file:
CFBundleURLTypes CFBundleTypeRole Viewer CFBundleURLName com.example.CustomURLScheme CFBundleURLSchemes foo
Thereby, we ceremoniously offer to take the role of “Viewer” for the URL scheme
For more information and a detailed explanation of all the possible configuration keys, you can have a look at Apple’s Property List Key Reference.
Handling Events from Your URL Scheme
The next step is to tell our application how to handle events that come in via our URL scheme.
For iOS applications, this is as simple as implementing the following delegate:
func application(_ app: UIApplication, open url: URL, options: