Facebook Helper API

Authors :
Dave Bauer (dave@solutiongrove.com)
Hamilton Chua (ham@solutiongrove.com)
Last Updated : 1/29/08
Version : 0.2d

Overview

The OpenACS Facebook Helper API package adds a layer of abstraction to the Facebook API to make it easier for OpenACS developers to write facebook applications using OpenACS.

The package is meant to be a service package and should not need to be mounted anywhere.

You will need to create a separate package to become your facebook application and use the TCL Api provided by the facebook helper api package.

Before attempting to create your facebook app we advise you to visit http://developer.facebook.com for a better understanding of how Facebook's api works.

In particular, the following links will be most helpful :

This helper api communicates with Facebook thru REST.

Quick Start Guide

Under the assumption that you already have the following :

  1. In acs-admin/apm, create a new singleton application package.
  2. Add two parameters to your new package,namely : ApiKey and secret.
    Both values for these parameters should be provided to you by facebook. They shall be fed to the TCL procs in order to be able to communicate with the Facebook web service.
  3. Mount your application in the admin/sitemap
  4. Fill up the ApiKey and secret parameters on the mounted application
  5. Create an index.tcl page with the following code ... 
    
ad_page_contract {
    
    A simple page that returns a list of friends in JSON format

} -query {
    {fb_sig_in_canvas ""}
    {fb_sig_added ""}
    {fb_sig_time ""}
    {fb_sig_user ""}
    {fb_sig_api_key ""}
    {fb_sig ""}
    {fb_sig_friends ""}
    {fb_sig_session_key ""}
    {fb_session_expires ""}
    {fb_sig_profile_update_time ""}
    {installed ""}
    {auth_token ""}
    {sent ""}
}

# check that we are passed an auth_token
#  an auth_token allows us to get a session_key from facebook
#  if auth_token is empty, it is most likely that we already have a 
#   session_key in fb_sig_session_key

if {$auth_token ne ""} {
    set session_info [facebook_api::get_session_from_token -package_key $package_key -auth_token $auth_token -url $app_url]
    set fb_sig_session_key [lindex $session_info 0]
    set fb_sig_user [lindex $session_info 1]
}

# check that we have an fb_sig_session_key
#  if we don't have this parameter it means that
#  the user didn't get here from facebook 
#  but rather directly
# ask the user to login or add the app

if { [exists_and_not_null fb_sig_session_key] } {

    set friends_info_json [facebook_api::get_friends_info -package_key "your_package_key" -session_key $fb_sig_session_key]
    ns_return 200 "text/html" $friends_info_json

} else {

    ad_returnredirect "http://www.facebook.com/add.php?api_key=$fb_sig_api_key"
    ad_script_abort

}
  6. In the above script, substitute your_package_key with the package_key of your new package. Substitute canvas_page_url with the Canvas Page URL value for your facebook application (See below).
  7. In the Facebook Developer Application, click Set Up New Application
  8. Enter a pretty Application Name.
  9. Fill up the Optional Fields.
  10. Change the Callback Url to the url of your openacs appication
  11. Make sure that you choose Use iframe.
  12. Click submit
  13. Your new application should now be listed under My Applications.
  14. Click on it to add your new application to your list of Facebook Applications.
  15. Click on the name of your application from your list of applications to launch your app
  16. The page should return JSON with your friends data.

Authenticating with Facebook

As of version 0.2d, the facebook api package has procs that allow you to do the following ....

For more information about authenticating with facebook refer to this page.

The facebook api package now has two new tables :

Authenticating with facebook is useful if you want to run a web application outside of the facebook user interface but still have access to data from facebook.