In this post, we’ll walk through the steps of creating Simple Serial, a Cocoa application whose sole purpose in life is to tell you if it’s registered or not. When a user goes to register Simple Serial, they’re sent an email, including a link. When they click the link, OS X launches the application and passes along the correct registration information to it. The user has never had to type in a serial number.
Simple Serial registers with OS X as the handler for simpleserial:// URLs. When you register it, you recieve email with a link like simpleserial://register/warwick%40codehackers.net/Bob%20Warwick/ABCD-ABCD-ABCD-ABCD. When you get the email, you click on the link, Simple Serial is passed the URL by OS X. The application then parses out the required data, validates it, and stores it for later retrieval.
So how do we go about setting this up in our applications? There are three steps. Letting OS X know that we’re handling simpleserial:// URLs, telling our application what to do when it receives the information, and actually applying that information for something useful.
Step One – Assign simpleserial:// URLs to the application
OS X allows you to specify your application as the app to handle a given URL scheme. In other words, I can have my application register with my computer to handle all URLs in the format of foo://stuff. This lets us pass data to an application from an email easily.
To do so, open the applications Info.plist file and insert
Now when it’s added to your system, it registers simpleserial:// with the system as its type. You can find some documentation about these plist keys here.
We need to enable Applescript support because OS X passes the URLs to our application via the ‘GetURL’ command.
Step Two – Tell application how to respond when a simpleserial:// request is recieved
We use a couple of Applescript script declaration files to handle the call made to our application. Please, stop crying! For Applescript/Cocoa intergration it’s on the painless end of the spectrum.
You’ll need two files added to your applications resources directory. In our example, they look like this:
You can find out more about these files by reading the Apple documentation on script suite files
Step Three – Processing the Data With Our Application
From the scriptSuite file, you might have noticed the line:
This tells our application that when we receive the request, it should pass it on to the class ’serialHandler’. In the sample project, I’ve created that class which parses out the URL and writes it to user defaults. This class should be a subclass of NSScriptCommand.
In the MainMenu.nib file I’ve created the user defaults of ‘regName’, ‘regSerial’, and ‘regEmail’. The sample project has those values bound to textfields in it’s window.
The serialHandler class looks like this:
Downloads – Sample Application and Source Code
Simple Serial.zip – This is the sample application. Download and run it. Then you can register it by using this link: simpleserial://register/warwick%40codehackers.net/Bob%20Warwick/ABCD-ABCD-ABCD-ABCD
Simple Serial Source.zip – This is the source code. Created with XCode 2.4.1 on OS 10.4.10.
All source is released free of charge. You may incorporate it into any of your applications. I assume no liability for any action that may come from you using this source. If you do use this in your application, I’d like a mention in your about box, but I don’t require it.
Update: I should note that this isn’t an original concept from me. Other developers like Michael Tsai have been smarter than me in this area for a while.