<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Facebook Helper API</title>
<style>
body { font-family:arial; }.style1 {color: #000066}
.style2 {color: #666666}
.style3 {color: #999999}
</style>
</head>
<body>
<h1>Facebook Helper API</h1>
<p><b>Authors :</b>
<br>Dave Bauer (<a href="mailto:dave@solutiongrove.com">dave@solutiongrove.com</a>)
<br>Hamilton Chua (<a href="mailto:ham@solutiongrove.com">ham@solutiongrove.com</a>)
<br><b>Last Updated :</b> 1/29/08
<br><b>Version :</b> 0.2d
</p>
<h2>Overview</h2>
<p>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.
<p>The package is meant to be a service package and should not need to be mounted anywhere.
<p>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.
<p>Before attempting to create your facebook app we advise you to visit <a href="http://developer.facebook.com">http://developer.facebook.com</a> for a better understanding of how Facebook's api works.
<p>In particular, the following links will be most helpful :
<ul>
<li><a href="http://developer.facebook.com/step_by_step.php">http://developer.facebook.com/step_by_step.php</a>
<li><a href="http://wiki.developers.facebook.com/index.php/Main_Page">http://wiki.developers.facebook.com/index.php/Main_Page</a>
</ul>
<p>This helper api communicates with Facebook thru <a href="http://searchsoa.techtarget.com/sDefinition/0,,sid26_gci823682,00.html">REST</a>.
<h2>Quick Start Guide</h2>
<p>Under the assumption that you already have the following :
<ul>
<li>Facebook account
<li>You've added the <a href="http://www.facebook.com/developers/">Developer Application</a>
<li>Installed OpenACS and this package (Facebook Helper API) via acs-admin/install
</ul>
<ol>
<li>In acs-admin/apm, create a new singleton application package.</li>
<li>Add two parameters to your new package,namely : <b>ApiKey</b> and <b>secret</b>. <br>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.</li>
<li>Mount your application in the admin/sitemap</li>
<li>Fill up the ApiKey and secret parameters on the mounted application</li>
<li>Create an index.tcl page with the following code ...
<pre style="border: 1px dashed rgb(153, 153, 153); padding: 5px; overflow: auto; font-family: Andale Mono,Lucida Console,Monaco,fixed,monospace; color: rgb(0, 0, 0); background-color: rgb(238, 238, 238); font-size: 12px; line-height: 14px; width: 100%;"><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
}
</code></pre>
<li>In the above script, substitute <i>your_package_key</i> with the package_key of your new package. Substitute <i>canvas_page_url</i> with the <b>Canvas Page URL</b> value for your facebook application (See below).</li>
<li>In the Facebook Developer Application, click <b>Set Up New Application</b></li>
<li>Enter a pretty Application Name.
<br><img src='fbookdev.jpg'>
</li>
<li>Fill up the <b>Optional Fields</b>.</li>
<li>Change the <b>Callback Url</b> to the url of your openacs appication
<br><img src='fbookdev1.jpg'>
</li>
<li>Make sure that you choose <b> Use iframe</b>. </li>
<li>Click submit</i>
<li>Your new application should now be listed under <b>My Applications</b>.</li>
<li>Click on it to add your new application to your list of Facebook Applications.</li>
<li>Click on the name of your application from your list of applications to launch your app</li>
<li>The page should return JSON with your friends data.
</ol>
<h2>Authenticating with Facebook</h2>
<p>As of version 0.2d, the facebook api package has procs that allow you to do the following ....
<ul>
<li>Request for a session key outside of facebook</li>
<li>Authenticate against facebook on your OpenACS site or web application.</li>
<li>Store the session_key of a user for use in subsequent requests</li>
</ul>
<p>For more information about authenticating with facebook refer to <a href="http://developer.facebook.com/documentation.php?v=1.0&doc=auth">this</a> page.
<p>The facebook api package now has two new tables :
<ul>
<li><i>fb_users</i> - stores the uid, auth_token, session_key and session_expire parameters</li>
<li><i>oacs_fb_user_map</i> - mapping table for openacs user_id and facebook uid values</li>
</ul>
<p>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.
</body>
</html>