Step 1: Sign up as an iTunes Affiliate

First you’ll need an affiliate account, so go to Apple’s iTunes Affiliates page and click on “Apply to be an affiliate,” which will take you to LinkShare. The sign up process asks for your company and website information.

You’ll need to apply to advertise for “Apple iTunes.” I don’t remember how long it took me to be approved, but I think it was less than 24 hours. They do check the website you provided to make sure it is legit. I have heard that they will reject your application if the website is just a placeholder or if it has trademarked names in the URL, such as “iPhone.”

You need a LinkShare account because Apple has provided LinkShare hooks into the App Store so it knows when a click turns into an actual sale. As a bonus you’ll earn a 5% commission.

Step 2: Create a LinkShare link for your app

Next, you’ll need to create a LinkShare link to your app in the App Store. Using this link will allow LinkShare to magically know if a click turns into a sale.

In LinkShare, select the Links > Deep Linking menu item, and select Apple iTunes as the advertiser. Enter your app’s iTunes URL in the URL field. Don’t worry about the U1 Value field right now, you can just leave it blank. Click Create Link and copy the resulting URL.

On your product page, wherever you link to your app in the App Store, use your LinkShare link instead. If you stop here, LinkShare will be able to track how many clicks from your product page result in sales. This is useful in itself, but it would be even better if you could track each promotion separately, and know how many sales a specific ad resulted in.

LinkShare supports ad/promotion tracking through “signatures” which is what the U1 Value field above was all about. Signatures are simply a user defined string that are passed to LinkShare via in the u1 URL parameter.

Step 3: Tracking referrers through the product page

When creating ads or links to your product, you’ll probably want to direct potential customers to your app’s product page on your website instead of directly to the App Store. This allows you to provide a video of your app, cross promote other products or services, or actually use HTML formatting. The complication that arises from this is remembering which ad the user clicked on to get to your product page by the time they get to the App Store.

The first step here is to know how the potential customer got to your product page to begin with. The easiest way to do that is to simply add on a URL parameter for the referrer and give each ad or promotion a different parameter value, which we’ll call a “signature.” For example, an ad for Hearts Attack could use this URL:

http://www.orderndev.com/hearts-attack.html?u1=GAD001

Here the referrer parameter name is u1, just to be consistent with LinkShare, and the ad signature is GAD001.

Next, you need to get the ad signature passed on to LinkShare. This is done through the u1 URL parameter, so you will need to modify any LinkShare URLs on your product page based on the signature parameter. You can do this either server side or client side in JavaScript. Dan Wood talks about how to track referrers server side for Mac apps, and his examples can be modified to work here. I chose to modify the LinkShare URLs client side using JavaScript. The basic algorithm is:

1. Check for the u1 URL parameter. If it exists save it off into a cookie.
2. Check for the signature cookie. If it exists, append “&u1=signature” to the LinkShare URLs.

At the bottom of my product page, I have code that looks like this:

	<script type="text/javascript">
		saveParameterInCookie('u1', 'hearts-attack-src');
		restoreCookieToParameterInAnchor('u1', 'hearts-attack-src', 'buy-link');
		restoreCookieToParameterInAnchor('u1', 'hearts-attack-src', 'app-store-link');
	</script>

The first line saves the URL parameter named u1 into a cookie named ‘hearts-attack-src.’ The next two lines update anchor tags in the HTML by appending the value of the signature cookie as an URL parameter. The second line says: update the ‘buy-link’ anchor tag by taking the contents of the ‘hearts-attack-src’ cookie as the value for the ‘u1′ parameter and appending it to the anchor tag’s URL.

Here’s the code for implementing saveParameterInCookie and restoreCookieToParameterInAnchor:

function getURLParameter(name) {
	name = name.replace(/[\[]/,"\\\[").replace(/[\]]/,"\\\]");
	var regexS = "[\\?&]"+name+"=([^&#]*)";
	var regex = new RegExp(regexS);
	var results = regex.exec(window.location.href);
	if (results == null)
		return null;
	else
		return results[1];
}

function addParameterToURL(url, name, value) {
	if ( value == null )
		return url;
	return '' + url + '&' + name + "=" + value;
}

function saveParameterInCookie(parameterName, cookieName) {
	var parameter = getURLParameter(parameterName);
	if ( parameter == null )
		return;

	createCookie(cookieName, parameter, 180);
}

function restoreCookieToParameterInAnchor(parameterName, cookieName, anchorName) {
	var cookie = readCookie(cookieName);
	if ( cookie == null )
		return;

	link = document.getElementById(anchorName);
	link.href = addParameterToURL(link.href, parameterName, cookie);
}

Hopefully the code is self-explanatory. It relies on functions createCookie and readCookie, which I got from this article on JavaScript cookies. I should also point out I am not a professional JavaScripter, so there may be bugs in the code. I make no guarantees about this code.

As complicated as all that might have seemed, you are now tracking potential customers from your ads or promotions, to your product page, to the App Store where LinkShare knows if they are actually buying or not.

Step 4: Tracking the performance of ads or promotions

The final step is viewing the results of your ad or promotion in LinkShare. LinkShare will be able to tell you how many visitors actually made it to the App Store, and how many of those actually bought something. To know how many visitors an ad or promotion is driving to your product page, you’ll need to use something like Mint or Google Analytics.

In LinkShare select the Reports > Advanced Reports menu item. Select the “Signature Activity” report type, and click View Report. You’ll get a table that looks like this:

The Member ID column is where your ad or promotion signature will show up. It will be whatever you pass to LinkShare via the u1 URL parameter. It also shows how many clicks the link got, and how much sales it generated. As you can see, my ads aren’t doing so hot, but at least I know that now.

Oops, sorry, wrong graphic. I meant this one:

Hmmm… not much difference really. As you can see I actually sold nothing on Sunday. Apparently everyone was interpreting “day of rest” as “don’t buy any iPhone apps today.”

This article is kind of a postmortem for the launch of Hearts Attack. I attempted a few different things in order to drum up sales. Some were more successful than others.

• One of the things I did before the launch was some search engine optimization on the Hearts Attack product page. Dan Wood of Karelia has some good resources on how to do SEO.

  I was fairly pleased with the results. The product page ended up on the first results page for a few of the keywords I was targeting. It could be better, but not bad for a PageRank amateur such as myself.

• On the day of launch, I issued a press release through prMac. I opted for their “extended press release” which sends the press release the same day and to more people. It’s only $20 so it’s low risk.

  I did see a couple of obvious benefits from this. The first benefit is “link juice” to the Hearts Attack product page and our company website in general. I had done some SEO earlier and discovered the biggest thing we were in need of was links. This helped immensely with that.

  Secondly, I mentioned in the press release that promotional codes were available upon request. Only three people ever asked for them, but I happily gave them away. I have not seen any reviews as a result, but hopefully at least I garnered some good will among reviewers.

  Speaking of reviewers, one thing I did not have ready at launch, that I should have, was a press kit. I kept mine simple in that it just contains screenshots and images of the app icon. I should have linked to it in the press release and product page, because it was something the reviewers immediately asked for.

  It terms of how many sales were made because of the press release, I don’t know. It did noticeably increase traffic to our site, but I didn’t have LinkShare hooked up at the time, so I don’t know how many of those visitors became customers.

• I wrote about Hearts Attack here and tweeted about it. I both published my own press release and then followed up with the story about Hearts Attack came about.

  This drove a decent amount of traffic to our website, and resulted in a few sales from my friends and other people who follow me on Twitter. Like the press release, it also helped with the “link juice” of our website.

• I asked my wife, Elaine, to write about it on Facebook since she has approximately 30 bazillion friends on there and I have none. Some say this is because I haven’t even created an account, but I think Facebook is just being stuck up.

  Anywho, this didn’t create much traffic, but it did create a couple of sales from friends who follow Elaine on Facebook, but not me on Twitter.

Of course the biggest driver of sales is being listed at the top in the App Store, which by default is sorted by the release date. Unfortunately being at the top is fated to be temporary, and I could easily tell when I fell down the list by looking at my sales.

In summary, I learned: I should have had LinkShare up and running to begin with so I could properly track conversions and know what approach is the most successful as far as sales. Second, I should have a press kit ready at launch and linked to it from the press release.

Way back in 2008 the original iPhone SDK came out, and I, like a lot of people, was excited about developing apps for the iPhone. My company is primarily a software development services company so I was mainly interested in learning the SDK so we could pick up iPhone contracts in addition to Mac ones. It also happens to be the case that my favorite card game is hearts, so I decided a good way to learn the iPhone SDK was to write my own hearts game.

After a couple of weeks I had the basic functionality implemented, and noticed I was playing it a lot. I realized then that I could probably make this into a product. Furthermore, releasing an iPhone app through the App Store seemed like a good way for us as a company to begin making the transition from a services based company to a product based one.

If I was going to release Hearts Attack as a published app, I knew the UI and presentation had to be greatly improved. I went through a lot of mockups for the main playing view, including one where everyone’s cards — all 52 of them — were always visible somewhere on the table (a truly horrible idea). Unfortunately I don’t seem to have most of the mockups around anymore, but I found a couple which you can see below. (See the product page for the end result.)

The biggest challenge I had was fitting everything on the screen and it still being legible and usable. By trial and error I figured out how small I could make the cards and still make them tappable, as well as their optimal position to make them accessible with one hand.

I began thinking about what would make Hearts Attack unique or different from its competitors. Back then there were literally just two iPhone hearts games in the App Store, and I felt pretty confident that what I had was already better than them, but I wanted to be sure. I decided on: oddball talking computer opponents, a tutorial that gave not only card suggestions but the rationale behind the choice (a pet peeve of mine), and multiple undo support for mis-taps and tactical errors.

The last step was to get professionals to do the sound and graphics. I ended up hiring a sound designer, a graphics designer, and a character illustrator. The sound design went smoothly, but getting the graphics done was a lot more involved than I anticipated, which is another story for another day. Jordan of OneToad Design created the app icon, playing backgrounds, and the special card backgrounds for the queen of spades and jack of diamonds. Lara Kehler did the character illustrations, which turned out great.

Unfortunately, Hearts Attack went on hiatus in early 2009. I was working full time on an iPhone contract, and simply didn’t have a lot of time to put into Hearts. Secondly, I had lost all desire in finishing it. It was becoming increasingly apparent that iPhone users didn’t want to pay more than $0.99 for anything, despite all the whining I did about it. I convinced myself it wasn’t worth releasing Hearts because it would never make back the money it cost us to make. Hearts stayed dormant for an entire year.

A couple of months ago, I decided to pick Hearts Attack back up again. I had the time and, as someone pointed out to me, it would never make money if I didn’t release it. I was tempted to update the app to the latest SDK (I started Hearts back before you could even use nibs on the iPhone) and add some features. I decided against this, because I really just wanted to ship it. I did have to update it to the 2.2.1 SDK because the current Xcode tools no longer ship with the 2.0 SDK.

Instead I focused on fixing the bugs and adding polish. Fortunately for me my wife happens to be a professional software tester with iPhone experience, so I got lots of good bugs to fix. I also prepared a press release, created a website, and otherwise got ready for the release. After I felt the app was stable enough, I submitted it to Apple on Friday. It was approved on Monday.

At this point, I’m still not convinced I’ll ever make back the money we spent on sound and graphic designers. A hearts card game simply is never going to be a big seller, and price point isn’t high enough to make up for that. Right now, I’m tending to think pessimistically about sales, but I’m going to do what I can to drum up sales and see how things go.

It’s a “wait and see” situation as to if we develop any more iPhone applications to sell ourselves. Of course, regardless of how well Hearts Attack does, we’d be happy to develop your iPhone app for you.

The player competes against three of seven possible colorful computer opponents, each of which has their own distinct looks and personality. The personalities range from a communist kitten trying to overthrow oppressive humans to a vegetarian vampire to a pacifist pirate who sells insurance. They always have something interesting to say about how they and their opponents are playing. The computer opponents can be configured to play at trivial, easy, normal, or hard difficulty levels.

Unique to Hearts Attack is its in-depth tutorial system. The tutorial begins by giving the player a brief introduction to the rules and strategies of hearts. Throughout the game it offers suggestions for which cards to pass or play, including the rationale for choosing those cards. The suggestions are useful to beginners learning how to play, and to more advanced players looking to improve their game. The suggestions can be used apart from the tutorial.

Since players always have their favorite way of playing hearts, Hearts Attack allows flexible configuration of the rules. Players can choose how cards are passed, which player leads and with what card, how penalty and bonus cards are scored, and what is required to shoot the moon or the sun.

Device Requirements

• iPhone or iPod touch
• Requires iPhone OS 2.2.1 or later
• 4.7 MB

Pricing and Availability

Hearts Attack 1.0 is $2.99 (USD) and available exclusively through the App Store in the Games category. Review copies are available upon request.

Links

• Order N Development, LLC
• Hearts Attack 1.0
• Purchase and Download

Company Information

Order N Development, LLC is a software engineering company providing contracting services for the Macintosh, iPhone, and iPad platforms. Order N Development was founded in 2002 in Dallas, TX by a small band of experienced Mac developers. Copyright 2002-2010 Order N Development, LLC. All Rights Reserved. Apple, and the Apple logo are registered trademarks of Apple Computer in the U.S. and/or other countries.

But at the risk of having my programmer’s license revoked, I have to confess I don’t really care about version control systems. I mean, I think it’s important to use version control, but I don’t get all excited about the latest ideas in version control technology or the newest VCS on the block. It’s just a tool. It keeps versions of all my code, and allows me to revert to previous versions, see when and how things changed, and collaborate with other programmers working in the same codebase. Beyond that I don’t much care.

The tools don’t make the programmer.

What’s new with DVCS is the proponents seem to think they need to evangelize their system. Unfortunately they rather suck at it, and their arguments usually leave me feeling that I don’t want to use software used by such jerks, on account that it might make me into a jerk. Or at least a bigger one.

However, I do think that a DVCS can be a really useful tool so I’ve come up with some suggestions for those wanting to effectively evangelize their favorite version control system, or at least annoy me less when they talk.

1. Don’t be condescending or insulting

   I think it’s part of human nature — or at least programmer nature — to assume you’re the smartest guy in the room, and think that anyone who disagrees with you is a real buffon. Programmers seem to take great pleasure in showing that the other person is an idiot, or didn’t know something they did, or is at least not as clever as they are. A lot of arguments for git or Mercurial seem to revolve around explaining how git or Mercurial are so clearly superior that only morons would use something else.

   While this works great for rallying the troops, it’s counterproductive when trying to win someone over to your side.

   Think of it this way: suppose someone comes to your door to tell you about their religion. During the discussion they are self righteous and condescending; they don’t listen to your arguments, but are only interested in proving that they’re right. Are you likely to be swayed to believe in their religion? If you’re like the other hairless bipedal mammals inhabiting this planet you won’t be, even if they had some valid points.

   As soon as you become insulting or condescending, your arguments will be rejected out of hand. I know this will upset some programmers because they believe if you show your argument is superior, everyone will accept it. But that’s not the way people work.

2. Try to be helpful

   The best way to introduce someone to your DVCS is by trying to help them. Not in the “I have all the answers” way, but in the “I’ve dealt with that before, and here’s what I did” kind of way. People will run into the kinds of problems that DVCS are good at solving. When they do, you can helpfully suggest a solution.

   However, some care should be taken so the suggestion doesn’t come off the wrong way.

   Wrong	Right
   Dude, why are you using subversion?	I’ve run into that problem before. I solved it by using feature X of git/hg in this way.
   Dude, just use git/hg.	You smell nice.

   Be aware that people may not know where their pain points are. I’ve seen customers jump through some excruciating hoops to get a piece of software to do something when there was an easier way. People get used to pain and begin to assume it’s normal. If you notice something like that, even if they’re not complaining about it, you can politely suggest a better way.

   Instead of a list of features that a DVCS provides or abstract arguments as to why they should be using it, people respond better to concrete examples of how a piece of software can make their lives better. People are also more responsive when they know you’re on their side, trying to help them, even if they don’t — or currently can’t — take your suggestion. Keep in mind switching VCS in the middle of product cycle is likely something most people can’t do.

   The right attitude is that of trying to help a friend, not conquer an enemy.

3. Be willing to answer questions, even dumb ones

   Distributed version control works differently from centralized version control, and it does require a different way of thinking. I know I was confused by it when I first started looking into it. A lot of tutorials jump into the mechanics of how to perform certain tasks, but rarely talk about the philosophy of the system or why things are the way they are. If you want to successfully persuade people that your DVCS is the best then you need to be willing to do a lot of patient education.

   I say “patient” because after using centralized version control they might have difficulty switching over to a new mental model. Or they might have heard a lot of FUD about your DVCS that you need to put to rest. It’s important to do this patiently, respectfully, and not insultingly because they’ve picked up misinformation or don’t immediately “get it” like you do. Otherwise they might ignore your DVCS so they don’t have to deal with people who look down on them because they don’t “get it.”

4. Make it trivial to install and use

   This seems like a no brainer, but it is an important part of any software. If it’s hard to try out and use your DVCS, it simply won’t get used. I think that for the most part both git and Mercurial succeed in this respect. My only complaint is neither has a good Mac GUI client. Contrast that with Subversion which has both Versions and Cornerstone on the Mac. You shouldn’t underestimate the draw of an easy to use, beautiful GUI.

I think Joel Spolsky has given the best example of how to properly promote and evangelize a DVCS. He wrote a blog post — Distributed Version Control is here to stay, baby — about how he came to learn and use DVCS. It’s well written, and instead of condescending, he’s actually humble and admits he was wrong about DVCS to begin with. Joel also created a site called HgInit that does an amazing job of explaining the philosophy behind Mercurial and gives a solid introduction to right way to use it. It’s actually the site that convinced me to start using Mercurial for real.

The old design simply wasn’t meeting our needs. Specifically:

• It didn’t communicate clearly what exactly we do here.
• It had a search box which, as far as I can tell, didn’t, and has never, worked.
• It had several pages describing services we don’t perform, at least not when a cop is around. Some of these pages just had boilerplate text in them. e.g. “Item 1″, “Item 2″, etc
• The visual design was really old and unprofessional. The new is at least not old.
• The old feedback form demanded a lot of extraneous information like title, company, telephone number, home address, when you shower, etc.
• It had a copyright date at the bottom of 2002, which caused people to ask: “Are you guys still in business?” This was apparently a barrier to them sending us money.

Fortunately, we mainly rely on word of mouth to get clients, but a bad website certainly doesn’t help our business. We could be missing out on clients who find our website, but don’t contact us for any of the reasons listed above.

I’ve recently had some time between contracts, which I used to think about how a software contractor’s website should be structured and what kind of information it should present. Also, I slept in late a lot. I came to some conclusions:

• It should immediately obvious to a visitor what the company does, no matter what page they land on.
• It should have a portfolio so the visitor can see what kind of work we have done in the past, and see if that matches up with what they want done at the quality level they want.
• A brief description of services that we do provide, explained in layman’s terms.
• It should be obvious and easy to get in touch with us. The form for submitting a message should have as few requirements as possible.
• It should contain a brief overview of the company, and the people in it. It should put a human face to the company.
• Noon really is not a bad time to wake up.

I also decided to add a page for products, mainly for future use.

Overall the project was a fun — and hopefully financially rewarding — exercise. It was interesting to think about what would induce a visitor to stick around on our site, and then actually contact us. I’m not sure if I got it completely right, but it’s at least a step in the right direction.

Unfortunately, I’ve not had much luck with Quartz Composer in way of meaningful compiler errors. Sometimes it returns good errors, sometimes inscrutable ones.

Composer: Wait, wait, I remember this… it’s COBOL, right?

However, I’ve found debugging OpenCL kernels to be much easier thanks to the invention of a function I like to call “printf.” If you run your kernel on the CPU, then you can print out values just like in C. With debugging solved, I just needed to figure out how to find compiler errors without having to run my code.

Unlike Core Image, OpenCL actually requires you to compile your kernel code explicitly before using it. The API’s required to do this will return nice compiler error messages and everything. The obvious thing to do would be wrap up these API’s in a command line tool and invoke the tool from Xcode, which is what I did.

The Code

You can download the Xcode project for clc, the OpenCL Compiler here. It requires Mac OS X 10.6 Snow Leopard and the associated Xcode tools. To install, just build the project and copy the resulting binary into your path somewhere. I used ~/bin.

Most of the code is self explanatory, with the possible exception of the output. Unlike most compilers, clc doesn’t output object code because the host and runtime CPU/GPU’s could easily be different. It could simply copy the source code as is for the output, but that was a little too obvious for my tastes. Instead clc compresses the source code and stuffs it into a binary plist. It has the slight benefit of potentially being smaller on disk, and making your source code negligibly less accessible to prying eyes, if you’re into that sort of thing.

There are definite possibilities for improvement. For example, there could be an option to encrypt the source code to be more “secure.” Or it could store the binary code generated by the host machine in the output on the chance that the host and runtime machines have the same hardware.

Setting up Xcode

To use clc, you’ll need to set up a build rule in your app’s target settings to run all OpenCL source files through it. Selecting the menu item Project > Edit Active Target, and then selecting the Rules tab, should land you here:

Add another rule, set it to process OpenCL source files using a Custom script. For the custom script enter:

~/bin/clc ${INPUT_FILE_PATH} -o ${TARGET_BUILD_DIR}/${PRODUCT_NAME}.app/Contents/Resources/${INPUT_FILE_BASE}.clar

Finally, you’ll need to tell Xcode where you’re putting the output file, which is:

${TARGET_BUILD_DIR}/${PRODUCT_NAME}.app/Contents/Resources/${INPUT_FILE_BASE}.clar

By default, Xcode won’t put OpenCL source files (.cl) into the target, meaning they won’t get compiled. For each of your OpenCL source files
you’ll need to explicitly add them to your target. There are several ways to do this, but the easiest is probably selecting all of them, and doing a Get Info (File > Get Info). Switch to the Targets tab and check the target they should be compiled into.

Runtime Code

At runtime, it’s pretty easy to retrieve the original OpenCL source code using the + (NSString *) openCLSourceWithData:(NSData *)data error:(NSError **)error; method on ONOpenCLArchive. However, there are a couple of convenience methods on NSBundle that makes retrieving the kernel easier. For example:

#import "ONOpenCLArchive.h"

NSString *kernelSource = [[NSBundle mainBundle] openCLResource:@"MyKernel"];

That’s pretty much all there is to it.

Conclusion

Although not ground breaking, this little tool has certainly been helpful to me by finding compiler errors at compile time instead of runtime. Hopefully it will be useful to other people as well.

This year they aren’t content with bringing conference justice to only the UK, so they’re branching out to the good ‘ole U.S. of A. by way of Atlanta, GA. To help you decide which conference you should attend, US or Europe, I’ve prepared the following quiz:

1. What is your opinion of Seattle?

   1. It’s nice, but isn’t nearly rainy or dreary enough.
   2. I like their coffee.
   3. The residents have too many teeth.

2. Describe your driving habits

   1. I like to drive on the left side of the road.
   2. I like to drive on both sides of the road.
   3. I like to merge right six lanes without signaling while going 147 mph on the off ramp and giving the finger with both hands in my black Camaro.

3. The pinnacle of human achievement is…

   1. Afternoon tea
   2. Sliced bread
   3. Hee Haw

Scoring: Give yourself -1 points for any 1 answer, 0 points for any 2 answer, and 1 point for any 3 answer.

If you scored is less than zero, you should attend NSConference Europe; if greater than zero, NSConference USA. If you scored exactly zero, you are truly a cultured individual and should attend both.

Personally, I’ll be attending both, and not just because of peer pressure and insightful quizzes. I’ll be presenting a talk on how to implement a watercolor brush using Core Image and OpenCL and maybe some duct tape. If you enjoy the graphics articles that I post here, you’ll probably enjoy my presentation. If not, I hear Steve “I’m Batman” Scott does a mean Adam West impression.

However, one of my frustrations with working with other app’s AppleScript interfaces was trying to figure out how the interface was intended to be used. Sure, the AppleScript Editor would show me all the actions and classes, but it isn’t always obvious how things are supposed to fit together. Something that would help in these cases is AppleScript recording. I could record the app performing the actions I cared about, then examine how the app itself used the actions and classes. Unfortunately, it seems like only the Finder and BBEdit ever got around to implementing AppleScript recording.

In the hopes of increasing the number of apps with AppleScript recordability, I’m going to document my approach to implementing it. For brevity, I’ll assume you’ve already an AppleScript interface implemented for your Cocoa app.

Thinking Big Design Thoughts

If you have an AppleScript interface for your application, you may think of your app architecture as something like this:

Here your AppleScript interface and graphical interface are independent peers, and both modify your model classes directly to accomplish your application’s tasks. Each interface is separate and largely ignorant of the other.

However, when implementing AppleScript recordability it is helpful to think about your app’s architecture in a different way:

In this case the GUI is dependent on, and implemented in terms of, the AppleScript interface. The general guideline is that anything the GUI does that mutates or alters the model goes through the AppleScript interface. However, if the GUI simply needs to access or get information from the model, it would go directly to the model, not through the AppleScript interface. Accessing the model can happen at seemingly random times to the user, and spamming the AppleScript Editor with these accesses when recording only confuses the user.

Suppose an application has table view and a button that deletes the currently selected item in that table view. The table view data source would be implemented the standard way, simply going directly to the model, bypassing the AppleScript layer. However, the delete button, since it alters the model, would be implemented by invoking the AppleScript delete command on the object represented by the current table row.

This design has some other benefits besides recordability. Notably it helps test your AppleScript interface design and implementation. If you find that implementing a GUI feature in terms of your AppleScript interface is impossible or difficult, congratulations, you found a bug! Also, merely testing your GUI also exercises your AppleScript interface. It is not a replacement for testing your AppleScript interface explicitly, but it certainly helps.

Implementation Hardships

Everything I’ve talked about so far hasn’t been all that novel, and probably has been met with large bucket fulls of “well, duh”s by anyone who’s ever looked into implementing AppleScript recording. The problem isn’t thinking about how to design in recordability, but actually implementing recordability.

As things stand now, doing something as simple as “invoking the AppleScript delete command on the object represented by the current table row” is incredibly involved and painful. You have to manually build up the AppleEvent that represents the delete command and the target model object using functions like AEBuildAppleEvent or classes like NSAppleEventDescriptor. Then you have to remember to target your app by specifying the kCurrentProcess process serial number (specifying kCurrentProcess as the ProcessSerialNumber is currently the only way to enable recording. Bundle identifiers, urls, and pid_t’s do not work.), and parse the AppleEvent you get back into something useful. You’d have to do this for every property or method on your model object you want exposed for recordability.

Dreaming of Ponies

The thing is, the Cocoa runtime has a lot of the AppleScript information from your SDEF file at its disposal and could theoretically generate these interfaces for you. In the ideal hypothetical situation, invoking the delete action via AppleScript inside your app could be as simple as:

// Suppose ONEmployee is our model object, with the appropriate AppleScript interface implemented
ONEmployee *employee = [_employees objectAtIndex:0];
ONEmployeeASProxy *proxy = employee.appleScriptInterface;
[proxy delete];

Here, any object that implemented the objectSpecifier method for AppleScript support would automatically get an appleScriptInterface property. The object returned by appleScriptInterface would be a proxy object implementing the same methods and properties as the original object. The proxy object would implement these methods by building up the appropriate AppleEvents, sending them, and parsing the resulting event back into a usable object.

Apple actually gets tantalizingly close to this with the Scripting Bridge. Outside users of your app can run your SDEF file through the sdp command line tool and get a nice Objective-C interface of proxy objects that build, send, and parse AppleEvents to and from your app. However, there is not currently a way tell these proxy objects to target kCurrentProcess, or to initialize one of the proxy objects by passing in a model object that implements objectSpecifier. (I’ve written this up as rdar://problem/7359646.)

Harsh Reality

Since I didn’t want to wait on Apple to extend the Scripting Bridge to make my life easier, I decided to write a couple of classes to help out. You can download the code here. The code is under the MIT license.

The classes work similar to the SBObject and SBElementArray classes in the Scripting Bridge framework. Using these classes, you can invoke the delete AppleScript method like so:

// Suppose ONEmployee is our model object, with the appropriate AppleScript interface implemented
ONEmployee *employee = [_employees objectAtIndex:0];
[ASObj(employee) invokeCommand:@"delete"];

The ASObj function creates an ASObject proxy object for any NSObject that implements objectSpecifier. invokeCommand takes care of marshalling the parameters into an AppleEvent, sending it, and unmarshalling the return value into an NSObject. The name of the command is the name of the name used in AppleScript, not the Cocoa implementation.

invokeCommand can take parameters, although it gets more tricky:

ONEmployee *employee = [_employees objectAtIndex:0];
[ASObj(employee) invokeCommand:@"giveRaise" with:[NSNumber numberWithInt:10], @"Percent", nil];

First, the parameters must be named (it’s not done by parameter order), and those names must match the Cocoa Key in the SDEF, not the user visible parameter name. Second, the marshalling code (from random NSObjects to AppleEvents) is a bit sparse. I’ve only added code for the types I needed for my project. If you use it, you may need to add support for other types. The same goes for return values; I only added support for the types that I use.

ASObject also has support for properties. For example this marks an employee as exempt:

ONEmployee *employee = [_employees objectAtIndex:0];
[ASObj(employee) setObject:[NSNumber numberWithBool:YES] forProperty:@"isExempt"];

The same type restrictions for parameters apply to properties as well. The Cocoa Key for the property must be used here, the same as parameters.

Elements also have basic support, which is where the ASElementArray comes in. Right now the only interesting thing to do with an element array is retrieve a reference to a specific element:

ONEmployee *employee = [_employees objectAtIndex:0];
ASObject *dependent = [[ASObj(employee) elementForKey:@"dependents"] objectAtIndex:0];
[dependent setObject:[NSNumber numberWithBool:YES] forProperty:@"insured"];

Unlike other methods, ASElementArray’s objectAtIndex does not execute an AppleEvents or otherwise take any actions. Instead it constructs an object specifier (i.e. an ASObject) for the given element.

The code is still somewhat rough and incomplete, but should help with anyone wanting to implement AppleScript recording. If nothing else, it should serve as a starting point or sample code for anyone rolling their own solution.