游戏请求

游戏请求为玩家提供邀请好友一起玩游戏的机制。玩家可以向一个或多个好友发送请求，而且请求始终包含游戏行动号召。接收方可以是现有玩家，也可以是新玩家。

游戏请求可用于吸引新玩家，或重新吸引现有玩家。在下面两种情况下可以发送请求：

1. 接收方是发送方的好友，而且尚未验证游戏。这种情况适合使用邀请。
2. 接收方是发送方的好友，而且之前已验证游戏。这种情况适合使用回合制游戏通知和寻求帮助。

发送方可在游戏内发送请求，而接收方可在 Facebook 中的多个位置看到该请求。请求始终是私密的，只有接收方才能查看。虽然发送方可以一次性向多个接收方发送请求，但接收方只能查看发送方的详情，而不能查看其他接收方。

在桌面版 Facebook 中显示的游戏请求示例。

游戏请求适用于 Facebook 游戏，以及 iOS 和 Android 移动游戏。在 Facebook 桌面版网站上，如果未进行筛选，请求会以蜂鸣式弹出窗口在屏幕左下方以及通知图标中显示。在移动平台上，如果未进行筛选，请求会在 Facebook 应用的通知列表内显示。您可以通过游戏请求 API 获取请求数据，并且构建自定义用户界面，以便在移动游戏中打造更加整体化的体验。因此，实施请求时不应该区分平台，而是应该在所有平台上提供一致的用户体验。但是，玩家发送的邀请会在游戏支持的所有平台中显示。

启动请求对话框

游戏请求对话框通过 JavaScript、iOS、Android 和 Unity 版 SDK 生成。以下示例假设发送方已验证应用。如果没有指定接收方，您可以筛选好友列表，将人数限制为 50 个好友或更少，并且可以按注册玩家或未注册好友进行细分。这有助于分别提供流程来重新吸引老玩家或邀请新玩家。

JavaScript

使用游戏请求对话框提供的好友多选工具发送请求：

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE'
}, function(response){
  console.log(response);
});

关闭对话框后，response 对象会包含发送结果，其中包括 request 编号以及一组 to 接收方。例如：

{
  "request":"1428237347457728",
  "to":["10150002163885335"]
}

在默认情况下，发送方可看到好友多选工具，以便选择最多 50 个接收方。

向一个特定接收方发送请求：

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID'
}, function(response){
  console.log(response);
});

如果指定了 to 字段，发送方将无法选择其他接收方。

向多个特定接收方发送请求：

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID, USER_ID, USER_ID'
}, function(response){
  console.log(response);
});

可通过包含用户编号的逗号分隔列表指定多个接收方。

向特定好友列表发送请求：

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

以明确指定 action_type 和 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);
});

对于回合制游戏请求，请勿指定 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);
});

此外，您也可以将接收方划分为不同的命名列表，方便玩家根据好友的游戏状态，从这些逻辑分组中挑选好友。

详情请参阅 JavaScript 版 Facebook SDK 的 FB.ui 参考文档。

iOS 版 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];

使用 iOS 版 SDK 向特定接收方发送明确指定 action_type 和 object_id 的请求：

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

使用 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);
}

使用 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

以下内容介绍如何在 Unity 版 SDK 中发送请求。详情请参阅 FB.AppRequest 文档。

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

对话框参数

您可以使用多个可确定其行为的额外参数创建游戏请求对话框。这些参数如下所述。

响应数据

通过游戏请求对话框发送请求后，系统会将响应传递至回调，其中包含以下信息：

在游戏内处理请求

接受请求

接收方在 Facebook 桌面版网站接受请求后，他们将跳转到发送该请求的游戏网址。此网址会包含额外的 GET 参数 request_ids，这是用户接受的请求编号的列表，会以逗号分隔不同编号：

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

系统不会在接收方接受请求后自动将其删除。这项操作应由您的游戏执行。常用方法是在启动游戏后，从图谱 API 读取该用户的未处理请求列表，并在处理后逐一删除。

接收方在移动平台接受请求后，系统会生成应用的深度链接。这样，在加载应用时，系统就会显示额外参数：请求编号。在移动平台上，接受及清除请求同样应该由您的游戏负责执行。在启动游戏时检查并清除待处理的请求是不错的做法。

读取请求

发送的每个请求都拥有唯一的请求对象编号。此编号代表请求对象。此请求对象编号可与接收方用户编号串联，以创建特定的请求实例。这代表请求的一次实例化，而且已发送给特定接收方。

例如，发送请求时，游戏请求对话框的响应如下所示：

{
  request: 'REQUEST_OBJECT_ID'
  to:[array of USER_IDs]
}

如果通过图谱 API 查找请求对象编号，根据查找时的查看背景，收到的响应会稍有不同，但响应始终代表整个请求对象。

例如，如果使用接收方的用户访问口令执行 http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKEN 查询，您将看到以下响应：

{
  "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"
}

请注意，返回的字段同时包含 to 和 from。但是，如果使用发送方的访问口令或应用访问口令调用同一端点，Facebook 会返回以下内容：

{
  "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"
}

如要使用应用访问口令获取包括接收方的完整请求，您需要在下划线“_”字符后附加接收方用户编号。例如，调用 https://graph.facebook.com/{REQUEST_OBJECT_ID}_{USER_ID}?access_token={APP_ACCESS_TOKEN} 会返回：

{
  "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"
}

读取所有请求

如要读取向某个接收方发送的所有请求，您可以使用该接收方的 USER ACCESS TOKEN 查询图谱（如下所示）。此操作会返回该用户收到的相关应用的请求编号列表。

GET https://graph.facebook.com/me/apprequests?access_token=[USER ACCESS TOKEN]

删除请求

在接收方接受游戏请求后，系统并不会自动删除请求，这应该由开发者负责。因此，您必须在玩家接受请求后，代表玩家删除请求。

您可以通过以下方法删除请求：

图谱 API

向串联的 request_id 发出 HTTP DELETE 请求：

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

追踪推荐请求并提供相应奖励

根据接收方在收到游戏请求后执行的特定操作，您可以奖励游戏请求发送方。例如，不要单纯因玩家发送请求就奖励他们，但如果接收方在接受请求后安装游戏并通过特定关卡，您就可以奖励该发送方。

如要奖励发送方，您需要知道奖励对象是谁。下面是执行此操作的两种方式：

1. 发送请求后，存储游戏请求对话框的响应中返回的 request_id，并在收到后进行匹配，以奖励发送方。
2. 在玩家启动游戏后，读取向该玩家发送的所有请求，然后根据请求中 from 字段里的 id 奖励发送方。如果有多个好友邀请某个玩家，可以选择奖励第一个发送方，或者奖励所有发送方。

好友邀请 API

本地化

为帮助您向全球受众提供最佳用户体验，Facebook 支持本地化 requests。在翻译请求前，请务必了解各类请求及其显示方式。请求可以显示为标准的“Anita sent you a request”，也可以在指定操作/对象组合时，显示为“Anita asked you for a Life”或“Anita sent you a Bomb”。另外还有回合制游戏请求，用于告知用户轮到他们在游戏中与好友对战。已验证游戏的玩家可以看到上述所有示例。如果接收方尚未安装游戏，他们看到的请求会显示为邀请的形式。例如，“Anita invited you to play Friend Smash!”。我们来看看如何翻译每个示例。

翻译邀请

Facebook 会自动翻译邀请文本，此操作不受开发者控制。文本会译为接收方使用的语言。

邀请通知（英语）

邀请通知（泰语）

在以上通知示例中，文本“invited you to play”已自动译为其他语言（在此示例中为泰语）。应用名称和说明在应用设置的“本地化”部分作为“显示名称”和“说明”进行翻译，如以下黄色方框中所示。

翻译相关应用的显示名称和说明

应用中心也会显示请求。应用中心会显示请求的“消息”。消息可由开发者翻译。在以下示例中，英语消息为“Can I have a life to help me through the next level?”，翻译为泰语为“ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า”。当前应用中心不会显示请求的正文“Anita sent you a request”。

应用中心内的请求（英语）

应用中心内的请求（泰语）

翻译消息

消息在调用请求对话框时作为参数传入，因此，您可以在调用请求对话框前自行翻译消息，并将翻译后的字符串作为消息传入。如果想要动态更改翻译，则应在调用对话框前执行此操作。您可以自行决定文本的显示语言，这些文本就是发送方将在请求预览中以及接收方将在收到请求后看到的文本。

许多开发者都会检测发送方的语言，以便确定消息使用的语言。他们假设在大多数情况下发送方和接收方会使用相同的语言。在上面的示例中，您可以查看发送方的语言，如果是“泰语”，则可直接将泰语字符串作为消息发送，如下所示：

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

最佳实践

将数据附加到请求

如以上对话框参数部分所述，发送请求时，最多可以额外附加 255 个字符的数据。您可以使用此选项传输与请求有关的附加信息，也可以使用此选项附加随后可用于查找服务器上存储的相关信息的标识符。

例如，在 Facebook 游戏项目示例《Friend Smash》中，玩家轮流上场，目标是尽可能使“粉碎”好友的次数达到最高。当一个玩家通过请求向另一个玩家发送挑战时，data 参数可用于存储发出挑战的玩家的最新分数。游戏随后为接受挑战的玩家提取此值，并将其设为下一轮游戏的目标分数。

筛选邀请

构建自定义好友多选工具，或以其他方式选择请求的接收方时，请考虑提供筛选条件，帮助玩家选择所需的接收方。

在使用游戏请求对话框执行邀请时，常用的筛选条件是 app_non_users。此筛选条件可避免游戏请求对话框显示之前玩过该游戏的用户。您可以考虑使用的其他筛选条件包括：最近互动过的玩家，或您管理的类似游戏的玩家。如需获取可用筛选条件的完整列表，请参阅游戏请求对话框 — 参数参考文档。

创建有吸引力的机制

创建有吸引力的机制，让玩家可以访问游戏中的好友，或者直接与他们互动。例如，如果游戏支持友邻概念，当玩家访问友邻的环境时，就可以给予能量作为奖励。如果玩家的基地受到攻击，可允许他们的好友帮忙修复。在帮助好友提升游戏进度的过程中，玩家通常会获得成就感，所以为他们提供这种机会能够打造更好的社交体验，并吸引更多玩家。

让玩家发现对象的价值

提供对玩家来说有价值的对象，让玩家能够凭借该对象提升游戏或社交体验。

细分玩家并提供相应请求

评估玩家并将他们细分为对您的游戏而言有意义的各个组别（例如，新玩家、构建装备的玩家、拥有很多好友的玩家、参与度较高的玩家等）。思考对于玩家所处等级，哪些对象对玩家而言具有吸引力，并为每个细分受众提供特定对象。