iphone Programming : Integrating Your Application - Custom URL Schemes

One of the more interesting features provided by the SDK is the ability for your application to use custom URL schemes to launch other applications, and in turn, to register custom URL schemes of its own. These schemes can be used to launch your application, either from the browser or from another application on the device. Additionally, such schemes are not just limited to launching the application; you can pass additional information to your application via the URL.

1. Using Custom Schemes

Most of the built-in applications Apple provides respond to custom URL schemes; for example, the Maps, Mail, YouTube, iTunes, and App Store applications will all open in response to custom URLs. However, there are also many established third-party applications with published URL schemes that you can use in your own application.

---

Note:

At the time of this writing, a fairly extensive list of URL schemes for third-party iPhone applications was available at http://handleopenurl.com/scheme.

---

1.1. Making a telephone call

You can easily trigger a telephone call from your application by using the tel: URL scheme:

NSString *string = @"tel:+19995551234";
NSURL *url = [NSURL URLWithString:string];
[[UIApplication sharedApplication] openURL:url];

1.2. Sending an SMS message

Unfortunately, Apple has not provided either a standard view controller as it did with email or an API for sending SMS messages from your application. This is regrettable, but if you consider the abuses that programmatic access might allow, you can probably follow the company’s reasoning as to why this is not available.

However, you can use the custom URL scheme sms:[phone number] to open the SMS application and allow your users to send SMS messages:

NSString *string = @"sms:+19995551234";
NSURL *url = [NSURL URLWithString:string];
[[UIApplication sharedApplication] openURL:url];

As this will cause your application to exit and you cannot prepopulate the body of the SMS message, it’s not generally very useful.

2. Registering Custom Schemes

Regardless of what you intend to do after a custom URL launches your application, you must first register your custom scheme using your application’s Info.plist file. Let’s do that for our City Guide application. You can choose any of the versions of the City Guide application we’ve worked on so far for this addition.

Open the project in Xcode and click on its Info.plist file to open it in the Xcode editor. Right-click the top row’s Information Property List and select Add Row. A row will be added and you’ll be prompted to select a key from a drop-down menu. Scroll to the bottom and select “URL types.” This will create an array key item, so click the disclosure triangle next to “URL types” to expand it.

Click on Item 0 to expand it to show the URL identifier line. The value for this can actually be anything, but it’s normal to use the Bundle Identifier, so double-click on the Bundle Identifier value to select it and then copy the identifier string. Then double-click on the field to the right of the URL identifier and paste it into the box.

Now right-click on Item 0, and select Add Row. You’ll be presented with a shorter drop down of possible values; this time select URL Schemes. This will create an array key item. Expand it, double-click on the value box for its Item 0, and enter cityguide.

If you’ve followed the procedure correctly, your Info.plist file should now look like mine does in Figure 1. We’re done; adding a custom URL scheme to your application really is that easy.

Figure 1. The Info.plist with our cityguide:// scheme registered

Of course, now that we’ve added the custom URL scheme we need to modify our application code so that it knows what to do with it. We’re going to modify the City Guide application to take URLs of the form cityguide://<City Name> and open the relevant city page (e.g., the London page for cityguide://London).

---

Warning:

If two different applications register with the same URL scheme, the most recently installed application will be the one that responds to custom URLs conforming to the URL scheme.

---

We really need to make only a few changes to the City Guide application to implement handling custom URL schemes. When the application is opened in response to a cityguide:// URL, the application:handleOpenURL: method is called in the application delegate class.

Click on the CityGuideDelegate.m implementation file to open it in the Xcode editor, and add the following method:

- (BOOL)application:(UIApplication *)application
  handleOpenURL:(NSURL *)url
{
    // URL of the form cityguide://London
    viewController.placeFromURL = [url host];
    return YES;
}

Save your changes and then click on the RootController.h interface file. Here we need to declare an instance variable (put this inside the @implementation block’s curly braces):

NSString *placeFromURL;

Now declare it as a property:

@property (nonatomic, retain) NSString *placeFromURL;

In the corresponding RootController.m implementation file, synthesize the new property:

@synthesize placeFromURL;

Now modify the viewDidLoad: method to do the actual work. I’ve highlighted the code that you need to add to deal with the custom URL scheme:

Code View: Scroll / Show All

- (void)viewDidLoad {
    self.title = @"City Guide";
    self.navigationItem.rightBarButtonItem = self.editButtonItem;
    CityGuideDelegate *delegate =
      (CityGuideDelegate *)[[UIApplication sharedApplication] delegate];
    cities = delegate.cities;

    if ( self.placeFromURL ) {
					NSIndexPath *indexPath;
					for( int i = 0; i < cities.count; i++ ) {
					City *thisCity = [cities objectAtIndex:i];
					if( [thisCity.cityName isEqualToString:self.placeFromURL] ) {
					indexPath = [NSIndexPath indexPathForRow:i inSection:0];
					}
					}
					// Begin debugging code
					UIAlertView *alert = [[UIAlertView alloc]
					initWithTitle:self.placeFromURL
					message:[NSString stringWithFormat:@"indexPath = %@", indexPath]
					delegate:self
					cancelButtonTitle:nil
					otherButtonTitles:@"OK", nil];
					[alert show];
					[alert autorelease];
					// End debugging code
					CityController *city =
					[[CityController alloc] initWithIndexPath:indexPath];
					[delegate.navController pushViewController:city animated:NO];
					[city release];
					}
}

					  

We’re done. Click the Build and Run button to compile and deploy the application into iPhone Simulator. Once the application is launched, quit again by clicking the Home button and navigate to Safari. Click on the address bar, enter cityguide://London, and click the Go button (or tap the Return key).

If all goes well, Safari should quit and the City Guide application will launch. Soon afterward, you should see something similar to Figure 2.

Figure 2. Opening the City Guide application from Safari

This doesn’t work only in Safari; we can now open the City Guide application from other applications using the following snippet of code:

NSString *string = @"cityguide://London";
NSURL *url = [NSURL URLWithString:string];
[[UIApplication sharedApplication] openURL:url];