Basic setup and configuration

1. Twitter Application Settings

First of all, make sure that you have registered an application with Twitter at http://dev.twitter.com and that the application's type is "Browser" (not "Client"). Also, you will need to set a callback url that has no redirects on that page--if the url redirects the OAuth sequence will not work.

Also, if you would like tweeps who use your application to be able to update their status (i.e. send tweets) then be sure to set "Default access type" to "Read & Write" in the application settings.

2. Get Dependencies

Go to http://oauth.googlecode.com/svn/code/javascript/ and download:

a. oauth.js

b. sha1.js

3. Include and Initialize BirdHouse Class

Ti.include('birdhouse.js');

var BH = new BirdHouse({
    consumer_key: "yourappsconsumerkey",
    consumer_secret: "yourappsconsumersecretwhichislonger",
    callback_url: "http://yourappsEXACTcallbackurl.com" // only necessary for overridding
});

Note 1: you may have to tweak the path in birdhouse.js depending on where the file is placed.

Note 2: you can add the show_login_toolbar: false option to turn off the toolbar at the top when the authorization window opens.

4. Authorize or Make an API Call

You can call eight different functions:

• authorize: this initiates the authorization sequence, storing credentials in the app's directory in a file called 'twitter.config', returns void
• deauthorize: deletes the 'twitter.config' so the app no longer has the access tokens
• authorized: returns bool whether or not the user is authorized
• get_tweets: returns the last 20 tweets as an object (not as a string)
• tweet: opens a tweet dialog box optionally with the given text, sends the tweet upon hitting the "tweet" button, and returns the response from twitter, which will be the tweet itself, as an object (not as a string)
• short_tweet: same as tweet but has a third button called "Shorten" which shortens any URLs in the tweet
• shorten_url: returns a shortened URL
• api: sends an api call to the given url by the given method with the given parameters which should be in url form, i.e. "count=20&since_id=13343859", and then returns the evaluated response; the responses are evaluated by:

  return eval('('+XHR.responseText+')');
  

With any call, if the user is not authorized it will initiate the authorization process, thus, there is no need to initiated the authorization process before hand unless, for some reason, you wanted to get it out of the way. So, for example, to get the latest tweets,

var tweets = BH.get_tweets();

Note that with most of these functions you can send a callback function. Because the XHR requests will be completed AFTER the functions have already sent a return value, in order to tell whether or not an API request was made successfully, you will need to use a callback, such as:

BH.get_tweets(function(e){
    if (e===false) {
        // it failed
    } else {
        // it worked
    }
});