RFacebook Quick Start Guide for Rails

1. Install the gem and plugin

From the commandline, type:

$ gem install rfacebook

This will install the latest RFacebook core API client. Now, we want to install the plugin as well. From your Rails directory, type:

$ script/plugin install svn://rubyforge.org/var/svn/rfacebook/trunk/rfacebook/plugins/rfacebook

2. Configure facebook.yml

Now that you have everything installed, you need to set up your facebook.yml configuration. From your Rails directory, type:

$ rake facebook:setup

This will create config/facebook.yml. Just open the file and paste in your own API key and API secret (you need to get these from Facebook). You can ignore the tunnel configuration for now, but later on you should check it out.

3. Use the new features in your controllers and views

First, you'll probably want to require the user to login or install your application. You can use the RFacebook before_filters to do that (require_facebook_login or require_facebook_install):

before_filter :require_facebook_login

Second, your controllers and views have a new variable, fbsession, which represents the current user's Facebook session. You can call any Facebook API method using this session. The example below calls facebook.users.getInfo.

# make Facebook call
useridA = 1234
useridB = 9876
response = fbsession.users_getInfo(:uids => [useridA, useridB], :fields => ["first_name", "last_name"])

# now, parse the user elements to get the names
users = response.user_list
nameA = users[0].first_name
nameB = users[1].first_name

For more samples, check out the sample API calls page.

The plugin automatically makes Rails URLs relative to http://apps.facebook.com when it detects that you are inside the Canvas. This saves a lot of headaches, and lets you use Routes just like you always did (url_for, redirect_to, image_path, etc.):

redirect_to :controller => 'MyController', :action => 'myAction'
<%= link_to "Some Page", :controller => 'MyController', :action => 'myAction' %>
<img src="<%= image_path 'myImage.jpg' %>" />

Besides these extra features, you can still use regular Rails session and flash variables in the Facebook Canvas (supports PStore, ActiveRecordStore, DRbStore, and more!).

4. Stay up to date

RFacebook is being improved all the time, so be sure to check back for updates. To stay up to date, simply update your gem:

$ gem update rfacebook

...and update your plugin:

$ script/plugin update rfacebook

If you notice any problems with RFacebook, please file a bug. If you have suggestions or improvements, feel free to submit patches, or just ask me if you can join the project.