Handling URL schemes in Cocoa

This morning I was playing around with getting a Cocoa app to respond to a custom URL scheme and figured it would be useful to write up the basics here. The information is primarily distilled from this post by Nicholas Riley, but I wanted to provide a cleaner example with more explanation.

In case you have no idea what URL schemes are, this allows you to put links that can pass data to your app within a web page or any other place that URLs can appear. Discussions on why you would do this and whether or not it's a good idea are left for the reader.

This is a Mac OS X Cocoa app that just handles the myscheme URL scheme and prints out what it gets to the console. You can download the source here. To handle URLs your app has to handle an apple event. Handling apple events is pretty easy in Cocoa, but there are few hoops to jump through to get things setup.

To begin you have to add a script suite description to the resources for your application. A script suite tells the Cocoa runtime what apple events your application responds to and to what objects the events should be directed. To handle the opening of a URL you need to handle the GURL apple event. To do that we'll create a URLHandlerCommand object and setup our script suite to use it for handling the GURL event.

// file URLHandler.scriptSuite:

{
    Name = URLHandler;
    AppleEventCode = "UrHD";

    Commands = {
        "GetURL" = {
            CommandClass = URLHandlerCommand;
            AppleEventCode = GURL;
            AppleEventClassCode = GURL;
         };
    };
}

  

The companion file to the script suite is the script terminology file. This file provides additional descriptive information for use by Applescript. It provides more friendly terms that can be used to perform the actions you're defining. It isn't strictly necessary to add this file for basic URL handling, but it gives you a start for Applescript support in your application so it's not a bad thing to do.

// URLHandler.scriptTerminology:
{  
    Name = "URLHandler commands";
    Description = "Commands to handle a URL";
    
    Commands = {
        "GetURL" = {
            "Name" = "get URL";
            "Description" = "Open a URL";
        };
    };    
}

  

The final thing to configure your app is to add a couple keys to info.plist. First you want to turn on AppleScript support by setting NSAppleScriptEnabled to YES and then you need to define the URL scheme that you want to handle by setting CFBundleURLTypes. You can specify one or more URL schemes that you want to handle. Here's an excerpt from info.plist showing more detail.

        <key>NSAppleScriptEnabled</key>
	<string>YES</string>
        <key>CFBundleURLTypes</key>
	<array>
		<dict>
			<key>CFBundleURLSchemes</key>
			<array>
				<string>myscheme</string>
			</array>
		</dict>
	</array>

  

Finally we just have to implement URLHandlerCommand as a subclass of NSScriptCommand.

// file URLHandlerCommand.h

#import <Foundation/Foundation.h>

@interface URLHandlerCommand : NSScriptCommand {

}

@end

  

We use the performDefaultImplementation message to get the URL from the command object and print it out to the console. Obviously, a real app would do something a little more advanced.

// file URLHandlerCommand.m

#import "URLHandlerCommand.h"

@implementation URLHandlerCommand

- (id)performDefaultImplementation {
    NSString *urlString = [self directParameter];
    
    NSLog(@"url = %@", urlString);

    return nil;
}

@end


  

Nothing too hard there, but you can now create URLs that look something like myscheme:what_ever_you_want_here and anytime they're activated your application will get the data. If you build the app you can try it by clicking here. Just be aware that if you include the links in a web page the URL you get will be URL encoded so you need to handle it just like any other URL. Also, it should go without saying that the URLs defined this way are useless to anyone who doesn't have the app installed.

Posted by Kimbro Staken