As soon as 3D Bookshelf is released, we’re planning on running a small promotional competition on twitter. In this post, I’ll briefly describe the architecture we put in place for managing the competition and providing a real-time view of the number of people who are participating.

Overview

There are many different ways to run a competition on twitter. Some companies have used hashtags to draw attention to their brand. Others use retweets to put their brand message in front of their followers’ followers virally. Each method has pros and cons associated with it.

For example, the hashtags method can work well because it allows the participant to tweet what they want so long as they include the hashtag. On the other hand, it means that a valid participant may well be tweeting about the competition owners’ brand in a negative way.

The approach we’re favoring at the moment is to require each participant to follow us and then tweet a specific competition message.

Management

Regardless of the competition method, participants must be identified and remembered so that at the end of the competition each participant has a fair chance of being chosen as the winner (or one of the winners). For the type of competition we’re favoring we have two choices. We can use the twitter search API to identify participants, or we can use the mentions timeline.

Using the twitter search API appears to be the best choice at first. It is subject to some limitations regarding the volume of results you can expect to receive. It is also subject to some date range restrictions. However, if it is polled often enough (within the rate limitations), these restrictions shouldn’t be a problem.

Using the mentions timeline is slightly more complicated in that you are required to implement a little more management code, but it offers more reliability in helping enumerate valid participants.

The reason the search API is less reliable is due to a known issue with the API. Apparently, this issue does not affect the mentions timeline. As described on the twitter web site, "if you post an @reply to a specific user, these will be delivered to that user. If we’re not experiencing issues, your account is public, your tweets have been posted for more than 24 hours, and you’re still not listed, your tweets have most likely been filtered out of our search index for quality reasons."

Implementation

To manage the twitter competition, we wrote a simple service that polls the mentions timeline and harvests valid participants. It remembers the last maximum TweetId encountered and only requests tweets back as far as this TweetId on subsequent requests. It also honors the rate limiting guidelines.

For each valid participant, we fire the participant details to a very simple local web service for storage in a database. The 3D Bookshelf website then requests the number of participants from this web service.

We deliberately decoupled the database access from the web site and service so that both of these components can talk a simpler language to the web service. This simplified both the web site and the service and also meant we only ended up with one ORM cache running behind the web service. It also made system testing and unit testing shorter and simpler.

Strategy

Having a reliable engine in the car is only half the battle. We’re learning as we go so we’re not sure what to expect, but we do know that without a good map for directions we wont get very far. In a follow up post, I’ll describe the strategy we’re working on to push the 3D Bookshelf twitter competition as far as we can.

Check back soon for more. Or, you can sign up to my RSS feed or follow me on twitter for updates.