Today I wanted to call out one of the more interesting projects happening on Titanium Desktop, and show how you can leverage its core library in your own Titanium Desktop projects. The Spaz microblogging client is one of the most popular open source Twitter (and StatusNet and Identi.ca) clients available today, and developer Ed Finkler (follow him on Twitter here) is leading the Spaz project in a port of the desktop version from Adobe AIR to Titanium Desktop, and to eventually bring Spaz to iPhone and Android handsets via Titanium Mobile.

With the Spaz project already running on the desktop and webOS platforms, Ed wisely decided to separate out core logic into a centralized library which he calls Spazcore. Spazcore has many useful features which you can use today in your Titanium Desktop applications, not least among them a facility for making xAuth authenticated requests to Twitter through a nice JavaScript API.

If you haven’t tried implementing xAuth (or oAuth) in your applications, SPOILER ALERT: it’s not trivial. xAuth is a much better fit for desktop and mobile applications, since you are able to skip the browser re-direct song and dance and exchange a username and password for a token that you will use to authenticate subsequent requests. xAuth uses the same header information and request signatures used by oAuth, however, so you still have a fair amount of work to do as the developer to sign your API requests properly. Luckily for us, Ed has figured this out already and abstracted it out into Spazcore, so we can very quickly and easily create a desktop application which uses xAuth for authenticated access to Twitter.

Your first step is to create a Twitter application at dev.twitter.com and request xAuth permission from Twitter, a process described on their developer site here. Essentially, you will send an e-mail to the Twitter team providing information about your application (I had to provide some screenshots for one app as well). After a day or two, you will be notified that your app has been blessed to access Twitter via xAuth.

Next, create a Titanium Desktop application to test out your new Twitter xAuth creds. After your project is created, you’ll need to grab the JavaScript dependencies you’ll need for Spazcore, including the library its self and a version of jQuery, upon which Spazcore currently depends. If you’re running a system that has curl available on the command line (like OS X or many Linux distros), fire up a terminal window, navigate to the Resources directory of your new Titanium Desktop project, and execute the following commands to quickly download the necessary dependencies (or just download these files and manually copy them):

curl http://code.jquery.com/jquery-1.4.2.min.js > jquery-1.4.2.min.js
curl -L http://bit.ly/spazcore-tutorial > spazcore.js

As always, we have a Gist available here which implements a simple index.html you can drop in to your new project to see Spazcore authentication in action (the complete example, adapted from Ed’s Spazcore examples is embedded below the tutorial). I’ll quickly illustrate some of the high points of the Spazcore API:

Spazcore configuration and dependencies

After including the jQuery and Spazcore libraries via standard script tags in the head of your HTML document, we will declare some global variables that we will use when creating an authenticated Twitter session:

// Include Twitter configuration - your keys must be approved for xAuth.
// More info: http://dev.twitter.com/pages/xauth
var SPAZCORE_CONSUMERKEY_TWITTER = 'consumerkey';
var SPAZCORE_CONSUMERSECRET_TWITTER = 'consumersecret';

Adding the Twitter service to Spazcore

The next step is configuring Spazcore to use our oAuth credentials for a connection to Twitter:

SpazAuth.addService(SPAZCORE_ACCOUNT_TWITTER, {
  authType: SPAZCORE_AUTHTYPE_OAUTH,
  consumerKey: SPAZCORE_CONSUMERKEY_TWITTER,
  consumerSecret: SPAZCORE_CONSUMERSECRET_TWITTER,
  accessURL: 'https://twitter.com/oauth/access_token'
});

Creating an authorization “pickle”

As we mentioned before in our brief discussion of oAuth/xAuth, we are essentially exchanging a username and password combination for a token (or set of tokens, more accurately) that we can use to sign requests to to the oAuth provider (in this case Twitter) for subsequent requests for protected data (or to create/modify data on behalf of the user). Spazcore simplifies this process for us by accepting a username and password from our application, and allowing us to save our set of tokens as a simple string (called a ‘pickle’) that we can use for future authenticated requests:

var auth = new SpazAuth('twitter');
 
// result is a boolean indicating success of the auth request
var result = auth.authorize('someusername', 'somepassword');
 
// You can save this authenticated session in an authPickle string
// which contains access token information, not the actual username
// and password combo, for later requests.
var authPickle = auth.save();

Do the Twitter!

With an authorized token all set up, we are now ready to talk to Twitter. To do this, we will create an instance of an object called SpazTwit, which implements an API we can use to execute various functions against Twitter. There aren’t any docs for SpazTwit that I could find (read on after the tutorial to see how you can help with that), but you can inspect the API in the source code (which is commented well enough to get the gist of what’s going on). The SpazTwit implementation starts at about line 11122 of the uncompressed Spazcore library I had you download – the interesting bits for the external API start getting added to the SpazTwit prototype at about line 116356. In the example below, we will grab the home timeline (which would normally appear on the web at http://twitter.com/yourusername):

// Load OAuth from the serialized string we got earlier 
// (or maybe we saved it in a database or property):
var auth = new SpazAuth('twitter');
auth.load(authPickle);
 
//Create a SpazTwit instance with the auth data we have
var twit = new SpazTwit({'auth':auth});
 
//Make a Twitter API call!
twit.getHomeTimeline(null, 200, null, null, function(timeline) {
  //do something with the results of this call
}, function() {
  //do something if there is an error!
});

Here is the full example in action:

Give Back!

Ed, like every good, long-suffering open source maintainer, does a lot of the heavy lifting for Spaz himself and could use your help. If you end up using Spazcore, please consider contributing either source code, documentation, or moral support to Ed as he continues his development efforts. Like us at our own #titianium_app channel, Spaz contributors and users often hang out on IRC at irc.freenode.net in the #spaz channel. Here are some of the other places where you can find further information on the Spaz/Spazcore project, and hopefully help out yourself:

• How To Contribute
• Developer Tasks and Milestones
• Mailing List
• End User Support
• Ed’s GitHub account, home of all Spaz projects

Also, you can reach out to Ed directly and follow his exploits on Twitter. As promised, the fully functional example app is included below. Big thanks to Ed for this library, and hopefully it will be of use on your next Titanium Desktop project!