Sinitter

Sinitter is a sinatra application to demonstrate the integration of Twitter OAuth via the twitter_oauth gem.

Live Demo

You can see sinitter running at http://sinitter.moocode.com/.

Local Setup

To run the application locally you’ll need to create a Twitter OAuth Application.

Once your application is setup you will have a consumer key and consumer secret. Create config.yml in the root of sinitter eg.

consumer_key: YOUR_CONSUMER_KEY
consumer_secret: YOUR_CONSUMER_SECRET
callback_url: YOUR_CALLBACK_URL

Grab the twitter_oauth gem:

sudo gem install twitter_oauth

Run:

./sinitter.rb

The application should now be available at http://localhost:4567/

Heroku setup

As in the local setup you will need to create a Twitter OAuth Application.

The demo application is already set up to run on Heroku so all you have to do is tell Heroku about your specific configuration. Assuming you have already pushed the application to Heroku, run the following:

heroku config:add CONSUMER_KEY=<your_consumer_key> CONSUMER_SECRET=<your_consumer_secret> CALLBACK_URL=<your_callback_url>

The application should now be running on Heroku.

Step-by-step

Firstly you need an instance of the Twitter OAuth API client with your credentials.

@client = TwitterOAuth::Client.new(
    :consumer_key => @@config['consumer_key'],
    :consumer_secret => @@config['consumer_secret'],
)

This client handles all the communication and authentication with Twitter. The next stage is to prompt the user to click something on your site that initiates the authorization procedure – imagine this is a link to /connect on your site, this is what the code might look like

get '/connect' do
  request_token = @client.request_token(
    :oauth_callback => ENV['CALLBACK_URL'] || @@config['callback_url']
  )
  session[:request_token] = request_token.token
  session[:request_token_secret] = request_token.secret
  redirect request_token.authorize_url  
end

We have just created a new request token and stored the details of the token in the session for when the user is returned to your site by Twitter. Then we have redirected to the authorize_url that will take the user to the Twitter site.

When you configure your application details on Twitter you have to specify a callback URL. In this example let us assume it is /auth

get '/auth' do
  # Exchange the request token for an access token.
  @access_token = @client.authorize(
    session[:request_token],
    session[:request_token_secret],
    :oauth_verifier => params[:oauth_verifier]
  )
  
  if @client.authorized?
    # Storing the access tokens so we don't have to go back to Twitter again
    # in this session.  In a larger app you would probably persist these details somewhere.
    session[:access_token] = @access_token.token
    session[:secret_token] = @access_token.secret
    session[:user] = true
    redirect '/home'
  else
    redirect '/login'
  end
end

Here we have retrieved the request token details from the session and asked Twitter to confirm the authorization, if this has all gone according to plan you will now have an access token for this user. The access token never expires (unless the user removes your aplication from their settings page) so you can use that in the future without having to do the authorization process again.

To start making authorized requests we can now create an instance of the API client with this users access token

@client = TwitterOAuth::Client.new(
  :consumer_key => @@config['consumer_key'],
  :consumer_secret => @@config['consumer_secret'],
  :token => session[:access_token],
  :secret => session[:secret_token]
)

Now we’re ready to call the API on behalf of this user. Here is an example action that updates the users status on twitter

post '/update' do
  @client.update(params[:update])
  redirect '/'
end

That’s it!