Getting Started with URL Schemes

You might think that the recent advances in Shortcuts on iOS has killed the previous method of using URL schemes, and while there’s no arguing that Shortcuts — especially those with parameters like on iOS 13 — are more user friendly, not every app developer has had a chance to implement them yet or will have done so by the time iOS 13 launches.

URL Schemes sound complex — and I’ll admit, they’re not the easiest to read when you first come across them – but if you know how they work, you’ll find they’re not too hard to understand! Let’s start at the beginning.

You’ve seen web addresses before, they start with http or https, which stands for Hypertext Transfer Protocol. This tells your device that the link should be opened in a web browser. You may also have seen tel and mailto links, which tell your device that it should call a number or open an email to an email address. URL schemes work the same way. You start by specifying which application you want to talk to:

omnifocus:///
things:///
bear://x-callback-url/
due://x-callback-url/
ulysses://x-callback-url/

As you can see here, there are some variations in the way this works. Usually, the apps with URL schemes that start with just two forward slashes are followed by x-callback-url, but as every app implements their own system, it may vary. Now we know how to address the app we need to do something!

omnifocus:///add?name=Pick%20up%20milk

So, reading along we can see that we’re talking to OmniFocus and telling it to add — something with the name Pick%20up%20milk, which is URL-encoded — a system which makes text safe to put in URLs so the characters don’t break our URL. In this case, it means all the spaces need to be replaced with %20. Now when we open the URL, a task is added to OmniFocus with the name Pick up milk.

Two tricks to make your life easier: If you’re on iOS and using Shortcuts to open the URL, you don’t need to URL-encode anything written in the URL action, and if you’re not using Shortcuts you can URL-encode your text either with Shortcuts, Keyboard Maestro, or online services.

The question mark in our URL scheme marks the start of the parameters. Information is passed into the app, and the part before this is the command it will run. Everything after this is the information it needs to run the command in the format of parameter=value. You can add multiples of these with &, so if we want to add a note to our Pick up milk task, we could do this:

omnifocus:///add?name=Pick%20up%20milk&note=Low%20fat

The beauty of URL schemes is, in many cases, they are cross platform. This means you can build a URL to add a task to OmniFocus to run the dishwasher, but then run it on iOS or macOS and enjoy the same results on both.

Now, you can guess as to what might work with which application, but as previously mentioned every application can implement their own system. While add works in Due, OmniFocus and Things, Things and Due use title as the name of their task while OmniFocus uses name, so either you need to read the documentation for each application you want to use, or you need to cheat! Cheating is of course much faster, and as the point of a URL scheme is to make your life easier and likely automate something, it’s definitely fair play.

There’s more than one way to cheat of course, and depending on the application you’re looking to create the URL scheme for, there may be more than one way. Some applications like DEVONthink, Drafts, etc. offer the ability to copy the URL scheme for the item you have open. Others, including Things, offer a URL scheme generator on their website. The final way involves an iOS app: Launch Center Pro, which can generate URL schemes and provide a convenient way to launch them too. It will put text to be URL-encoded inside two sets of curly brackets (like%20this), which makes it much more readable. If you want to take the generated URL scheme out of Launch Center Pro, I created a quick Shortcut that will take your clipboard and convert it for you.

A note for Shortcuts: There are two actions you can use after the URL action for URL schemes. You can Open URL (this will take you to the target application), or you can Open X-Callback URL, which will then bring you back to Shortcuts once the action has been completed.

Documentation for the URL schemes used in this article can be found here:

• Bear
• Due
• OmniFocus
• Things: this includes a URL scheme generator for your projects and tasks.
• Ulysses

Go forth, and have fun with URL schemes!

---

We have more useful workflow examples right here.

---