The Complete Tutorial on iOS/iPhone Custom URL Schemes

Note: Since the introduction of custom URL schemes, this post has consistently been the top read content on the blog. Although much is the same, there are a few nuances that have changed. This is a re-write of the original post, updated for the latest iOS and Xcode versions.

One of the coolest features of the iPhone/iOS SDK is an application’s ability to “bind” itself to a custom URL scheme and for that scheme to be used to launch the application from either a browser or from another application.

Registering a Custom URL Scheme

The first step is to create a custom URL scheme – start by locating and clicking on the project info.plist in the Xcode Project Navigator. With the plist displayed in the right pane, right click on the list and select Add Row:

From the list presented scroll down and select URL types.

Open the directional arrow and you’ll see Item 0, a dictionary entry. Expand Item 0 and you will see URL Identifier, a string object. This string is the name for the custom URL scheme you are defining. It’s recommended to ensure uniqueness of the name that you reverse domain name such as com.yourCompany.yourApp.

Tap on Item 0 and add a new row, select URL Schemes from the drop-down and tap Enter to complete the row insert.

Notice URL Schemes is an array, allowing multiple URL schemes to be defined for an application.

Expand the array and tap on Item 0. This is where you will define the name for the custom URL scheme. Enter just the name, do not append :// – for instance, if you enter iOSDevApp, your custom url will be iOSDevApp://

Here is how the complete definition looks at this point:

Although I appreciate Xcode’s intention when using descriptive names, I find it helpful to see the actual keys created. Here’s a handy trick, right-click on the plist and select Show Raw Keys/Values, the output will look as follows:

There’s another output format that also has merit, XML, as it’s much easier to see the structure of the dictionary and the nested array and its entries. Tap the plist and this time choose Open As – Source Code:

Calling Custom URL Scheme from Safari

With the URL scheme defined, we can run a quick test to verify the app can be called as expected using the URL. Before we do that, I’ll create a barebones UI so we can identify the app with the custom URL. The app contains nothing more than a UILabel with the text “App With Custom URL.” Download source for creating iOS App with Custom URL Scheme.

Using the simulator, here’s how to call the app:

– Run the application from within Xcode
– Once installed, the custom URL scheme will now be registered
– Close the app via the Hardware menu in simulator and choose Home
– Start Safari
– Enter the URL scheme defined previously in the browser address bar (see below)

At this point Safari will close and the app will be brought to the foreground. Congratulations, you’ve just called an iPhone application using a custom URL scheme!

Calling Custom URL Scheme from Another iPhone App

Let’s take a look at how to call the custom URL scheme from another iPhone application. Again, I’ve created a very simple iPhone application with nothing more than a UILabel and a UIButton – the former shows a message that this is the app that will call another app via a custom URL scheme, the button starts that process. Download source for creating iOS App to call Custom URL Scheme.

Line 5 we check to see if the custom URL is defined, and if so, use the shared application instance to open the URL (line 8). The openURL: method starts the application and passes the URL into the app. The current application is exited during this process.

Passing Parameters To App Via Custom URL Scheme

Chances are you’ll need to pass parameters into the application with the custom URL definition. Let’s look at how we can do this with.

The NSURL class which is the basis for calling from one app to another conforms to the RFC 1808 (Relative Uniform Resource Locators). Therefore the same URL formatting you may be familiar with for web-based content will apply here as well.

In the application with the custom URL scheme, the app delegate must implement the method with the signature below:

The trick to passing in parameters from one app to another is via the URL. For example, assume we are using the following custom URL scheme and want to pass in a value for a ‘token’ and a flag indicating registration state, we could create URL as follows:

NSString *customURL = @"iOSDevTips://?token=123abct&registered=1";

As in web development, the string ?token=123abct&registered=1 is known as the query string.

Inside the app delegate of the app being called (the app with the custom URL), the code to retrieve the parameters would be as follows:

It’s important to note that you cannot prevent another application from calling your app via custom URL scheme, however you can skip any further processing and return NO as shown above. With that said, if you desire to keep other apps from calling your app, create a unique (non-obvious) URL scheme. Although this will guarantee you app won’t be called, it will make it more unlikely.

Custom URL Scheme Example Projects

I realize it can be a little tricky to follow all the steps above. I’ve included two (very basic) iOS apps, one that has the custom URL scheme defined and one that calls the app, passing in a short parameter list (query string). These are good starting points to experiment with custom URL’s.

Q: Will this work from within the app? For instance, in a tab bar-based app with multiple Web Views, it would be nice to be able to pick a link within one web view, and immediately end up at application:handleOpenURL: since the app is already running. (If not, how is this sort of thing accomplished within an app that uses web views?)

@Aaron: Greetings! If application:handleOpenURL: is _not_ invoked, the next best thing might be to check the delegate method webView:shouldStartLoadWithRequest:navigationType: … though I’m hopeful it’s still possible the other way. :)

Create a class that implements the IWebViewDelegate protocol and implement the shouldStartLoadWithRequest method. When your webview needs to load a page (via a clicked link, an ajax request, some sort of javascript event, whatever…) it will call this method on your delegate and pass in an NSUrlRequest object.

if [[request url] scheme] is your app’s custom scheme, go ahead and do whatever it is the url indicates you should do, and return NO to prevent the webview from continuing to process the request. If the scheme isn’t something you want to catch, return YES to let the webview handle the request in the usual manner.

PhoneGap does this (see /iphone/PhoneGapLib/Classes/PhoneGapDelegate.m) in a very elegant way, providing a way for their javascript framework to call methods written in obj-c. They use the stringByEvaluatingJavaScriptFromString method of the webview to pass information back into the browser from obj-c, which is also pretty slick.

@Lawson Culver – this one had me bugged too. Instead of doing it through code ( [[UIApplication sharedApplication] setStatusBarHidden: YES]; ) you will need to add the “Status bar is initially hidden” line to your Info.plist and check the box. Once I did that, it worked for me!

As a rookie I have question you probably all be able to answer. I am building a mobile website and would like to include a line of code that automatically launches an iPhone app. It should be through some kind of URL link. Do you know how I could make this work? What is the ‘launch code’ or URL code for an iPhone application that you would have on your phone?

You can extend that with a small timeout to redirect the visitor to the Apps homepage or the iTunes page when the app is not installed like so:

<a href="//start" rel="nofollow">Play iThrown</a>

If the app is not installed, Safari will alert the user that it cannot open the link. Once the user clicks the OK button the setTimeout will kick in and send the user on to the apps page. You will want to work on this to inform/query the user on the next action.

The second was supposed to have an onclicked attribute with a setTimeout function in it redirecting the user in 500 mSeconds giving Safari enough time to pass control to the app if it is installed but short enough to keep the show going.

Im Using a webservice that send an email to the client which notifies them of an update to the app. Then Once they click the link inside the email, they should go to my custom app. For some reason mail won’t interpret the link as a link, but if i put the scheme in the url it works. I’m stumped

@Boris
You might want to try to make an HTML (rich) email with a link in it.
(To avoid spam-filters you should use the same link in the href as the visible one.)

Another, albeit less elegant, option is to create a page at your server which will transfer visitors over to the app. So the link in your emails point at http://www.your-server.com/transfer-to-app?open-code and the script redirects Safari to the correct location. Safari WILL recognize the URL scheme and will open the app accordingly.
You can also display a link to the itunes store here for those who do not have the app installed.
In PHP this would look something like:

<?header('Location:'.$_GET['scheme']);// add the following which will only be shown if the browser can't follow the 'header' directive:echo"You do not have so-and-so installed yet. <a href="itunes-store/app/so-and-so" rel="nofollow">Click here</a> if you would like to do so now";?>

DUDE! Thanks! That PHP is exactly the answer for me!! I’m going to build a PHP script which will take into account the client viewing a QR code and server up either a web URL or activate a Forusquare app check-in

@Maarten is there a way to automatically determine if an app is installed using a variation of your script? Perhaps in the UIWebView we could detect that it will try to navigate to a custom protocol and then ask UIWebView to stop the navigation (in ObjectiveC we can listen to this event). Thoughts?

What I need is .. I have to launch my application through another application when we click on a button. I tried this requirement using URL Scheme. Its working and I just want to know is there any other way to do the same task ??

These 2 are the assumed conditions:
The app which I am trying to launch is already there in iPhone and I know the name of the application.

I’m figuring that the best way to handle uniqueness of the URL scheme is to also have it be com.company.appname. I researched valid url scheme names and there are certainly standard url schemes (z39.50r for example) that have periods in them. So when you activate your app via webpage the url would look like “com.company.appname://whatever_parameters_you_want”. Any flaw with this approach? Not sure why we need a fancy registration process since this is pretty much guaranteed to be unique.

@FadiN: No, wont work. It is not possible to pre-fill the body part in the official text-app. There’s 2 more SMS apps in our index (http://handleopenurl.com/search?scheme=sms) of which the BeSMS allows setting the body. You can check if that app is available on the users’ phone (or iPod Touch, BeSMS works there too!). If it is, you can use that and otherwise fall back to the ‘normal’ SMS app.

@Dinesh: There is no way to return to your app from the telephone app.

@Paul: completely right you are. A fancy registration would only be useful if you would want to publish the possibilities of your app.

@Maarten : First of all thanks for insight on URL scheme. But my problem in little different.

I wast to open iBook, PDF reader etc. applications through URL’s similar to what DropBox is doing. But the issue is how will I find the URL for these applications. I tried searching “http://www.handleopenurl.com/” but the URLs are not listed there.

We have an SDK that is embedded in 100s of games and would like to enable each of them to at least start from another app. It sounds like the scheme has to be in the info.plist which is read only in the app? Thats such a terrible design. I would really like my SDK to be able to set up a standard scheme in each game so that we could call each app … there are so few games with scheme’s in them

i would like to thank the poster, for the great explanation, but i cant get my app to launch from the html link.
could you please anyone please post an example ?
this is how i am calling my app from a web page : go to urlapp

is this syntax correct ? does my app have to be on the app store ? (because i can call facebook app in the same manner)