Improvements to Requests 2.0
By Derek Brandao
Requests are an important Social Channel for users to communicate with their friends from within apps. Coupled with the Open Graph updates announced at f8 last week, Requests continue to be a core part of how people share app activity with friends.
As part of the FBML deprecation, we will stop supporting our old request model and will no longer fix bugs on January 1, 2012. We highly encourage all developers to move to Requests 2.0 by this date. Today we're announcing several new features to Requests 2.0 to make the process of sending and receiving requests even more efficient for users and developers.
New features for Requests 2.0
We have heard repeated feedback from developers and users that requiring users to click ‘Send Request’ every time they wish to send requests to the same friends interferes with game play and limits sharing. To reduce this friction, we’re introducing frictionless Requests, which improves the experience for both users and developers.
Frictionless Requests enable users to send requests to specific friends from within an app without having to click on a pop-up confirmation dialog. Upon first sending a request to a friend from within an app, a user may authorize the app to send subsequent requests to the same friend without prompting for his permission. By default, the check box is checked. This removes a dialog from the flow and streamlines the process of sharing with friends.
To enable frictionless Requests you must initialize the JavaScript SDK with ‘frictionlessRequests:true’. You’ll send requests to users via the Requests Dialog just as before. As users share with friends, they may authorize the app to send future requests to specific friends on their behalf.
You can specify an array of user_ids in the ‘to’ field of the request dialog. Only if all of the user_ids are frictionless, the confirmation dialog will not display and the users will be notified of the request. If even one of the recipients is not frictionless, the confirmation dialog will be displayed and the user must press ‘Send Request’ for the requests to be sent.
Here’s a full JavaScript example for how to use frictionless requests.
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:fb="https://www.facebook.com/2008/fbml">
<head>
<title>Frictionless Request Example</title>
</head>
<body>
<div id="fb-root"></div>
<script src="http://connect.facebook.net/en_US/all.js"></script>
<p>
<input type="button"
onclick="sendRequestToOneRecipient(); return false;"
value="Send Request to One User"
/>
<input type="text" value="User ID" name="user_id" size=”50” />
</p>
<p>
<input type="button"
onclick="sendRequestToManyRecipients(); return false;"
value="Send Request to Many Users"
/>
<input type="text"
value="Comma Delimited List of Multiple User IDs"
name="user_ids" size=”50” />
</p>
<script>
FB.init({
appId : 'YOUR_APP_ID',
status : true,
cookie : true,
frictionlessRequests : true,
oauth: true
});
function sendRequestToOneRecipient() {
var user_id = document.getElementsByName("user_id")[0].value;
FB.ui({method: 'apprequests',
message: 'My Great Request',
to: user_id,
}, requestCallback);
}
function sendRequestToManyRecipients() {
var user_ids = document.getElementsByName("user_ids")[0].value;
FB.ui({method: 'apprequests',
message: 'My Great Request',
to: user_ids,
}, requestCallback);
}
function requestCallback(response) {
// Handle callback here
console.log(response);
}
</script>
</body>
</html>
Performance improvements
We have spent the past few months on rewriting the back-end for requests to make them faster to ensure users have the best experience with Requests 2.0. However in doing so, we ran into issues which require a breaking change to Requests 2.0 to make them more efficient.
To opt-into higher performance Requests 2.0 enable the migration “Requests 2.0 Efficient” in the developer app. This setting is available in the Advanced section of your app settings.
Setting the ‘Request 2.0 Efficient” in the app migration changes the format for request IDs in the JavaScript requests callback method.
Previously the response param that looked like:
{
request_ids: ‘request_id1, request_id2, …’
}
With the “Requests 2.0 Efficient” migration, the JavaScript request callback method now receives a response param like below to represent the changes to the request ids explained above:
{
request: ‘request_id’
to:[array of user_ids]
}
A request now has a single ID representing the actual request object and is then concatenated with the user_id to create the full request ID which represents the request for the specific recipient.
This prevents a developer from having to make a second GET request back to the Graph API to identify the recipients once a request has been sent. To construct the request ID for a user you concatenate as follows: ‘<request_object_id>_<user_id>’. Thus the request IDs from the example above would be:
150785095008591_499802820 180646335344553_499802852
To delete a request, the developer must issue an HTTP DELETE request to:
DELETE https://graph.facebook.com/[<request_id>_<user_id>]?access_token=[USER or APP ACCESS TOKEN]
Note: You can concatenate the request_id and user_id without doing the migration so that you can verify everything works before actually migrating.
Here is a full PHP sample which shows you how to concatenate the request_id and user_id in order to delete the outstanding requests for a user.
<?php
require_once('php-sdk/facebook.php');
$config = array(
'appId' => 'YOUR_APP_ID',
'secret' => 'YOUR_APP_SECRET',
);
$facebook = new Facebook($config);
?>
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:fb="https://www.facebook.com/2008/fbml">
<head>
<title>Deleting Requests Example</title>
</head>
<body>
<?php
$user_id = $facebook->getUser();
if ($user_id) {
//Get the Request Ids
$request_ids = explode(',', $_REQUEST['request_ids']);
//Construct full Request_Id
function build_full_request_id($request_id, $user_id) {
return $request_id . '_' . $user_id;
}
//For each Request construct full Request_id and Delete
foreach ($request_ids as $request_id) {
echo ("reqeust_id=".$request_id."<br>");
$full_request_id =
build_full_request_id($request_id,$user_id);
echo ("full_reqeust_id=".$full_request_id."<br>");
try {
$delete_success =
$facebook->api("/$full_request_id",'DELETE');
if ($delete_success) {
echo "Successfully deleted " . $full_request_id;
}
else {
echo "Delete failed".$full_request_id;
}
}
catch (FacebookApiException $e) {
echo "error";
}
}
}
//User TOS if user has not authenticated your App
else if (!isset($_REQUEST['error'])){
$params = array(
'redirect_uri' => 'http://localhost/~namitag/requests.php'
);
$loginUrl = $facebook->getLoginUrl($params);
echo
'<script>window.top.location.href="'.$loginUrl.'";</script>';
}
else {
echo ("user denied permission"); }
?>
</body>
</html>
Migrations and breaking changes
Starting today new apps will automatically be opted into “Upgrade to Requests 2.0” and “Requests 2.0 Efficient" and these migrations will no longer be available in the app settings for new apps. This requires developers to use the new request_id format as detailed above. In addition when a user is directed to your app, by clicking a Request from the app, the games dashboard, or from a Request notification, you must delete the request after it has been accepted. These are not automatically deleted once they have been clicked, thus it is the developer’s responsibility to clear them once they have been consumed. See sample above for how you can delete these requests.
In 90 days - on January 1, 2012- existing apps will be opted into “Requests 2.0 Efficient” and "Upgrade to Requests 2.0" migrations and all developers must ensure that they are using the correct request_id format and deleting requests appropriately.
We look forward to improved requests experience with frictionless Requests and our performance improvements. For more information reference our documentation here. Please provide feedback and thoughts in the comments below.
Get our newsletter
Sign up for monthly updates from Meta for Developers.