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
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.
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):
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.first_name nameB = users.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!).
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.