Implementation
Game Requests are available for games on Canvas, iOS or Android. Requests appear on whatever combination of these platforms are supported by your game. For example, a player using the iOS version of your game could send a request to a player who plays on Canvas, and vice-versa. Hence, your implementation of requests should be platform-agnostic and should provide a consistent user experience, regardless of platform.
On all platforms, requests are sent via the Game Request Dialog, which is provided by the Facebook SDK for that platform. As described in the User Experience section, the dialog can be used to send a request directly to a specified recipient, or to display a multi-friend selector, allowing the sender to select multiple recipients for the request.
Configuring your app to send requests
Game Requests are only available to apps that are categorized as type Game. If your app is configured in any other category, it won’t be possible to launch the Game Requests Dialog.
In order for your app to send Game Requests, you need to configure the platforms that are supported. This will ensure that Game Requests can be delivered to recipients on all the platforms that your app supports.
Canvas Games
For Canvas games, configuration is simply a matter of adding Canvas as a supported platform in App Settings and providing your Secure Canvas URL. Once this is done, Game Requests sent to web recipients will appear in the recipients’ notifications on www.facebook.com.
iOS Games
If an iOS user receives a Game Request and doesn’t have your game installed, the notification will take them to the App Store to download your game. To ensure this works correctly, you need to supply an iPhone and/or iPad Store ID, and you need to ensure that both Single Sign On and Deep Linking are enabled for iOS under App Settings for your app.
Configuring your iOS platform settings to enable Game Requests.
While your game is under development, it’s common that you won’t have a Store ID that works. You can use any valid Store ID for testing, then change it to your live Store ID once you launch the game.
Android Games
When an Android user receives a Game Request and doesn’t have your game installed, the notification will take them to the Play Store to download your game. To ensure this works correctly, you need to supply a Google Play Package Name, and you need to ensure that both Single Sign On and Deep Linking are enabled for Android under App Settings for your app.
Configuring your Android platform settings to enable Game Requests.
While your game is under development, it’s common that you won’t have a package name that exists in the Play Store. You can use any valid package name for testing, then change it to your live package name once you launch the game.
Invoking the dialog
The Game Request Dialog is generated via the JavaScript, iOS or Android SDKs, Unity SDK, and by performing a browser redirect to a given URL. These examples assume the sender has already authenticated the app.
JavaScript SDK
Sending requests using the multi-friend selector provided by the Game Request Dialog:
FB.ui({method: 'apprequests',
message: 'YOUR_MESSAGE_HERE'
}, function(response){
console.log(response);
});
When the dialog is closed, the response object will contain the results of the send, including a requestid and an array of to recipients. For example:
{
"request":"1428237347457728",
"to":["10150002163885335"]
}
By default, the sender is presented with a multi-friend selector allowing them to select a maximum of 50 recipients.
Note: Due to URL length restrictions, the maximum number of recipients is 25 in Internet Explorer 7 or 8 when using a non-iframe dialog.
Sending requests to a specific recipient:
FB.ui({method: 'apprequests',
message: 'YOUR_MESSAGE_HERE',
to: 'USER_ID'
}, function(response){
console.log(response);
});
If the to field is specified, the sender will not be able to select additional recipients.
Sending requests to multiple specific recipients:
FB.ui({method: 'apprequests',
message: 'YOUR_MESSAGE_HERE',
to: 'USER_ID, USER_ID, INVITE_TOKEN'
}, function(response){
console.log(response);
});
Multiple recipients can be specified via a comma-separated list.
Note: There are restrictions on the maximum number of recipients you are able to specify via the ‘to’ field. Namely, fewer than 50 friends, and fewer than 26 friends on Internet Explorer 8 or below.
Sending requests to specific lists of friends:
FB.ui({method: 'apprequests',
message: 'Friend Smash Request!',
filters: [{name:'GROUP_1_NAME', user_ids:['USER_ID','USER_ID','USER_ID']},{name:'GROUP_2_NAME', user_ids: ['USER_ID','USER_ID','USER_ID']}]
}, function(response){
console.log(response);
}});
Sending requests explicitly stating an action and object:
FB.ui({method: 'apprequests',
message: 'Take this bomb to blast your way to victory!',
to: {user-ids},
action_type:'send',
object_id: 'YOUR_OBJECT_ID' // e.g. '191181717736427'
}, function(response){
console.log(response);
});
For turn based requests, do not specify an object_id.
FB.ui({method: 'apprequests',
message: 'Just smashed you 78 times! It\'s your turn.',
to: {user-ids},
action_type:'turn'
}, function(response){
console.log(response);
});
Alternatively, recipients can be divided into named lists, allowing the player to pick from logically-grouped friends based on their status in the game.
For more information, see the FB.ui reference documentation for the JavaScript SDK.
iOS SDK
FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
// Look at FBSDKGameRequestContent for futher optional properties
gameRequestContent.message = @"YOUR_MESSAGE_HERE";
gameRequestContent.title = @"OPTIONAL TITLE";
// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];
Sending requests explicitly stating an action and object using the iOS SDK:
FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
gameRequestContent.message = @"Take this bomb to blast your way to victory!";
gameRequestContent.to = @[@"RECIPIENT_USER_ID"];
gameRequestContent.objectID = @"YOUR_OBJECT_ID";
// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];
Android SDK
Sending a request via the Android SDK:
GameRequestDialog requestDialog;
CallbackManager callbackManager;
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
FacebookSdk.sdkInitialize(this.getApplicationContext());
callbackManager = CallbackManager.Factory.create();
requestDialog = new GameRequestDialog(this);
requestDialog.registerCallback(callbackManager, new FacebookCallback<GameRequestDialog.Result>() {
public void onSuccess(GameRequestDialog.Result result) {
String id = result.getId();
}
public void onCancel() {}
public void onError(FacebookException error) {}
});
}
private void onClickRequestButton() {
GameRequestContent content = new GameRequestContent.Builder()
.setMessage("Come play this level with me")
.build();
requestDialog.show(content);
}
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
callbackManager.onActivityResult(requestCode, resultCode, data);
Sending a request explicitly stating an action and object using the Android SDK:
private void onClickRequestButton() {
GameRequestContent content = new GameRequestContent.Builder()
.setMessage("Come play this level with me")
.setTo("USER_ID")
.setActionType(ActionType.SEND)
.setObjectId("YOUR_OBJECT_ID")
.build();
requestDialog.show(content);
}
For more information, see the guide to Sending Requests using the Android SDK.
Unity SDK
Here is how requests are done in the Unity SDK. Check the FB.AppRequest documentation for more details.
// For 1:1 requests
public static void AppRequest(
string message,
string[] to,
string data = "",
string title = "",
FacebookDelegate callback = null)
// For 1:N requests
public static void AppRequest(
string message,
List<object> filters = null,
string[] excludeIds = null,
int? maxRecipients = null,
string data = "",
string title = "",
FacebookDelegate callback = null)
Dialog Parameters
The Game Request Dialog can be created with a number of additional parameters that determine its behavior. These parameters are described below.
| Parameter |
Description |
Required |
| app_id |
Your app’s unique identifier. |
Yes |
| redirect_uri |
The URL to redirect to after a sender clicks a button on the dialog. Used for returning a sender to the game after sending a request. For security reasons, the redirect_uri specified must exist within the same root domain as the app’s Canvas page url. |
Yes when using the URL redirection method |
| to |
Either a user id,username or invite token, or a comma-separated list of user ids,usernames or invite tokens. These may or may not be a friend of the sender. If this is specified by the app, the sender will not have a choice of recipients. If not, the sender will see a multi-friend selector |
No |
| message |
A plain-text message to be sent as part of the request. This text will surface in the App Center view of the request, but not on the notification jewel |
Yes |
| action_type |
Used when defining additional context about the nature of the request.
Possible values are send, askfor, and turn |
Yes ifobject_idhas been set |
| object_id |
The Open Graph object ID of the object being sent. |
Yes ifaction_typehas been set to send oraskfor |
| filters |
This controls the set of friends someone sees if a multi-friend selector is shown. If left empty, the multi-friend selector will display all of the user’s Facebook friends.
By specifying app_users, the multi-friend selector will only display friends who are existing users of the app. This should be used when using requests for matchmaking.
Alternatively, by specifying app_non_users, the sender will only see friends who have previously not authenticated the app. This should be used when using requests for inviting new users to the game.
An app can also suggest custom filters as dictionaries withname and user_ids keys, which respectively have values that are a string and a list of user ids. name is the name of the custom filter that will show in the selector. user_ids is the list of friends to include, in the order they are to appear.
Note: On the iOS and Android SDKs only the app_users andapp_non_users filters are supported, as singular values. Dictionaries of these values are not supported. In addition, this parameter can not be used together with suggestions, using the two in the same dialog will result with an error. |
No |
| suggestions |
An array of user IDs that will be included in the dialog as the first suggested friends. Note: This parameter is available for mobile devices only and can not be used together withfilters. Using the two in the same dialog will result with an error. |
No |
| exclude_ids |
An array of user IDs that will be excluded from the dialog. If someone is excluded from the dialog, they will not appear in the multi-friend selector. Note: This parameter is not supported by the mobile SDKs and will be ignored. |
No |
| max_recipients |
An integer that specifies the maximum number of friends that can be chosen by the sender in the friend selector. This parameter is not supported on mobile devices. |
No |
| data |
Additional freeform data you may pass for tracking. This will be stored as part of the request objects created. The maximum length is 255 characters. |
No |
| title |
The title for the Dialog. Maximum length is 50 characters. |
No |
Response Data
When a request has been sent via the Game Request Dialog, a response will be passed to the callback containing the following information:
| Parameter |
Description |
| request |
The request object ID. To get the full request ID, concatenate this with a user ID from the to field: <request_object_id>_<user_id> |
| to |
An array of the recipient user IDs for the request that was created. |
Creating objects for requests
To send an object and action as part of a request, you’ll need to create an Open Graph representation of an in-game item that can be sent in requests.
Open Graph objects for requests can be created in the same way as objects for custom Open Graph stories. You can even re-use the same objects that you use in your stories if you’d like. However, you cannot use instances of the standard open graph types and must use your own custom open graph type.
It is a requirement that objects sent via requests need to be app-owned, so they are public for everyone to see.
You will need to set up a custom Open Graph object type, and an instance of that type, for each type of object you would like to use in a request. For example, if you are sending a bomb and a life, you will set up an Open Graph object type for bomb and another one for life, and create an instance of type.
To create a custom Open Graph type, follow the instructions in the “Creating Object Types” documentation.
Here is the object type for the bomb example used elsewhere in this guide. The only required properties are og:type and og:title.
The Open Graph object type page for a bomb in Friend Smash.
Other properties (image, description etc.) of the object instance are not used in requests. The information shown in the request is based on the object type’s name.
The Object Brower tool is an easy and fast way to create object instances.
Creating an instance of a bomb object type using the Object Browser
Accepting a request
When a recipient accepts a request, either through the notification jewel, the beeper popup, or App Center they will be sent to the Canvas Page URL of the app that sent the request. This URL will contain an additional GET parameter: request_ids, which is a comma-delimited list of request IDs that the user is enacting:
http://apps.facebook.com/[app_name]/?request_ids=[REQUEST_IDs]
It’s important to note that requests are not automatically deleted when a recipient accepts them. This is the responsibility of your app. A common approach is that when your game is launched, read from the Graph API the list of outstanding requests for that user and delete each one after processing.
Reading requests
Each request sent has a unique Request Object ID. This ID represents the request itself. This Request Object ID can be concatenated with a recipient User ID to create a specific instance of the request. The represents one instantiation of the request, which was sent to a specific recipient.
For example, when sending a request, the response from the Game Request Dialog looks like the following:
{
request: 'REQUEST_OBJECT_ID'
to:[array of USER_IDs]
}
If you look up the Request Object ID via the Graph API, the response you receive will differ slightly, depending on the viewing context of the lookup, but the response will always represent the entire request object.
For example, if a query to http://graph.facebook.com/<REQUEST_OBJECT_ID>?access_token=USER_ACCESS_TOKEN is made with the user access token of the recipient, you will see the following response:
{
"id": "REQUEST_OBJECT_ID",
"application": {
"name": "APP_DISPLAY_NAME",
"namespace": "APP_NAMESPACE",
"id": "APP_ID"
},
"to": {
"name": "RECIPIENT_FULL_NAME",
"id": "RECIPIENT_USER_ID"
},
"from": {
"name": "SENDER_FULL_NAME",
"id": "SENDER_USER_ID"
},
"message": "ATTACHED_MESSAGE",
"created_time": "2014-01-17T16:39:00+0000"
}
Note that both the “to” and “from” fields are returned. However, if the same endpoint is called using the access token of the sender, Facebook will return the following:
{
"id": "REQUEST_OBJECT_ID",
"application": {
"name": "APP_DISPLAY_NAME",
"namespace": "APP_NAMESPACE",
"id": "APP_ID"
},
"from": {
"name": "SENDER_FULL_NAME",
"id": "SENDER_USER_ID"
},
"message": "ATTACHED_MESSAGE",
"created_time": "2014-01-17T16:39:00+0000"
}
Note that the “to” field is now missing. The same response is returned if the call is made using an app access token, so: http://graph.facebook.com/<REQUEST_OBJECT_ID>?access_token=APP_ACCESS_TOKEN will return:
{
"id": "REQUEST_OBJECT_ID",
"application": {
"name": "APP_DISPLAY_NAME",
"namespace": "APP_NAMESPACE",
"id": "APP_ID"
},
"from": {
"name": "SENDER_FULL_NAME",
"id": "SENDER_USER_ID"
},
"message": "ATTACHED_MESSAGE",
"created_time": "2014-01-17T16:39:00+0000"
}
To get the full request that includes the recipient, you will need to append the recipient user ID following an underscore ‘_’ character. So for example:
http://graph.facebook.com/<REQUEST_OBJECT_ID>_<USER_ID>?access_token=APP_ACCESS_TOKEN
returns:
{
"id": "REQUEST_OBJECT_ID",
"application": {
"name": "APP_DISPLAY_NAME",
"namespace": "APP_NAMESPACE",
"id": "APP_ID"
},
"to": {
"name": "RECIPIENT_FULL_NAME",
"id": "RECIPIENT_USER_ID"
},
"from": {
"name": "SENDER_FULL_NAME",
"id": "SENDER_USER_ID"
},
"message": "ATTACHED_MESSAGE",
"created_time": "2014-01-17T16:39:00+0000"
}
Reading all requests
In order to read all the requests for a recipient for you can query the graph as shown below using the recipient’s USER ACCESS TOKEN. This will return a list of request ids for that user in the app.
GET https://graph.facebook.com/me/apprequests?access_token=[USER ACCESS TOKEN]
Deleting requests
As previously mentioned, Requests are not automatically deleted after they have been accepted by the recipient. It is the responsibility of the developer to delete the request after it has been accepted. Youmust delete requests on behalf of players once they have been accepted.
You can delete a request via the following methods:
Graph API
Issue an HTTP DELETE request to the concatenated request_id:
DELETE https://graph.facebook.com/[<REQUEST_OBJECT_ID>_<USER_ID>]?
access_token=[USER or APP ACCESS TOKEN]
JavaScript SDK
function deleteRequest(requestId) {
FB.api(requestId, 'delete', function(response) {
console.log(response);
});
}
Here is a full PHP sample that shows you how to concatenate the request_id and user_id in order to delete outstanding requests.
<?php
require_once('php-sdk/facebook.php');
$config = array(
'appId' => 'YOUR_APP_ID',
'secret' => 'YOUR_APP_SECRET',
);
$facebook = new Facebook($config);
//Assuming the user has already authenticated the app
$user_id = $facebook->getUser();
//get the request ids from the query parameter
$request_ids = explode(',', $_REQUEST['request_ids']);
//build the full_request_id from request_id and user_id
function build_full_request_id($request_id, $user_id) {
return $request_id . '_' . $user_id;
}
//for each request_id, build the full_request_id and delete request
foreach ($request_ids as $request_id) {
echo ("request_id=".$request_id."<br>");
$full_request_id = build_full_request_id($request_id, $user_id);
echo ("full_request_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";
}
}
?>
Rewarding the Sender
In efforts to incentive players to send requests, you can reward the sender based on certain actions the receiver performs as a result. For example, you can not reward players for simply sending requests, but if the receiver installs the game and reaches a certain level as a result of accepting the request, you are able to reward the sender. In order to do this, you will want to trace a request back to the sender to know who to reward. There are two ways to achieve this:
- Upon sending the request, store the request id returned in the response from the Game Request Dialog and match it upon receipt to reward the sender.
- Read all the requests for the receiver and reward the sender based on the ID in the “from” field.
Translating Requests
Requests can be translated and depending on the type of request, this is done by either Facebook or the developer. Please see the Translation Guide for Requests for details.
