Under The Microscope

The Developer News Window

As our user base has grown over the years, the ability to handle problems rapidly has become increasingly important for us. Even a brief service outage or rare bug can cause hundreds of emails to come flooding in. While we have a large user base, our team is still small, so heading off problems with fast updates and useful communication is essential.

Unfortunately, with the advent of Apple’s App Store and the associated review processes, it’s become more difficult both to push out updates in a timely fashion and to communicate directly with our customers. We don’t have any way of knowing when (or even if) an update will ship through Apple’s App Stores to our customers, nor do we have any idea who those customers actually are!1

Even for apps outside the App Stores, getting in touch can be difficult. Only a small portion of users follow our Twitter feed, have Liked us on Facebook, or read this site. While we have a well-subscribed mailing list, emailing everyone about a bug which won’t affect most of them is likely to be more annoying than helpful, and still won’t reach all relevant users.

The fact is, regardless of where they purchased our software, most customers have no contact with us at all after purchasing. That’s generally just fine, but when an emergency arises, everyone prefers a direct line of communication.

A Solution

Because of this, we’ve rolled out some new infrastructure in our applications. We call it the Developer News window. After exploring many different ways to talk to our active customers, we finally realized the best way to do it was right in the application itself. By talking to users inside the application, we can reach them as they’re most likely to need the information we’re providing.

Here’s a screenshot of Piezo’s Developer News window, informing users of a critical update for Mac OS X 10.7.3 and up:

Dev News In Action
Breaking News

We’re certainly not the first to have the idea to publish news directly inside a software application. Nevertheless, it seems most applications don’t do it, and they’re often left scrambling because of it. Because so few apps seem to have implemented something like this, and because getting all the little things right takes a fair amount of effort, it’s worthwhile to talk about it in depth.

In Action

Since we started shipping Developer News in our apps many months ago, we’ve been fortunate to need to provide users with critical information just once, and everything worked exactly as designed. Specifically, users with Piezo on Mac OS X 10.7.2 were alerted to an issue before they upgraded their OS, and many opted to hold off for a few days until we could issue a fix. After that, users on Mac OS X 10.7.3 who had the broken version were alerted as soon as a working version was available.

Though we hope emergencies will be rare, we do plan to utilize Developer News again in the future. In the past when we’ve had a paid upgrade, we generally made a single mention of it in our version checking window, without ever actually offering to download the new version (as doing so would mean changing out the user’s licensed copy for an unlicensed one). This was not terribly effective.

Worse, when Mac OS X 10.7 was released, it killed the quite-out-of-date-but-still-popular Airfoil 3 entirely. We needed to get the word out to all Airfoil 3 users on Lion that their new OS required Airfoil 4. Making the best of a lousy situation, we opted for the first time to use the version update window (which had previously only ever offered free updates) to move users to a paid upgrade:

Airfoil 4's Update/Upgrade
This is best avoided.

The majority of users read this notice and upgraded without incident. However, plenty of users missed the note in red, and were thus angered to find themselves suddenly using a trial copy. As we had expected from the get-go, this proved to be a less than ideal way to get users up to date.

In the future, we’ll be able to use the Developer News window for alerting users when an old version simply must be updated, as well as displaying a notice once or twice when a major new upgrade is available.

Our Implementation

Much like the version checking found in nearly all apps outside the App Store, the Developer News system starts out by invisibly determining if there’s any news to display (the answer is almost always no; more on that later). To check, the application downloads a control property list on our web server, which looks like this:

<dict>
	<key>uuid</key>
	<string>news-2012-02-07</string>
	<key>displayLimit</key>
	<integer>10000</integer>
	<key>url</key>
	<string>https://rogueamoeba.com/piezo/ping/news.php</string>
	<key>checkInterval</key>
	<integer>86400</integer>
</dict>

The control property list contains a UUID of the current news item, a count of the number of times to display it, the actual URL of the item, and a time interval as to when to check again for new news.

The Display Limit is a significant variable, as some news items should display persistently while others need only be shown a single time. In the example above, the older version of Piezo was permanently broken, necessitating an update. As such, that news will be shown each and every time the broken version is launched. However, if we want to alert the user to news that’s important but not critical, we certainly don’t want to bother them by mentioning it more than once or twice.

The Check Interval is a little trick we came up with years ago when working on Nicecast. Anytime we have code that is polling a server, determining what an acceptable polling rate is can be difficult. Most of the time there is no news, and we want a slow polling rate to preserve both the users’ and our own network resources. But during times when we need to inform users of critical updates, using those resources to inform the customers sooner (by lowering the polling rate to hourly) is worth it for everyone involved. By putting the polling rate on the server, we can save resources while still providing fast updates.

When the Developer News system reads the control property list and determines that there is news to display, it prepares to fetch the News URL. While we could simply fetch the URL and display it to all users, we built the system to provide finer-grained control. For example, the Piezo news item shown above was only relevant to users on Mac OS X 10.7.3 – there was no reason to show it to others.

To facilitate this fine-grained display, the News system sends along some anonymous information to the web server.2 The web server then determines if the news it has is relevant, and only sends it down if so. This has to be designed and thought through very carefully ahead of time though. If tomorrow we had a bug that only affected Mac Mini users, we’d have no way of delivering the news to just them, as we aren’t sending MachineType data.

The content itself is simply displayed in a WebKit view. Since we don’t know in advance how big our news content is going to be, we even send down an extra HTTP header (X-Rogueamoeba-Windowsize) to set the dimensions of the window. We do the same for the window title (X-Rogueamoeba-Windowtitle). Having the full power of HTML provides us with a lot of options that sending a simple text-only message wouldn’t, including the ability to include images, links, forms, and more.

A Light Touch

Earlier, we mentioned that there will almost always not be news to display. This relates to our philosophy for using the Developer News window. We plan to use this window only after careful consideration, and to err on the side of not using it if we have another choice. It would be very easy to fall into the habit of using this window to convey all sorts of information, but we feel that would be a serious mistake. Users don’t want to be spammed inside of apps they’ve purchased, so the Developer News window is only for crucial information. Information about minor updates, other products, and most anything else belongs on Twitter, Facebook, or this weblog. These are places where users have opted-in to receiving additional information.

Conclusion

If you’re a developer, we definitely recommend you consider a similar setup for your own applications. The ability to get in touch with active users and provide them with critical information has the potential to benefit both you and your users, and it’s even more important given the disconnection from our customers the App Store can cause. Be conservative in how you use it, and sooner or later, both you and your customers will be pleased you were able to get in touch.


Footnotes:

1. Most App Store users know very little about how things work for developers, and generally they shouldn’t need to. It is worth being aware, however, that developers have no idea if you’ve purchased their software via the App Store, nor any way to contact you about your purchase. 

2. Specifically: the application version, OS version, and a flag indicating if this is an AppStore build or not. 

10 Responses to “The Developer News Window”

  1. Ben Hodder says:

    Great work as always guy! Hopefully I will get to see it in action dor something, Fission 2 I hope :D

  2. Dave M. says:

    I just want to make a plea to not give up on Snow Leopard support! There are some of us out here that can’t run Lion due to performance reasons and will never be able to run Mountain Lion due to hardware restrictions. I love AirFoil and want to keep using it, but if you guys stop supporting older OS’s, myself and many others won’t be able to enjoy this great software.

    Please, just remember that there are some of us out here that can’t upgrade our hardware like Leo Laporte does. We have to wait until we can afford it and being unemployed makes that wait even longer.

    Dave

  3. Adrian says:

    I’ve been using a similar system in Presence (flyingmac.com) for a few years now. It’s great for those rare emergencies and I agree its use should be sparing. I do use it to display release notes though.

    If you’re using preferences to record when a one-off news item has been displayed, ‘ware the guest user, whose preferences are deleted every logout. Someone has just reported that Presence’s news window displays every time the guest user logs in, since viewed items are never recorded.

  4. Paul Kafasis says:

    Ben Hodder: Thanks for the kind words. Fission 1 is likely to see it show a mention of Fission 2 in the next couple months!

    Dave M.: This seems like a rather off-topic request, but I’ll address it. We’ve always tried to support the current OS, and the one before it (so right now, 10.7, and 10.6). When 10.8 comes out, we won’t immediately drop support for 10.6, but it will start to be on the chopping block.

    But really, so what? For apps like Airfoil, you don’t need to have the latest to keep using it. Airfoil 3.5.7 is the last version for Mac OS X 10.5, and while it’s not as great as Airfoil 4, it still works well, and we still have a few 10.5 users buy it each week.

    In short, just because new versions no longer support an older OS doesn’t mean all is lost. Our Legacy page exists for a reason – to provide older, still working versions to folks on older OSes.

    Adrian: What’s the use case for showing release notes there, instead of in an actual update window? Built-in software update (via Sparkle or something homegrown) is pretty well-established now, and works well for the purpose of moving folks up to free newer versions. It seems like using a News window for this is likely to be a duplication. Or is it your only update method?

    Good to know on Guest Users, though I suspect that’s much more of an issue for your app than most!

  5. Peter Maurer says:

    @Paul: I don’t know about Adrian’s reasoning for showing release notes in the News window, but one of the reasons we do it in our News window (example: http://manytricks.com/sandbox/screenshots/news.png — no other earthshattering news there, because it’s 1.x) is to replace Sparkle. In our opinion, it’s nice to be able to list changes within the app even for App Store apps.

  6. Brent Royal-Gordon says:

    It’s especially critical to do this if you interface with any web services. I have an iOS app that talks to two external services that sometimes go down or subtly change their format without notice; eventually I made the app read a config file from my server with service URLs, data format parameters, and messages to show the user. When, like clockwork, one of the services started sending corrupt data after New Year’s Eve, I changed the service URL to point to a manually corrected version on my server, added a message indicating that some of the data would be a few days old, and answered all the support emails. A week later the corrupt data had cleared, and I switched back to the original version of the config file.

  7. Adrian says:

    @Paul: In Presence, release notes display after you’ve been informed of and have installed an update. To me it seems more sensible to say “here are the new features you’ve just installed – go and try them out” rather than “here are the new features – commit them to memory while you download and install the update, then go and try them out (if you haven’t forgotten what they are by then)”.

    I guess what Sparkle-style update notifications are really saying is “here are the new features – please install this update”. This perceived need to motivate the user makes sense to me if you’re trying to sell them a paid major upgrade, but less so for free updates. Updates contain new features and/or bug fixes – why *wouldn’t* you want those?

    But then, Presence is a bit different to self-contained apps – with multiple components communicating (Mac, iOS, central server) it has more need for you to stay up to date. Free upgrades aren’t really considered optional – if you persist with ignoring updates, eventually the version you have is considered too old and stops working.

    What really precipitated this though was that I wasn’t using Sparkle (and there were technical reasons for that), so I needed somewhere for release notes. The news mechanism – which I wanted anyway – was the obvious place.

  8. Paul Kafasis says:

    Peter Maurer: Interesting – are you then using the Mac App Store URL to open the Updates page? macappstore://showUpdatesPage

    It certainly makes sense to try to keep users aware of updates directly, instead of relying on them opening the App Store app. We’re steering clear of that for now, but I understand the rationale.

    Brent Royal-Gordon: Definitely – really, it’s not even just “web services” but any services you don’t entirely control. That includes the App Store, web services, and more.

    Adrian: Showing new features when they’re actually available makes sense, sure, but I’m not sure it makes sense to use a server-side data file to do that? It’s not in any way wrong, of course, but if that were the only thing you used a server-based News window for, it’d be a bit much. Having it in place now gives you an Emergency Broadcast system too, so that’s good.

    As for motivating users, it’s absolutely needed. Why wouldn’t a user want free updates? Because users unfortunately tend to figure that if it ain’t broke, don’t fix it.

  9. Peter Maurer says:

    @Paul: As of now, we don’t use that Mac App Store Updates URL yet, but that’s mainly because I had no idea it existed. It would definitely make sense to show that in cases where the running app version is older than the newest one shown in the change log.

    Now to find out if the macappstore URI scheme is officially supported by Apple. And I wonder whether what Jiulong Zhao says about sandboxing on Stack Overflow is true — although that’s irrelevant for most of our non-sandboxable apps.

  10. Dave M. says:

    Paul: Fair enough. I was actually thinking about bug fixes and such, but I do understand that it’s hard to keep track of several versions of a program, even with source control.

    I guess I’m just feeling left behind with 10.8 not supporting my 2006 Mac Pro. Apple needs to stop making such good hardware so that us users have a “good” reason to upgrade our hardware! :)


Comments for this post have been closed. Thanks for reading!