Tuesday, 30 July 2013

Integrating Custom URL Schemes into your iOS app

I've always been fascinated by the idea of Custom URL Schemes in iOS - the functionality that allows these otherwise sandboxed applications to communicate with each other, and also allows deep-linking into these applications from something as simple as a URL.

Anyway, I had been waiting for the right project to use them - then I came up with the Squizzd project, and it was a perfect opportunity to use a Custom URL Scheme for sharing content.

In this article, I'll go through the processes involved in integrating a custom URL scheme into your iOS app, and other peripheral tasks that you may want to carry out.

1. Picking your URL scheme
The first thing you need to do is pick the scheme that you'd like to use for your project. It is important that you choose a scheme that is unique to your app. I can't find any guidance from Apple on how conflicts are resolved, but the general consensus is that it would be extremely unpredictable - your app may load only some of the time, or none of the time.

There are some URL scheme directories that will help in your due diligence (in order of directory size):
1m App Schemes by Zwapp
HandleOpenURL by Magnatron
iPhone URL Schemes by Akosma

There are many more lists out there too - shows that I'm not the only fan of this functionality!

In the remainder of this article, I'll use the scheme we're using in Squizzd - strangely enough, that is:  squizzd://
NOTE: once you've published your app, you may want to register your scheme with the directories above so that people know it exists, and also so that they can avoid using it in their own apps.

2. Inform iOS that you're using the scheme
Open your project in XCode, and go to the "Info" section of your target.
Expand the "URL Types" section, and click the +.
Enter a unique identifier for the URL scheme (usually involving your reversed domain name), and enter the scheme that you'd like to use - in this case we're using "squizzd".

Select an icon (usually the icon of your app) for the URL scheme, and select "Viewer" for the role.

NOTE: If you're using an older version of XCode, then you need to enter this information directly into the Info.plist file - a good example of how to do this is here.

This is actually all that you need to do in order to allow the opening of your app via the URL scheme - how easy is that?! Everything after this is only relevant if you want to handle the URL after the app's been opened.

3. Handling the URL
There is only one method that you need to implement in your AppDelegate:

(application:handleOpenURL: has been deprecated, but if you want to look after iOS4.1 users, then you can daisy-chain the two methods e.g.
      return [self application:application handleOpenURL:url];
from within application:openURL:sourceApplication:annotation:)

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
    if (!url) {  return NO; }

    // Remove the double forward slash from the beginning of the resourceSpecifier
    NSString *URLResource = [[url resourceSpecifiersubstringFromIndex:2];

    if ([[url schemeisEqualToString:@"squizzd"]) {
        NSLog(@"Squizzd URL...");    
        [self openProjectWithID:URLResource];
    } else {
        NSLog(@"Not a Squizzd URL...");
    return YES;

As you can see, the URL arrives in the form of an NSURL - there's a good cheat-sheet on its format here.

In the above example, I'm using another method in the AppDelegate -(void)openProjectWithID: in order to open the relevant content in the app - how you do that will depend entirely on what you're type of content you're sharing via the Custom URL Scheme - or if you're using it to share content at all.

Hopefully you can see just how easy it is to integrate a Custom URL Scheme into your iOS app. We're going to be following this article with similar posts about achieving the same results with Android, Windows Phone 8, and BB10.

Without rdrct.it, our URLs for the Squizzd app would need to be in the format: squizzd://abcde12345
This means that when using rdrct.it, we enter "squizzd://" into the Custom URL Scheme box.
We then share URLs in the format: http://rdrct.it/squizzd?abcde12345

rdrct.it will then take our custom URL scheme, add the querystring from the shared URL, and serve the following to the device: squizzd://abcde12345 in order to open the app with the correct content.

NOTE: Here's Apple's official documentation on opening your app this way.

But wait, there's more!

What if you want to open one app from within another. You can do this using Custom URL Schemes too:

     NSURL *squizzURL = [NSURL URLWithString:@"squizzd://abcde12345"];
     // Check if we can open the URL scheme
     if ([[UIApplication sharedApplication] canOpenURL:squizzURL]) {
          // We know we can open it, therefore do it...
          [UIApplication sharedApplication] openURL:squizzURL];

Using this method, we can actually see if the other app is installed, and we could then either open that app (if installed), or do something else (e.g. send the user to the app store) if it is not installed.
Anyway, don't take our word for it! Here's some other great resources on the subject:
1. There are a number of very good articles on Custom URL Schemes (and other iOS developer subjects) on iOS Developer Tips including this one: Launching your iPhone app via Custom URL Scheme
2. If you use Adobe AIR, then there's a good article on the subject by Aymeric Lamboley here.
I'll add more links as I come across them, but please let us know if you've got something to say on the subject.


  1. Thank you for your article.
    It must be not so easy to implement. I had the similar issue and it took several days before I'd managed in finding a solution. By the way, virtual data rooms reviews are full of useful information.

  2. Very good guide, thank y, I made like y said and it works.