facebook.auth.getSession Now that you have an authentication token, you'll need to get yourself a session key for the current user. This key is passed to every other Facebook API call, to identify the user upon which your application is conducting an action.
Because we're not using a library provided by Facebook, we'll need to manually construct the HTTP query that we'll send to Facebook, and write some code to process the response. With every call, you must provide three required values, as described on the Facebook web site:
method- The first parameter is the method name. The method must be one of those exposed by the API documentation, or the API will return error code 3 (with message Unknown method).api_key- The vendor-specific API key corresponding to the site making the API call. This is the same key that we used in the login request, as provided to you when you registered your application.sig- The signature for the method call.
The signature is generated as described by this pseudocode:
args = array of args to the request, formatted in arg=val pairs
sorted_array = alphabetically_sort_array_by_keys(args);
request_str = concatenate_in_order(sorted_array);
signature = md5(concatenate(request_str, secret))
Rather than having to do this manually every time you need to perform an HTTP query, I've written a short do_facebook_request() function that is available for download. This takes the optional parameters that are to be sent for a specific API function, as well as the name of that function. It constructs and sends the request, then returns the result:
do_facebook_request.php
/**
* Sends an API request to Facebook
*
* @param array $parameters Array of parameters to send
* @param string $method The API function to call
* @return array Returns array of data returned
*/
function do_facebook_request($parameters, $method)
{
if (empty($parameters) || empty($method))
{
return false;
}
// Build Facebook args
// http://developers.f8.facebook.com/documentation.php?v=1.0&doc=auth
$data['api_key'] = 'API KEY';
$data['method'] = $method;
$data['v'] = '1.0';
// Loop through and set as array
foreach ($parameters as $key => $value)
{
$data[$key] = $value;
}
// Sort
ksort($data);
$args = '';
foreach ($data as $key => $value)
{
$args .= $key.'='.$value;
}
$data['sig'] = md5($args.'secret');
// Get a Facebook session
$response = do_post_request('http://api.facebook.com/restserver.php', $data);
// Handle XML
$xml = simplexml_load_string($response);
return $xml;
}
/**
* Sends a POST request with necessary parameters
* Code based on http://netevil.org/node.php?nid=937
* We use HTTP here. See http://uk2.php.net/manual/en/wrappers.http.php
*
* @param string $url The URL to perform the POST on. Include http://
* @param array $data The data to POST in array format
* @param array $optional_headers Any HTTP headers. See http://www.php.net/manual/sv/function.header.php or http://www.faqs.org/rfcs/rfc2616
* @param string $method The method for the request. Defaults to POST
* @return string The response
*/
function do_post_request($url, $data, $optional_headers = NULL, $method = 'POST')
{
// Just defining some parameters for the request here
// See http://uk2.php.net/manual/en/wrappers.http.php#AEN268663 for additional context options
$params = array('http' => array('method' => $method, 'content' => http_build_query($data)));
if ($optional_headers !== NULL) // Add in any additional headers
{
$params['http']['header'] = $optional_headers;
}
// Makes it easier to add additional parameters such
// as any optional HTTP headers as set above
$context = stream_context_create($params);
$fp = @fopen($url, 'rb', false, $context);
if (!$fp)
{
return false;
}
$response = @stream_get_contents($fp);
if ($response === false)
{
fclose($fp);
return false;
}
fclose($fp);
return $response;
}
?>
The code is part of a class I wrote for the welovelocal application, and is based on the code provided in Wez Furlong's blog. You'll need to replace the API_KEY on line 20 with your own key, as well as the secret on line 40 to generate the signature. The secret is a string generated by Facebook, and is displayed underneath your API key on the My Applications section of the Developer application within Facebook.
Here's an example in which we're calling the do_facebook_request function:
$xml = do_facebook_request(array('auth_token' => $token), 'facebook.auth.getSession');
After the request has been processed, the $xml variable will contain something that looks like this:
This is the session_key that you can store and use for all subsequent requests. See the auth.getSession documentation for detailed information.
The User Profile Box
Displaying contributed content as part of users' profiles is a great way for users to show off the work they've done on your web site. With welovelocal, we let people list their latest reviews on their profile, so that their friends can read what they've been writing. This concept could be extended for photos, news articles, game high scores -- almost anything, really.
Facebook uses its own subset of the HTML language to allow you to put rich content in a user's profile without opening security issues or destroying the layout of a site. This markup language is called FBML -- Facebook Markup Language -- and is well documented on the Facebook developer web site.
Pushing the content to a profile is very simple -- you generate the FBML within your code, then send it to the API, which makes the content live. The function is called facebook.profile.setFBML and requires you to provide both the session key we obtained earlier and the actual FBML you want to display.
Creating FBML is very straightforward and is well explained in the official documentation, so I won't go into any detail here. You can use the FBML test console to see a preview of what the output will look like.
Once you've written the FBML, you can use the do_facebook_request() function to send it to Facebook's API:
$xml = do_facebook_request(array('session_id' => 'idhere', 'call_id' => microtime(), 'markup' => $markup), 'facebook.profile.setFBML');
You'll notice a call_id as the final parameter that we passed to the do_facebook_request function. This is a unique ID for the request. Facebook recommends that you use the current time in milliseconds, which is available via the microtime() function.
And that's it -- the profile content will appear immediately!
News Feeds
The news feed in Facebook is a summary of everything that's going on with your friends -- it's something of a history of their interactions with the site. Through a friend's news feed, you can:
- find out what they're doing with status updates (like Twitter)
- learn who they've become friends with
- see when they've updated their profiles
... as well as almost anything else that happens to them on Facebook. I'm sure you'll agree that being able to post items to all of a user's friends is a great way to publicize activity that's occurring on your own web site.
You can publish a news item to the feed of a single user, or to the feeds of all the friends of a specific user. Next up, we're going to look at the latter task -- using the feed.publishActionOfUser function -- as this is the most useful for notifying people about things that are happening on your own site.
While the feed.publishActionOfUser function allows you to send up to four images (which is ideal for sites that use graphical content), to keep things simple, I'll keep this example to the simple task of sending text.
When sending a news item you must specify a title (max. 40 characters), but you can also optionally provide body text. The title will be displayed in bold, and the body text in regular paragraph styling. The body text is usually used to elaborate on the details contained in the title.
Facebook allows the use of certain tags in the title and body. These tags allow you to display context-sensitive information, such as the name of the user and a link to the profile. So, if I were to send the following request to post information to my friends:
It would show up as:
David Mytton (Network Name) wrote a new review.
My name would be linked to my Facebook profile, and the Network Name would be replaced with the network through which the person viewing the news feed knows me (for example, university name, club name, or the like).
To prevent spamming, Facebook imposes limits on the number of times you can send out news items. This is explained in detail in the developer documentation.
As we saw earlier, you can also use the do_facebook_request function to send out a news feed, like so:
$params['call_id'] = microtime();
$params['session_id'] = 'idhere';
$params['title'] = '
$params['body'] = 'Read the full review...';
do_facebook_request($params, 'facebook.feed.publishActionOfUser');
Spreading your Wings
We've touched on just a few of the key Facebook Platform functions in this article, but there are plenty of other features that you could utilize to push more content out to Facebook.
User Data - Documentation
Once you've authenticated the user, you can grab almost all of their profile data (though the data available may be limited depending on their privacy settings). Of course, one should use this data responsibly -- one approach that comes to mind is to use it to pre-populate a lot of the fields on your own site, to save the user having to enter the same data twice.
Events - Documentation
As any given user tends to connect with many friends on Facebook, the site is often used to organize social events. The Facebook API allows you to tap into this and return a list of all the events that a user can see, based on certain criteria. The criteria by which you can filter this data include start and end dates, and whether the user has indicated that they will attend the event.
You could use this feature to present a calendar to your users, so that they can plan other events around other commitments they have in place with their friends.
Groups - Documentation
Similar to the ways in which you can use events data, you can use the Facebook API to find out which groups a user belongs to, and retrieve a list of members of those groups. This could be useful to combine with the notifications API, for example, to send requests to all users in a group to join your web site. Of course, this approach could be seen as spamming, so you would definitely need to ensure that the content you broadcast is relevant.
Photo Uploads - Documentation
Facebook has over 60 million photos uploaded every week, and 160TB of photo storage is currently available, which makes it an extremely popular way to share photos. Using the API, you can:
- create a new album to store photos
- retrieve a list of the existing albums, to choose which one to upload photos to
- upload photos to the site
- retrieve photos from a specific album, or from all photos across the entire site to which the current user has access
This means that you could present a user with a list of their Facebook photos, and provide them with the ability to display them on your own site. They could also do the reverse: copy photos from your site to Facebook, thereby allowing all their friends to see them.
Summary
This article looked at some of the ways in which you can integrate your web site with Facebook. Whether you choose to utilize only one small aspect of the Web's fastest growing community, or embrace it with open arms, the Facebook API is a powerful tool both to enhance the experience for existing users, and to attract new users by driving traffic to your site.
Resources
No comments:
Post a Comment