Back on my old post: “Ruby on Rails and Facebook API (Koala): Basic Example” there was a request for either sample code, or more detail. I’ve setup an app in Github: “Sample Koala Rails Test.”. You can get that code by putting the following on your server:
git clone git://github.com/banane/sample-koala-rails-app.git
Or, just read it online at GitHub. Please remove my app id and secret if you implement.
Important Step
Setup your Facebook app for local development on your computer. To do this, set the site_url to “http://localhost:3000/” (or whatever port you are running your Rails server).
1. Create your own Facebook app.
2. Copy the application id, secret, and url into the /config/initilizers/constants.rb file. Don’t use mine!
3. Run the server: “rails s”
4. Access in a browser http://localhost:3000
5. Click the “authenticate this app” button, and you will go through the authentication flow for gaining credentials to Facebook data, as a user.
6. The next view displays your recent statuses.
What’s going on?
Well, quite a lot, it turns out.
You’re setting up authentication between the Facebook server, your local application, and the user. It’s well explained in the Facebook Developer Authentication Guide, though written for PHP and JavaScript developers, mainly. What we’re doing is “Facebook Application” authentication, even though we’re not hosting it inside an iFrame on Facebook itself (which is totally possible, I just didn’t do it for simplicity’s sake).
First, we setup a Koala object
session[:oauth] = Koala::Facebook::OAuth.new(APP_ID, APP_SECRET, SITE_URL + '/home/callback')
Passing to it our Facebook application constants. We will use this session variable throughout the app.
Next, we derive a “authentication url”, and pass to it a string that represents the access we’d like to have. In this example, it’s “read_stream”- accessing the user’s statuses (chart of Facebook permissions).
@auth_url = session[:oauth].url_for_oauth_code(:permissions=>"read_stream")
Koala takes this information and creates an “auth_url”- a link to the Facebook auth services. We use this variable in our index.html.erb view, to direct the user to authenticate. Facebook checks the user to see if they’re logged in and already authorized for the app. If not, it leads them through a series of screens to explain and request permission. You noticed when we setup the Koala session variable “oauth”, that we included a redirect uri. This is where we want the user to land after authentication. In rails, it’s a controller/method combination. We’re sending them, in this example, to “home/callback.”
In the callback method, the authentication is still not complete. We receive a “code” in the GET string, which we send to the “oauth” session object.
if params[:code]
# acknowledge code and get access token from FB
session[:access_token] = session[:oauth].get_access_token(params[:code])
end
Koala sends this to Facebook (largely in the background) requesting the final token, the “access token.” Then, we send this access token to Koala object, which then enables us to use the Koala methods to retrieve data from Facebook.
We query the Facebook data with the “get_object” method, and pass to it two arguments, first the object (me) and the connection, “statuses.” It is well explained in Facebook’s description of the User graph object. Farther down you can read about the other available connections, and, you can query the data through the Explorer Tool – very handy.
@api = Koala::Facebook::API.new(session[:access_token])
@graph_data = @api.get_object("/me/statuses", "fields"=>"message")
The result is a hash, “GraphCollection.” I minimized the data result by setting the specific fields in “statuses” to return. That is the second argument in “get_object” method, “fields”=>”message”. This simplifies the code and speeds up the query.
Depending on how you want to build your app- using session objects or passing the “code” GET parameter around- depends on how you are hosting your app and various browser issues. Some opt for JavaScript session management, cookie, or re-authenticating with the Code element in the query string each time. This sample app is simply two views so it’s relatively simple.
Koala’s a great lightweight framework for Facebook. In this example, I’m using 1.3.0. This is how I created the sample:
1. Created a simple rails app, “rails new koalatest”
2. Added “”koala”,”1.3.0″ to the Gemfile, ran update bundle.
3. Created “constants.rb” file in /config/initializers, and updated with my new app id and secret.
4. Copied in the two methods- index and callback- from another app I have.
5. Added the two routes, and the root route.
6. Spent quite a bit of time futzing with CSS and the View (graphcollection isn’t very intuitive)
Enjoy, and if you have any questions please feel free to comment!
More reading
Realtime facebook updates with Rails, Koala, and Resque
Rails 3 Sample App
Developing Facebook Apps Using Koala