Game Requests

Overview

Game Requests give players a mechanism for inviting their friends to play a game. Requests are sent by a player to one or more friends, and always carry a call-to-action for the game. Recipients can be existing players or new players.

Game Requests can be used to attract new players or to re-engage existing players. Requests can be sent in three scenarios:

1. The recipient is a friend of the sender and has not authenticated the game. This scenario is useful for invites.
2. The recipient is a friend of the sender and has authenticated the game before. This scenario is useful for turn-based notifications, gifting, and asking for help.
3. The recipient has authenticated the game but is not a friend of the sender. This scenario is useful for match-making.

Requests are sent while the sender is in-game and are surfaced to recipients in several places on Facebook. Requests are always private, and can only be seen by the recipient. While a single request can be sent to multiple recipients at once, the receiver of a request only ever sees details of the sender, and can never see either other recipients of the request.

%FB(devsite:markdown-wiki:image-card { src: "https://scontent-iad3-2.xx.fbcdn.net/v/t39.2178-6/12056965_1663935097214135_1022304374_n.png?_nc_cat=106&ccb=1-7&_nc_sid=34156e&_nc_ohc=n4eWynr0Ns8Q7kNvwHB9yoW&_nc_oc=AdmdXsUhYbeRdRJxd0pw0NlgsivED7876crD06zyk35-b-OYWbx-fjjLec5sr85eEKw&_nc_zt=14&_nc_ht=scontent-iad3-2.xx&_nc_gid=V1wus_3CFMZfr1vah9jRCw&oh=00_AfqyYe-zYICYOB__K-OfCSS5c1tFqpo-05R1O0MmoMeZxw&oe=69786B0A", caption: "An example Game Request surfaced on Facebook for Desktop.", })

Game Requests are available for Games on Facebook and for mobile games on iOS and Android. On the Facebook desktop site, requests appear as a beeper pop-up in the lower left of the screen as well as in the notifications jewel. On mobile platforms requests will surface within the list of notifications in the Facebook App. Request data is available through the Game Request API, and custom UIs can be built for a more integrated experience within mobile games. Your implementation of requests should therefore be platform-agnostic and should provide a consistent user experience, regardless of platform.

Launching the Request Dialog

The Game Request Dialog is generated via the JavaScript, iOS, Android, and Unity SDK. These examples assume the sender has already authenticated the app. If no recipients are specified, you can filter the list of friends to a limit of 50 friends or less, and you can segment by registered players or unregistered friends. This is useful for providing a separate flow for re-engagement or invitation.

JavaScript

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 request id 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.

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 containing a mix of User IDs and Invite tokens from the Invitable Friends API.

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 objects via requests, by explicitly stating an action_type and object_id:

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 Facebook SDK for JavaScript.

iOS SDK

Launching the Request Dialog using the friend selector provided by the 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_type and object_id to a specific recipient 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";
gameRequestContent.actionType = @"ACTION_TYPE";
// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

Android SDK

Sending a request using the Request Dialog friend selector 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);
}

Unity SDK

Here is how requests are done in the Unity SDK. Check the FB.AppRequest documentation for more details.

FB.AppRequest(
 message: "I Just got " + GameStateManager.Score.ToString() + " points! Can you beat it?",
 to: recipients,
 data: "{\"challenge_score\":" + GameStateManager.Score.ToString() + "}"
 title: "Friend Smash Challenge!",
 callback:appRequestCallback
);

Dialog Parameters

The Game Request Dialog can be created with a number of additional parameters that determine its behavior. These parameters are described below.

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:

Handling Requests In-game

Accepting Requests

When a recipient accepts a request on the Facebook desktop site, they will be sent to the URL of the game 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 accepting:

http://apps.facebook.com/[app_name]/?request_ids=[REQUEST_IDs]

Requests are not automatically deleted when a recipient accepts them. This is the responsibility of your game. 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.

When a recipient accents a request on a mobile platform, this will deep-link to the app. An additional parameter will be present in the loading of the app, the request ID. The same responsibility of accepting and clearing requests applies on mobile as well. It's a good practice to check and clear pending requests on game launch.

Reading requests

Each request sent has a unique Request Object ID. This ID represents the request object. 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月17日T16: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, or an app access token, 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月17日T16:39:00+0000"
}

To get the full request that includes the recipient using an app access token, you will need to append the recipient user ID following an underscore '_' character. So for example, a call to https://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月17日T16: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

Game 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. You must 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

function deleteRequest(requestId) {
 FB.api(requestId, 'delete', function(response) {
 console.log(response);
 });
}

Tracking Requests for referrals and rewards

You can reward the Game Request 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 reward the sender, you will need to know who to reward. There are two ways to achieve this:

1. When 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.
2. Read all the requests for a player when they've launched the game, and reward the sender based on the id in the from field of their requests. If multiple friends have invited a player, you can choose to reward the first or all senders.

Invitable Friends API

Facebook provides invite functionality through the Game Request Dialog, but experienced developers may want to build a custom friend selector that helps maintain their immersive game experience. The way to achieve this is by using the Invitable Friends API. { Info Box : This feature is only available to games with a presence on Facebook Desktop }

By querying the invitable_friends for a given user, Facebook will return a ranked list of the player's friends who have not yet played the game. The ordering of the list places people most likely to be interested in playing the game toward the top. This allows developers to construct a multi-friend selector with a customized look and feel, and target people who are most likely to respond positively.

Each entry on the list has information about the persons's name, picture and an invite token. The invite_tokens returned from this list can then be passed into the Game Request Dialog under the to parameter, in order to invoke Facebook requests to non-app friends.

Invites have the same behavior as Requests, and will direct recipients to one of the following places:

• Your game on Facebook.
• Your native app on iOS or Android, if installed.
• The Apple App Store or Google Play, if not installed.

The invitable_friends list is only available for games on Facebook.com and mobile games with a presense on Facebook.com. The scenarios in which the Invitable Friends API is available are enumerated below:

Invites that are sent by the player will appear on whatever combination of platforms supported by your game. Your implementation should be platform-agnostic and should provide a consistent user experience across devices.

Calling the Graph API

To access the invitable_friends list of the current player, you should use your platform's SDK to call the Graph API with the active user access token.

GET /v2.5/me/invitable_friends HTTP/1.1
Host: graph.facebook.com

and an example response:

The Graph API will then return a ranked list of objects which represent the current player's friends who haven't authorized the game. The list is given in order of relevance to the current player and game.

Example response:

{
 "data": [
 {
 "id": "AVkgK9fLFxasdvXNbDV_gYogR6lXa9SKLnH...",
 "name": "Anita Sujarit",
 "picture": {
 "data": {
 "is_silhouette": false,
 "url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-prn2/t1.0-1/c0.0.50.50/p50x50/1470158_10201991701127909_302023572_t.jpg"
 }
 }
 },
 ...
 {
 "id": "AVlzYTkXshfBqLe58zR9tY5dZ7L0wltTUkWKT0Z5V87zkwv-39...",
 "name": "Guy Cross",
 "picture": {
 "data": {
 "is_silhouette": false,
 "url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-prn1/t5.0-1/623782_622770420_2109148508_q.jpg"
 }
 }
 }
 ],
 "paging": {
 "next": "https://graph.facebook.com/v2.0/500535225/invitable_friends?limit=25&pretty=1&after=MTAxNTM5NjI0NDE5MjA2MzI=",
 "cursors": {
 "before": "NzM3OTE3Mzc2MjQ4ODkx",
 "after": "MTAxNTM5NjI0NDE5MjA2MzI="
 }
 }}

The default size of this list is 1000 objects. If there are more objects in the list, you can traverse the different pages using the next url on the paging object. You can also get a bigger or smaller list by setting the limit on the initial call.

However, as you go down the list, you can expect the recipients to be less likely to respond to an invitation. Facebook recommends therefore, that you construct an interface that showcases a smaller number of friends to invite.

If you want more control over the size of the images returned via this endpoint, you can make a nested request specifying a desired image size.

`GET /v2.5/me/invitable_friends?fields=name,picture.width(300)s HTTP/1.1
Host: graph.facebook.com`

You can read more on paging and limits, as well as making nested requests, on the Using the Graph APIreference document.

Invite Tokens

The invite token, returned on each of the friend objects as the value of a field named id, is a unique (per user and per game) string of variable length. The invite token is subject to expiration, and may change between game sessions. It is therefore not advisable to cache these results, or to try to assign them to a given person.

{
 "id": "AVlzYTkXshfBqLe58zR9tY5dZ7L0wltTUkWKT0Z5V87zkwv-39...", //Invite Token
 "name": "Guy Cross",
 "picture": {
 "data": {
 "is_silhouette": false,
 "url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-prn1/t5.0-1/623782_622770420_2109148508_q.jpg"
 }
 }
}

Inviting Friends

Each of the invite tokens can be used to invite the player's friends using the Game Request Dialog. After obtaining the tokens, you should build your own in-game friend selector dialog using the list returned by the Graph API.

Players should be able to select more than one friend to invite in this dialog, but no friends should be pre-selected by default.

After the player has selected their friends to invite and explicitly expressed their intention to invite them into your game (i.e. by clicking an "invite" button), you should make a call to show the request dialog.

To send an invite to the selected friends, populate the to parameter of the request dialog call with the friend's invite tokens. For example, assuming the player has selected one friend with the token shown below, you can make this call using the Facebook SDK for JavaScript:

var friend_ids = "AVlzYTkXshfBqLe58zR9tY5dZ7L0wltTUkWKT0Z5V87zkwv-39,
AVmT0LpyfvRMStEo2BW5seybtX1KbySRJtTb0wv0PqHVhT4sr7Le3,
AVk97lyKZQSXIJqOYJywIS3wR6gMo88tSF960l6m7Dm_j4";
FB.ui({
 method: 'apprequests',
 message: 'Come play Friend Smash with me!',
 to: friend_ids
 },
 function(){
 //handle result
 });

After making the call, you will receive a request_id that can be used to track how the invites perform for your game.

Permissions

Invitable Friends requires the user_friendspermission. As a best practice, you should always check the player's granted permissions before you make the Graph API call to get either the player's friends or invitable friends. You should also verify that the list that you receive has at least one friend on it, before showing your custom multi-friend selector.

Localization

To help you offer the best user experience for your global audience, Facebook supports localization for requests. Before you translate requests, it’s important to know the different types of requests and how they are surfaced. Requests can be seen as the standard "Anita sent you a request" or if an action/object pair is specified, "Anita asked you for a Life" or "Anita sent you a Bomb". There is also a turn request letting people know that it is their turn in a game versus their friend. All of those examples are seen by players that have authed the game. If the recipient doesn’t have the game installed, he will see the request in the form of an invite. For example, "Anita invited you to play Friend Smash!". Let’s take a look at how to translate each one of these.

Translating Invites

The text for an invite is automatically translated by Facebook and cannot be controlled by developers. It is translated into the language of the recipient.

%FB(devsite:markdown-wiki:image-card { src: "https://scontent-iad3-2.xx.fbcdn.net/v/t39.2178-6/12057240_1525113317809738_1129154907_n.png?_nc_cat=111&ccb=1-7&_nc_sid=34156e&_nc_ohc=GjEYP2Iqnz0Q7kNvwH1WBiX&_nc_oc=AdlSlGbmuEVv1Pa7_hAPA-V_El18RCDn0WKAkcF-OqxUPUUl-hQm6jMVeqTay9jsS8I&_nc_zt=14&_nc_ht=scontent-iad3-2.xx&_nc_gid=V1wus_3CFMZfr1vah9jRCw&oh=00_AfoLnnJrq7IskBWwvj4ShhZ3HlLA8dDJBy5MZ4Htth7eGw&oe=69785902", caption: "Invite Notification in English", })

%FB(devsite:markdown-wiki:image-card { src: "https://scontent-iad3-1.xx.fbcdn.net/v/t39.2178-6/12057243_1527140124274129_1527983129_n.png?_nc_cat=104&ccb=1-7&_nc_sid=34156e&_nc_ohc=C11zYiYElHEQ7kNvwHSRBug&_nc_oc=AdkoRTYF1hemuZcY9bIOxOk2Cmsyb0QMGb5pKa3PoMm8yXAFbitcp1O2btFTa3q27mY&_nc_zt=14&_nc_ht=scontent-iad3-1.xx&_nc_gid=V1wus_3CFMZfr1vah9jRCw&oh=00_AfoDGwtPwwkXyN4_66zrZTYEnR8Uq82pJXrNWcS0ubsK0Q&oe=697863EE", caption: "Invite Notification in Thai", })

Notice in the examples above that the text "invited you to play" is automatically translated into the other language, in this case Thai. The app name and description are translated in the "Localize" section of the app settings as "Display Name" and "Description", in the yellow boxes below.

%FB(devsite:markdown-wiki:image-card { src: "https://scontent-iad3-2.xx.fbcdn.net/v/t39.2178-6/12056955_1642868772667533_1269773212_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=34156e&_nc_ohc=9w2ZuO2Gz_4Q7kNvwHepAUl&_nc_oc=AdnvWWxtNxDZw-LuZr1XBpYYuv00pz2k03zv-cnLcmTkvb--iZJzx7xWvWjzeubKa44&_nc_zt=14&_nc_ht=scontent-iad3-2.xx&_nc_gid=V1wus_3CFMZfr1vah9jRCw&oh=00_Afo7vgfIXNgtXk3MociWNbi4AKKK-KchdLNtRv2O6L5_Yw&oe=69787AD7", caption: "Translating the App's Display Name and Description", })

Requests can also show up in the App Center. In the App Center, the "message" of the request is displayed. The message can be translated by the developer. In the examples below, the message is "Can I have a life to help me through the next level?" in English and "ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า" in Thai. Currently the main text for the request, "Anita sent you a request" is not shown in App Center.

%FB(devsite:markdown-wiki:image-card { src: "https://scontent-iad3-2.xx.fbcdn.net/v/t39.2178-6/12057216_545233832298569_1283274329_n.png?nc_cat=100&ccb=1-7&_nc_sid=34156e&_nc_ohc=RwiZUpcdY08Q7kNvwGe4g9r&_nc_oc=AdlC4GHg4V2-bPedo3mafm68IXTCYYlNxBliW3b2RC-2Qbd-Qkj5O9mawP6nfQVI60&_nc_zt=14&_nc_ht=scontent-iad3-2.xx&_nc_gid=V1wus_3CFMZfr1vah9jRCw&oh=00_AfqTG9u82Rh_N7ytMRvSz0eroqOl6iIAB4Tts7d08mDozg&oe=69786D0F", caption: "Request in App Center in Thai", })

%FB(devsite:markdown-wiki:image-card { src: "https://scontent-iad3-2.xx.fbcdn.net/v/t39.2178-6/12057065_342337352556705_39103913_n.png?_nc_cat=100&ccb=1-7&_nc_sid=34156e&_nc_ohc=jSDHdGd1rEEQ7kNvwFZIzrW&_nc_oc=AdkJnZdP4w57jL2jgtYJOyiuALsttMkwhb43XG9-CvAS1DgRtdCPyWsO91jgiyt-i0c&_nc_zt=14&_nc_ht=scontent-iad3-2.xx&_nc_gid=V1wus_3CFMZfr1vah9jRCw&oh=00_AfpnhyGDcIzIJAVJpNn0HVEholJ3YPEjZ6TcMk2nFHgDGg&oe=697879E2", caption: "Request in App Center in Thai", })

Translating the Message

Since the message is passed in as a parameter when the request dialog is invoked, you can translate this on your own before you invoke the request dialog and pass in the translated string as the message. If you want to change the translation dynamically, you should do so before you invoke the dialog. It is up to you to decide which language you would like to display as this will be the same text that the sender sees in the request preview and the recipient sees upon receiving the request.

Many developers detect the locale of the sender and then use that to determine what language to use as the message. They assume that in most cases the sender and recipient speak the same language. In the example above, you could look at the locale of the sender and if it was Thai, you could send in the string in Thai directly as the message, like this:

FB.ui({method: 'apprequests',
 message: 'ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า'
}, requestCallback);

Requests that have Action/Object pair

Requests that have an Action/Object pair specified are translated using our Translation Tools. These are the requests like "Anita asked you for a Life" or "Anita sent you a Bomb". Since these are Open Graph objects, the strings are translated in a similar way to Open Graph stories. These translations show up in both the request notifications and the home reminders.

If you do not have translations entered for a specific language, that request will be shown to the recipient as if it did not have an action/object pair since it's likely there will already be a translation available. This is a better user experience for the recipient to see the request in their language opposed to a more detailed request in a language they may not be able to read if there is no translation available which is the default English.

After you have set up your Open Graph object to use with Game Requests, you’ll go to the Translation Tool which can be found from the Localize section in the app configuration.

%FB(devsite:markdown-wiki:image-card { src: "https://scontent-iad3-1.xx.fbcdn.net/v/t39.2178-6/12056954_842106805907668_602114614_n.jpg?_nc_cat=108&ccb=1-7&_nc_sid=34156e&_nc_ohc=w7e0udbOCikQ7kNvwFQFENi&_nc_oc=Adm9PY4hVQy1Mx-Dvr4I-HFzpR_nXlIXclmKkj8Ewuw0AeDyVYGC1Q57-Kawi4SQxU0&_nc_zt=14&_nc_ht=scontent-iad3-1.xx&_nc_gid=V1wus_3CFMZfr1vah9jRCw&oh=00_AfrHBdRvEX_fsmiUgFcys9_qlVbkVdfBW1MEonLEanW46g&oe=697875A6", caption: "Translate Open Graph Stories button on Localize section", })

After you click on the "Translate Open Graph Stories" button, this will take you to the Translation Dashboard here. This is where you’ll be translating your phrases. However, you need to "Delete and Re-import" your strings first so that your strings for your new Open Graph object and request show up here. From this screen, click on the "Dashboard" tab.

In the "Dashboard" tab, you’ll see the ability to "Delete and Re-import" your strings. Click this link. Don’t worry, this will not remove all your previously translated strings. This will simply rebuild the phrases needed to be translated, and will include your new phrases for your request.

%FB(devsite:markdown-wiki:image-card { src: "https://scontent-iad3-1.xx.fbcdn.net/v/t39.2178-6/12057217_1656255224632115_1709562554_n.jpg?_nc_cat=101&ccb=1-7&_nc_sid=34156e&_nc_ohc=5iA9j4GXCVMQ7kNvwE20a0j&_nc_oc=Adnq4ijipV3BFIfSoZK95fmickg_vrFbDA1uDUQ9geCWo7bgmpA_rj5hwHNUMhuVR2A&_nc_zt=14&_nc_ht=scontent-iad3-1.xx&_nc_gid=V1wus_3CFMZfr1vah9jRCw&oh=00_AfrJrsLEHCus6GyK5-6gC9Fh7wwAw5nEyDeSXb9Bh8nA8g&oe=69785730", caption: "Translation Tool Dashboard", })

After you have "Delete and re-import all strings" clicked, go back to the Browse phrase tab and find all the strings related to your new object. Keep in mind that there are a variety of different phrases that go with it due to the number of different ways a request can be aggregated and show on Facebook. Go through each of the phrases related to your object and translate them.

%FB(devsite:markdown-wiki:image-card { src: "https://scontent-iad3-1.xx.fbcdn.net/v/t39.2178-6/12057216_809904939117967_512994393_n.png?_nc_cat=104&ccb=1-7&_nc_sid=34156e&_nc_ohc=11x-7cT4rtUQ7kNvwHlW6SP&_nc_oc=AdnQM1M8ccfCJyKh0XGO9w7H3W92LmQD8rfNgcK4VrGk3ba1jxH9wBvsyVRbhCsURl8&_nc_zt=14&_nc_ht=scontent-iad3-1.xx&_nc_gid=V1wus_3CFMZfr1vah9jRCw&oh=00_AfrGeBtbq4pTnZbRFfGaGyP2zKhQH1JcyR03PRdIAk53Bg&oe=69787715", caption: "Translation Tool Dashboard", })

Note that all of the translation is done in the Translation Tool for the object and action. There is no need to translate anything in the object’s description file’s meta tag information. All the pieces of the request in the notification and the home reminders, including the translations for the action, are done in the Translation Tool.

Turn Requests

Turn requests are used in turn-based games where each player is informing the other player that it is now their turn. These are translated through Facebook crowdsourcing and show up in both the request notification and home reminder. The amount of the string that is translated depends on how much has been successfully crowdsourced.

Advanced Topics

Using Frictionless Requests

You can streamline the process of sending requests by implementing frictionless requests. Frictionless requests allow players to send requests to specific friends from within an app without having to click a pop-up confirmation each time.

Upon first send to a friend, the player can allow subsequent sends to be sent to the same friends, without prompting for permission each time. This works especially well for turn-based games, where players can send requests for subsequent turns to their opponent without taking additional.

%FB(devsite:markdown-wiki:image-card { src: "https://scontent-iad3-2.xx.fbcdn.net/v/t39.2178-6/12057062_491433291027531_504725550_n.jpg?_nc_cat=103&ccb=1-7&_nc_sid=34156e&_nc_ohc=doFLyTk-y1oQ7kNvwHAf_Yd&_nc_oc=AdmS5Apy3f4wM6Lcb9GY7M4WVX-12Ewz_1Bj5k48hOPxpioCPF4y2PzARZcZOl36JRY&_nc_zt=14&_nc_ht=scontent-iad3-2.xx&_nc_gid=V1wus_3CFMZfr1vah9jRCw&oh=00_AfpHNosytMi8efJDpqpU2YrWSUssI8-tzcq1TU4-fEahpQ&oe=697871FF", caption: "Frictionless request dialog toggle", })

Frictionless requests are extremely easy to implement. Using the Facebook SDK for JavaScript, set the frictionlessRequests parameter in FB.init to true, as shown:

FB.init({
 appId : APP_ID,
 oauth : true,
 frictionlessRequests : true
});

On iOS, frictionless requests are implemented via the FBFrictionlessRecipientCache class, which maintains a cache of friends that can receive frictionless requests. Here we have a sample implementation of frictionless requests

First we need to add a FBFrictionlessRecipientCacheinstance to our call to FBWebDialogs presentRequestsDialogModallyWithSession:. TheFBFrictionlessRecipientCache object is used to cache details of our friend list and keep track of who we've previously sent requests to. First, let's add an instance of the FBFrictionlessRecipientCacheto our FacebookController class.

Go to FacebookController.h, and add the following item as a private static member of the class:

private:
static FBFrictionlessRecipientCache* ms_friendCache;

Now navigate to FacebookController.cpp, at the top of the file, above the first class method, our previously created CreateNewSession() method, add the following line to instantiate the recipient cache:

FBFrictionlessRecipientCache* FacebookController::ms_friendCache = NULL;

Then scroll back down to the SendRequest(const int nScore) method. Below where you define theNSMutableDictionary* params object, add the following code:

if (ms_friendCache == NULL) {
 ms_friendCache = [[FBFrictionlessRecipientCache alloc] init];}[ms_friendCache prefetchAndCacheForSession:nil];

This will create the FBFrictionlessRecipientCache object, if it hasn't already been initialised, and will prefetch and cache a list of frictionless friend recipients for the current session.

Finally, in the call to presentRequestsDialogModallyWithSession, which spawns the request dialog, add the friend cache to the final method parameter.

You should end up with code which looks like the following:

void FacebookController::SendRequest(NSArray* friendIDs, const int nScore){
 // Normally this won't be hardcoded but will be context specific, i.e. players you are in a match with, or players who recently played the game etc
 NSArray *suggestedFriends = [[NSArray alloc] initWithObjects:
 @"223400030", @"286400088", @"767670639", @"516910788",
 nil];
 SBJsonWriter *jsonWriter = [SBJsonWriter new];
 NSDictionary *challenge = [NSDictionary dictionaryWithObjectsAndKeys: [NSString stringWithFormat:@"%d", nScore], @"challenge_score", nil];
 NSString *challengeStr = [jsonWriter stringWithObject:challenge];
 // Create a dictionary of key/value pairs which are the parameters of the dialog
 // 1. No additional parameters provided - enables generic Multi-friend selector
 NSMutableDictionary* params = [NSMutableDictionary dictionaryWithObjectsAndKeys:
 // 2. Optionally provide a 'to' param to direct the request at a specific user
 [friendIDs componentsJoinedByString:@","], @"to", // Ali
 // 3. Suggest friends the user may want to request, could be game context specific?
 //[suggestedFriends componentsJoinedByString:@","], @"suggestions",
 challengeStr, @"data",
 nil];
 if (ms_friendCache == NULL) {
 ms_friendCache = [[FBFrictionlessRecipientCache alloc] init];
 }
 [ms_friendCache prefetchAndCacheForSession:nil];
 [FBWebDialogs presentRequestsDialogModallyWithSession:nil
 message:[NSString stringWithFormat:@"I just smashed %d friends! Can you beat it?", nScore]
 title:@"Smashing!"
 parameters:params
 handler:^(FBWebDialogResult result,
 NSURL *resultURL,
 NSError *error) {
 if (error) {
 // Case A: Error launching the dialog or sending request.
 NSLog(@"Error sending request.");
 } else {
 if (result == FBWebDialogResultDialogNotCompleted) {
 // Case B: User clicked the "x" icon
 NSLog(@"User canceled request.");
 } else {
 NSLog(@"Request Sent.");
 }
 }
 }
 friendCache:ms_friendCache];}

On Android, the option is in the control of the player whether or not they'd like to allow sending requests without a confirmation step. On the Android platform, the game client is unaware of this setting.

Sending Objects to Players

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 Browser tool is an easy and fast way to create object instances.

Building a Multi-Friend Selector

By constructing your own multi-friend selector, you can customize the look and feel of the experience to make it consistent with the rest of your game. Additionally, you can optimize the flow with any additional information you may have to surface friends who are the most relevant to your game.

If your game is constructed in Flash or Unity on the web, you may want to create a native multi-friend selector instead of using Facebook's web-based dialog. Similarly, creating a native flow on either iOS or Android will often be a smoother experience than the default Facebook implementation. For these reasons, the majority of top game developers on the Facebook platform choose to implement custom multi-friend selectors.

Appending data to a request

As mentioned in the Dialog Parameters section above, you are able to append up to 255 characters of additional data to send with the request. You can use this facility to either transfer additional information regarding the request, or append an identifier that you can use later to look up relevant information stored on your server.

As an example, in the Facebook sample game project Friend Smash, players take turns competing to 'smash' the highest number of friends possible. When one player sends a challenge to another, via a request, the data parameter is used to store the challenging player's latest score. The game then extracts this value for the receiving player, and makes it the target score for the next game.

Best Practices

Filter invites

When building a custom multi-friend selector, or otherwise choosing who to send requests to, consider providing filters to help the player choose their desired recipients.

A common filter used when implementing invites using the Game Request Dialog is the app_non_users filter. This filter prevents the Game Request Dialog from displaying people who have previously played your game. Other filters you may consider are players recently interacted with or players of similar games you control. For a full list of filters available, see the [#Anchor] Game Request Dialog - Parameters reference doc.

Create engaging mechanisms

Create engaging mechanisms for players when they visit their friends in game or interact with them directly. For example, if the game supports the concept of neighbors, grant bonus energy when players visit their neighbors' environments. If a player's base is attacked, let their friends help repair it. Players generally find value in helping their friends progress, and giving them opportunities to do so results in greater social experience and more people playing.

Make the object valuable to the player

Offer something that is valuable to the player that they can use to enhance their gameplay or social experience.

Segment players and offer requests in context

Evaluate your players and break them up into various groups that make sense for your game (e.g. new players, players that are doing crafting, players with lots of friends, engaged players, etc.). Think about what kinds of things would be useful to them at their level, and offer specific things to each segment.