Launching Your Own Application via a Custom URL Scheme

Posted on December 14, 2008 by Rodney Aiglstorfer in Cocoa


One of the coolest features of the iPhone SDK is an application’s ability to “bind” itself to a custom URL scheme and for that scheme to be used to launch itself from either a browser or from another application on the iPhone. Creating this kind of binding is so simple, its almost criminal not to use it in your application!

Before you get started, you need to figure out how you want you application to respond to the URL. The simplest way to use custom schemes is to just “wake up”; but it is also possible to pass information to the application via the URL, and in so doing, enable the application to do different things when woken up.

Registering Custom URL Schemes

Regardless of what you want to do once your application is started, the first step is to register a custom URL scheme with the iPhone. This is done via the info.plist file located in your application’s project folder (NOTE: this is the same file you would change to define a custom icon).

By default, when opened, XCode will edit the file in a graphical UI. It is possible to edit the info.plist file directly in Text mode which may be easier for some people.

Step 1. Right-Click and “Add Row”

screen-capture.png

Step 2. Select “URL types” as the Key

screen-capture-1.png

Step 3. Expand “Item 1″ and provide a value for the URL identifier. This can be any value, but the convention is to use a “reverse domain name” (ex “com.myapp”).

screen-capture-2.png

Step 4. Add another row, this time to “Item 1″.

screen-capture-3.png

Step 5. Select “URL Schemes” as the Key.

screen-capture-4.png

Step 6. Enter the characters that will become your URL scheme (e.g. “myapp://” would be “myapp”). It is possible for more than one scheme to be registered by adding to this section though that would be strange thing to do.

screen-capture-6.png

NOTE: If you open the info.plist file in a text editor you will see the following has been added to the file …

CFBundleURLTypes
 
    CFBundleURLSchemes
 
      myapp
 
    CFBundleURLName
    com.yourcompany.myapp

Optionally Handle the URL

Now that the URL has been registered. Anyone can start the application by opening a URL using your scheme.

Here are a few examples …

myapp://
 
myapp://some/path/here
 
myapp://?foo=1&bar=2
 
myapp://some/path/here?foo=1&bar=2

The iPhone SDK, when launching the application in response to any of the URLs above, will send a message to the UIApplicationDelegate.

If you want to provide a custom handler, simply provide an implementation for the message in your delegate. For example:

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url 
{
  // Do something with the url here
}

A common technique is to parse the URL passed in and pull from it the parameters that will be used by various views in the application and store them in the User Preference. Below is an example where we store the URL as a value parameter “url” in just such a manner …

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
{
    if (!url) {  return NO; }
 
    NSString *URLString = [url absoluteString];
    [[NSUserDefaults standardUserDefaults] setObject:URLString forKey:@"url"];
    [[NSUserDefaults standardUserDefaults] synchronize];
    return YES;
}

Now you have everything you need to enable others to wake-up your application and even pass it information! Enjoy!

Comments

23 Responses to “Launching Your Own Application via a Custom URL Scheme”

Leave Comment

(required)

(required)