Launching iOS Apps with a Custom URL Scheme

I’ve been experimenting with widgets recently which led me to wanting to launch apps with custom URLs. Trying and retrying different URLs during development is tiresome and I couldn’t remember the different ways to do it. Here’s my recap for future reference.

Custom URL Schemes

A custom URL scheme gives you a way to launch your app to a specific context. For example, launching to a particular screen or to display a specific item. If you need a recap on implementing custom URL schemes take a look at this Apple article. I’ve been playing with widgets in a sample App that shows country information using the following scheme:

Custom URL Scheme definition

A typical URL to open the country detail view looks like this:


You’re probably going to launch your App many, many times while implementing a custom URL scheme. Here’s a summary of three different ways you can use to try launching an App with specific URLs.

Launch on Device

Launching your app from a URL on a device is perhaps the slowest, most cumbersome way during development. I find it useful when I want a final sanity check that the launch works on a device. It’s slightly less painful on an iPad where I can keep a list of example URL’s in Notes with the App in split screen mode and quickly run down the list observing the results:

Launching from Notes on an iPad

Share from Desktop Safari

Using the simulator on your Mac is generally faster than using a device (especially if the simulator is already running). Enter the custom URL in the Safari address bar and use the share button to select the Simulator:

Share URL from Safari to Simulator

The share sheet allows you to choose between the running Simulators:

Simulator Share sheet

In theory, you can also edit the URL in the share sheet but I haven’t been able to get that to work with Xcode 12.

Launch from simctl

The fastest and most convenient way I’ve found is to use the command line to launch your App in the running Simulator. The simctl command has an openurl option that does the job:

xcrun simctl openurl booted facts://country/1149361

If you have more than one running simulator you can replace booted with a specific simulator device ID:

# xcrun simctl list devices
xcrun simctl openurl 91194807-8E7C-4220-A903-64A08ED64742 facts://country/2635167

Launching with the Debugger Attached

Finally, if you are debugging a launch issue remember that you can always have the debugger attached at launch. From the Xcode menu, Debug > Attach to Process by PID or Name...:

Attach Debugger to Process

Enter your Application name and click Attach. Xcode will wait for the process to launch and then attach the debugger. See Connecting Xcode to a Running Process for more details.

Read More