Pages

Creating Custom URL schemes in iOS/iPhone

iPhone apps can also specify their own custom URL scheme (for example, myapp://doStuff). When might you want to use a custom URL scheme for your app?
  • To transfer data from your app to your  another app
  • To allow other apps (or even web pages) to call your app (and send data to it)
  • To handle callbacks for custom authentication (such as OAuth) and third party API's

Implementing 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.



 Select URL Types for the new item. Once that's added, click the grey arrow next to "URL Types" to show "Item 0". Set your URL identifier to a unique string - something like com.yourcompany.yourappname. 
 
After you've set the URL identifier, select that line and click the "+" sign again, and add a new item for URL Schemes. Then click the grey arrow next to "URL Schemes" to reveal "Item 0". Set the value for Item 0 to be your URL scheme name. 


 

 

Handling Custom URL Calls

In order for your app to respond when it receives a custom URL call, you must implement the application:openURL:sourceApplication:annotation: method in the application delegate class:

 - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{

// handler code here
}

Parsing the Custom URL

There are several parts to a URL:
scheme://host/path?query
The parts to the URL can be retrieved through the NSURL object that is passed into the application:openURL:sourceApplication:annotation: method. If you have a fairly simple URL naming scheme and want to allow access to specific pages/keys, you can just use the host name:

 

 To pass data into your app, you'll want to use the query string. Here's a simple method for parsing the query string from the url:
- (NSDictionary *)parseQueryString:(NSString *)query {
    NSMutableDictionary *dict = [[[NSMutableDictionary alloc] initWithCapacity:6] autorelease];
    NSArray *pairs = [query componentsSeparatedByString:@"&"];
    
    for (NSString *pair in pairs) {
        NSArray *elements = [pair componentsSeparatedByString:@"="];
        NSString *key = [[elements objectAtIndex:0] stringByReplacingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
        NSString *val = [[elements objectAtIndex:1] stringByReplacingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
        
        [dict setObject:val forKey:key];
    }
    return dict;
}
 

Testing The Custom URL

You can easily test your URL scheme in the simulator. Just add a test button to one of your views, and implement the IBAction method for it as follows:

- (IBAction)getTest:(id)sender {
     NSString *escapedDataString = [@"any data you want to parse" stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding]
     NSURL *quotescreator = [NSURL URLWithString:[NSString stringWithFormat:@"quotescreator://sendtext?quote=%@",escapedDataString]];
                                    
     if ([[UIApplication sharedApplication] canOpenURL:quotescreator]) {
                                       
            [[UIApplication sharedApplication] openURL:quotescreator];
       } else {
                                        
            [[UIApplication sharedApplication] openURL:[NSURL URLWithString:@"http://itunes.apple.com/app/id895331100"]];
      }
}

 Then in your app delegate, implement the application:openURL:sourceApplication:annotation: method:

 - (BOOL)application:(UIApplication *)application
             openURL:(NSURL *)url
   sourceApplication:(NSString *)sourceApplication
          annotation:(id)annotation {
 
    NSLog(@"url recieved: %@", url);
    NSLog(@"query string: %@", [url query]);
    NSLog(@"host: %@", [url host]);
    NSLog(@"url path: %@", [url path]);
    NSDictionary *dict = [self parseQueryString:[url query]];
    NSLog(@"query dict: %@", dict);
    return YES;
}