Game Requests

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 two 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 and asking for help.

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.

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, if they are not filtered. On mobile platforms, requests will surface within the list of notifications in the Facebook App, if they are not filtered. 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. However, invites that are sent by the player will appear on whatever combination of platforms supported by your game.

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, USER_ID'
}, function(response){
  console.log(response);
});

Multiple recipients can be specified via a comma-separated list containing User IDs.

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 accepts 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-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, 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-17T16: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-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

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

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.

Invite Notification in English

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.

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.

Request in App Center in English

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);

Best Practices

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.

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