Game Development On Facebook

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 specific friends, and always carry a call-to-action that the sender wants the recipient to complete. Recipients can choose to accept the request, or they can choose to ignore or decline it.

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, or other requests not sent to them.

Typically, games use Game Requests 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.

As of API 2.3 Game Requests will only be available to games. You can read the announcement here. Requests will remain available to all apps with API 2.2 until March 2017.

User Experience

This section illustrates how requests appear to both the sender and the recipient.

Send Experience

Game Requests are sent via the Game Request Dialog, which is invoked in-game via the Facebook SDK on iOS, Android and Canvas. Requests can contain a user-facing message as plain text, which is passed as a parameter when invoking the dialog, or they can contain specific information including in-game items and explicit calls to action.

Unless recipients are explicitly defined when the dialog is invoked, a multi-friend selector is shown allowing the sender to select friends to whom they want to send the request.

Game Request Dialog with no recipients specified on Canvas and iOS.

If your game interface has its own multi-friend selector, you can specify the recipients of the request as an additional parameter when invoking the dialog.

Game Request Dialog with a recipient specified, on Canvas and iOS.

In addition, you can specify multiple recipients at once, or suggest friends for the player to select as recipients.

Game Request Dialog with a multiple recipients specified on Canvas, and suggested on iOS.

Finally, on the Canvas version of the dialog, you can provide specific lists of recipients for the sender to pick from.

Game Request Dialog on Canvas with two lists of recipients specified.

You can add additional information to the request by specifying an action and an object. There are three possible actions, send, askfor, and turn. The send action maps to the gifting scenario and theaskfor action maps to the asking for help scenario. The turn action is for turn-based games. The objects used for the first two cases can be any in-game item. These scenarios are described underCommon Scenarios.

By adding an action and an object to a request, developers can bring game content out of the game and onto Facebook, giving new players increased context on the request when they receive it.

For example, instead of sending a generic request (“Anita sent you a request”), you can specify that the request is about asking for a life, or sending a bomb, and it will show up to the recipient with the additional context.

Sending a bomb to a friend in Friend Smash

Receive Experience

Requests will only surface on platforms where the game has been defined in the app dashboard as having a presence. So for example, if an app exists on iOS and Android, but has no Canvas presence, recipients will not see requests received via that app appear on the desktop web version of Facebook.com as notifications.

On the web, when a recipient receives a request they will receive a notification via the notification jewel on Facebook.com. Additionally, the bookmark counter for the game in the left hand menu will be incremented.

Requests as they appear in the notification jewel and bookmark counter

Requests may also show up in the Home Reminders section in the upper right hand corner of the main news feed home. If an action and object are specified, they will be shown here as well.

Home reminder section showing requests with, and without, actions and objects.

In addition, the App Center – Activity page will list the request. If the recipient is on Facebook.com when the request is received, they will see a ‘beeper’ notification in the bottom left of their current page.

Requests listed in App Center and a notification beeper for a new incoming request.

Accept Experience

A player accepts a request by clicking on the notification item or beeper, or by clicking Accept on the request item in App Center.

On Facebook.com, accepting the request will take existing players to the Canvas Page URL of the game from which the request was sent. New players will be sent to the App Center page for that game.

On iOS and Android devices, if the player has the Facebook app installed and push notifications enabled, they will receive a push notification alerting them to the request. The push notification will open the Facebook app and will display the request inside the notification jewel in a similar way to on desktop.

Accepting the request will direct the recipient to the app on their device if installed or to the appropriate location (Apple App Store or Google Play) to download the app otherwise.

Game Requests stack and appear in chronological order, much like a traditional email inbox. Requests are not automatically deleted when recipients accept them. It is the developer’s responsibility to ensure that requests are deleted after being accepted and consumed. This is discussed in more detail in the implementation section of this guide.

Common Scenarios

Some of the common use cases for Game Requests are described in more detail below.

Invites

Game Requests can be sent to a player’s friends who haven’t previously authenticated the game. Requests therefore serve as a primary method for players to invite their friends to join them. For developers, Requests function as an important channel for organic game discovery and acquisition.

Game Request Dialog with a list of friends to invite.

To query Facebook for a player’s friends who are not yet using your app, use the Invitable Friends API. The information you receive from this API can be coupled with the Game Request Dialog to send invites.

Players are great product advocates, so game invites are a great mechanism to drive distribution and increase awareness for a new game.

Further information on using Game Requests for invites in your game can be found in the Best Practices section of this guide.

Turn-based games

Turn-based games can use requests to great effect as a notification mechanism. When one player completes a turn they can send a request to their opponent prompting them to take their turn. This helps to keep players engaged with the game.

Turn based game sending a `turn` request
Turn based game using `turn` request to notify a player it’s their turn.

Match-making

Requests can be sent to any player that has already installed the game; the sender and recipient do not need to be friends. If a player wants to start a new game but none of their friends are active or available, the game can send a request to players who aren’t friends. As a developer, this lets you increase the pool of your app’s matchmaking system outside of the player’s social graph and works especially well for synchronous, real-time games.

Since requests from non-friends carry no social context, they are susceptible to higher decline rates and request blocking, so it is wise not to over-use Game Requests for this scenario.

Gifting and social trading

Gifts are typically lightweight virtual goods (energy packs, vanity items) that can be used to re-engage players who haven’t played your game in a while. Many games implement the feature such that players can easily accept pending gifts and send reciprocal gifts back to their friends. This creates a retention loop that encourages players to stay engaged in your game.

Pepper Panic Saga by King implements social gifting to keep players engaged.

For players, this provides an opportunity to assist friends and get things from each other to create a social experience among friends working together.

The bomb gift from our Friend Smash example in the User Experience section of this guide illustrates the ability to specify and show the gift in the request for the sender and the receiver.

Asking for help

When a player gets stuck in your game, they can use Game Requests to ask their friends for assistance by requesting specific items. Similar to gifting, this also creates an organic retention loop that encourages players to stay engaged in your game.

A player asking for help in Friend Smash

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:

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

Tracking and Improving Performance

In order to improve the performance (Click Through Rate) of your request, you can track and compare how each request is doing through Insights. For each tab, there is the ability to show by action or by object.

Action/Object Performance for Game Requests in Insights

You can also implement your own custom data tracking using some of the information stored with the request in the graph, namely action_type and object.

If you want even greater control over tracking, you can embed additional information in the data field. Simply add the data parameter with a string value when invoking the Game Request Dialog.

FB.ui({method: 'apprequests',
  message: 'Take this bomb and blast your way to victory!',
  to: 'RECIPIENT_USER_ID'
  action_type:'send',
  object_id: 'YOUR_OBJECT_ID',
  data: 'Friend Smash Custom Tracking 1'
}, function(response) {
    console.log(response);
}); 

The data field is always returned with the request information. In order to retrieve the action_typeand object fields in the request, you will need to explicitly ask for these fields in your query.

GET https://graph.facebook.com/<USER_ID>/apprequests?fields=id,application,to,from,data,message,action_type,object,created_time&access_token=APP_ACCESS_TOKEN
   {
      "id": "<REQUEST_OBJECT_ID>_<RECIPIENT_USER_ID>",
      "to": {
        "name": "RECIPIENT_NAME",
        "id": "RECIPIENT_USER_ID"
      },
      "data": "Friend Smash Custom Tracking 1",
      "message": "Take this bomb and blast your way to victory!",
      "created_time": "2013-11-09T23:05:39+0000",
      "action_type": "send",
      "from": {
        "name": "SENDER_NAME",
        "id": "SENDER_USER_ID"
      },
      "object": {
        "id": "YOUR_OBJECT_ID",
        "type": "YOUR_APP_NAMESPACE:bomb",
        "title": "Bomb",
        "updated_time": "2013-10-25T17:37:29+0000",
        "created_time": "2013-10-25T17:37:29+0000",
        "application": {
          "id": "YOUR_APP_ID",
          "name": "Friend Smash!",
          "url": "http://www.facebook.com/apps/application.php?id=YOUR_APP_ID"
        },
        "is_scraped": false
      },
      "application": {
        "name": "Friend Smash!",
        "namespace": "YOUR_APP_NAMESPACE",
        "id": "YOUR_APP_ID"
      }
    }

If you do not need all the information in the object returned with the request, you can limit your call to return only the object.id.

GET https://graph.facebook.com/<USER_ID>/apprequests?fields=id,application,to,from,data,message,action_type,object.id,created_time&access_token=APP_ACCESS_TOKEN

For your own data tracking, it may also be helpful to know how the recipient of the request saw the request. For example, when the requests that have action and object are aggregated in the notifications, only the most recent object is explicitly detailed out, while the other requests are aggregated together (“…and other requests”).

This information can be extracted from the content URL parameter on the request. It will be passed in the format content=ACTION_TYPE:OBJECT_ID, where ACTION_TYPE and OBJECT_IDcorrespond to the action_type and object_id parameters set when invoking the Game Request Dialog.

https://apps.facebook.com/friendsmashsample/?fb_source=notification&request_ids=601174626623131,235483369959425&ref=notif&app_request_typ=user_to_user&content=send:55728546344483&notif_t=app_request

Best Practices

The documentation above gives a basic technical overview of requests, and how to implement them into your product. Below are some common best practices that help to take full advantage of the requests channel.

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

Frictionless request toggle on the web dialog.

Frictionless requests are extremely easy to implement. On the web, simply include thefrictionlessRequests parameter in FB.init and set it to true, like this:

    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. For an example implementation, please see the iOS Games Tutorial – Frictionless Requests. For a complete reference of the class and its use, please see iOS Reference – FBFrictionlessRecipientCache.

This is especially effective for Canvas, mobile web and iOS games as the request notifies the recipient across all of their devices, which creates a seamless cross platform experience. For more information on how requests work across platforms, read Building a Cross-Platform Game.

Frictionless requests only apply to requests, not invites. Once the friend installs the game, requests will be frictionless. The user_friends permission is also required.

Append 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. This is fully documented in the Canvas Games Tutorial.

Create a custom 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.

Custom multi-friend selector implemented in King’s Farm Heroes Saga.

For more information about how to construct a custom multi-friend selector, please see the dedicatedMulti-friend Selector documentation, and the Invitable Friends API.

Create prominent invite buttons

Make sure that the invite buttons are prominent within your interface. Players should never have to hunt to invite their friends. Most successful social games include an option to invite friends within their main screen, letting players invite their friends at will. Another common strategy is to maintain a friend bar that showcases a player’s friends and their current status in the game. That bar could be a leaderboard, neighbor list etc, and it generally should include a button to let a player invite their friends directly.

Prominent invites in Nordeus’ Top Eleven.

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

Prompt appropriately

Prompt highly engaged players during low activity areas of the game (such as, when loading screens) and asking them to invite their friends. If players are enjoying the game, periodically prompt them to invite more friends, but be mindful to not interrupt their experience.

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.

Optimize your requests

As mentioned in earlier sections, when players are able to see the contents of the requests, they are able to make a more informed decision about which requests they want to click on and when. This is a better user experience and you can optimize your requests by doing the following:

Specify the action and object

This will show the player what the contents of the request is before they click on it.

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. Offer specific things to each group.

Track and optimize

Implement your own tracking and monitor to iterate and optimize.

You can also take a look at games in your genre for ideas on how others are using requests

Source taken from facebook.com