游戏请求

分类目录: 游戏

游戏请求

概览

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

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

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

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

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

游戏请求可用于 Facebook 游戏和 iOS 及 Android 移动游戏。在 Facebook 桌面版网站上,请求会以蜂鸣式弹出窗口在屏幕左下方以及通知图标中显示。在移动平台上,请求在 Facebook 应用的通知列表内显示。请求数据可通过游戏请求 API 获取,还可以构建自定义用户界面,实现更加整体化的移动游戏体验。因此,请求的实施应不区分平台,并应在所有平台上提供一致的用户体验。

注意:

  • 从图谱 API 2.3 开始,只有游戏能使用游戏请求
  • 我们会过滤应用请求中的垃圾信息或其他负面信号。被过滤的请求不会收到通知。用户可在游戏活动页面找到被过滤的请求。

启动请求对话框

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

JavaScript

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

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

关闭对话框时,response 对象会包含发送结果,其中包括 request 编号以及一组 to 接收方。\n例如:

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

在默认情况下,会向发送方展示好友选择工具,方便他们选择最多 50 个接收方。

由于存在网址长度限制,使用非 iframe 对话框时,Internet Explorer 7 或 8 中的最大接收方数量为 25。

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

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

通过逗号分隔列表可指定多个接收方,该列表中包含用户编号和来自好友邀请 API 的邀请口令。

您能够通过 to 字段指定的最大接收方数量存在限制,即少于 50 个好友,在 Internet Explorer 8 及以下版本中为少于 26 个好友。

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

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

对话框参数

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

参数名称 说明 是否必须提供

app_id

应用的唯一标识符。

redirect_uri

在发送方点击对话框按钮后重新定向到的网址。可让发送方在发送请求后返回游戏。出于安全考虑,指定的 redirect_uri 必须位于与应用的 Canvas 网址相同的根域中。

使用网址重新定向时必须提供

to

此参数为用户 idusernameinvite token,或包含用户 idusernameinvite tokens 的逗号分隔列表。接收方可以是发送方的好友,也可以不是。如果由应用指定,则发送方无法选择接收方。如果未由应用指定,则发送方会看到好友选择工具

message

要在请求中发送的纯文本消息。此文本会在请求的应用中心视图中显示,但不会在通知图标中显示

action_type

在定义有关请求性质的附加背景时使用。可能的值包括 sendaskforturn

如果设置了 object_id,则必须提供

object_id

待发送对象的开放图谱对象\n编号。

如果 action_type 设置为 sendaskfor,则必须提供

filters

此参数控制显示好友选择工具时可以看到的好友组。如果留空,好友选择工具会显示用户的所有 Facebook 好友。指定 app_users 后,好友选择工具仅会显示身份为应用现有用户的好友。使用配对请求时应使用此参数。或者,可以指定 app_non_users,发送方仅会看到之前未验证应用的好友。使用请求来邀请新用户加入游戏时应使用此参数。应用还可以使用具有 nameuser_ids 键(值分别为字符串和用户 id 列表)的字典来推荐自定义筛选条件。name 是将在选择工具中显示的自定义筛选条件的名称。user_ids 是要包含的好友的列表,按显示顺序排序。注意:在 iOS 和 Android SDK 中,仅支持作为奇异值的 app_usersapp_non_users 筛选条件,不支持这些值的字典。此外,此参数不可与 suggestions 一起使用,在同一对话框中使用这两个参数会导致错误。

suggestions

将作为首选推荐好友而包含在对话框中的一组用户编号。注意:此参数仅面向移动设备提供,不可与 filters 一起使用。在同一对话框中使用这两个参数会导致错误。

exclude_ids

将从对话框中排除的一组用户编号。如果从对话框中排除某些用户,他们将不会在好友选择工具中显示。注意:移动版 SDK 不支持此参数并会忽略此参数。

max_recipients

整数值,用于指定发送方可在好友选择工具中选择的最大好友数量。此参数不受移动设备的支持。

data

可以传递用于追踪的附加自由格式数据。此参数会作为所创建的请求对象的一部分存储。最大长度为 255 个字符。

title

对话框的标题。最大长度为 50 个字符。

响应数据

通过游戏请求对话框发送请求后,包含以下信息的响应将传递给回调:

参数名称 说明

request

请求对象编号。要获取完整的请求编号,请使用 to 字段中规定的用户编号串联此参数:{request_object_id}_{user_id}

to

适用于所创建请求的一组接收方用户编号。

在游戏内处理请求

接受请求

接收方在 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"
}

请注意,会返回 tofrom 字段。但是,如果使用发送方访问口令或应用访问口令调用同一端点,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. 在玩家启动游戏时读取所有请求,然后根据请求中 id 字段里的 from 奖励发送方。如果有多个好友邀请某玩家,可以选择奖励第一个发送方或奖励所有发送方。

好友邀请 API

Facebook 通过游戏请求对话框提供邀请功能,但经验丰富的开发者可能会想要构建自定义好友选择工具,帮助维护沉浸式游戏体验。具体方法是使用好友邀请 API。

此功能仅面向能在桌面版 Facebook 玩的游戏

查询指定用户的 invitable_friends 后,Facebook 将返回该玩家尚未玩游戏的好友的排序列表。列表的排序方式是将最有可能对游戏感兴趣的用户排在顶部。这让开发者能够针对最有可能积极响应的用户,构建具有自定义外观和风格的好友选择工具。

列表中的每个条目都包含关于用户姓名、照片和 invite token 的信息。此列表返回的 invite_tokens 随后会传入游戏请求对话框中的 to 参数,以便向不是应用用户的好友调用 Facebook 请求。

邀请拥有与请求相同的运作模式,并会使接收方跳转至以下位置之一:

  • Facebook 上的游戏。
  • iOS 或 Android 平台上的原生应用(如果已安装)。
  • Apple App Store 或 Google Play 商店(如果未安装)。

invitable_friends 列表仅面向 Facebook.com 上的游戏以及在 Facebook.com 上展示的移动游戏。好友邀请 API 的可用情况如下所示:

Canvas iOS Android 好友邀请 API\n是否可用?

玩家发送的邀请会在游戏支持的任意平台组合上显示。您的实施不应视平台而异,并能为所有设备打造一致的用户体验。

调用图谱 API

要访问当前玩家的 invitable_friends 列表,您应通过平台的 SDK,使用有效用户访问口令调用图谱 API。

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

响应示例:

图谱 API 随后会返回排序的对象列表,其中的对象代表当前玩家尚未授权游戏的好友。此列表按与当前玩家和游戏的相关度排序。

响应示例:

{
  "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&amp;pretty=1&amp;after=MTAxNTM5NjI0NDE5MjA2MzI=",
    "cursors": {
      "before": "NzM3OTE3Mzc2MjQ4ODkx",
      "after": "MTAxNTM5NjI0NDE5MjA2MzI="
    }
  }}

此列表的默认大小为 1,000 个对象。如果列表中的对象数量超过此大小,您可以使用分页对象中的 next 网址遍历不同页面。您还可以设置初始调用中的 limit,获取包含更多或更少对象的列表。

但是,列表中越靠近底部的接收方响应邀请的可能性越小。因此,Facebook 建议构建展示较少待邀请好友的界面。

如果想要更好地控制通过此端点返回的图片的大小,您可以发送嵌套请求,指定所需的图片大小。

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

您可以阅读使用图谱 API 参考文档,了解有关分页和限制以及发送嵌套请求的更多信息。

邀请口令

邀请口令是长度可变的唯一(按用户和按游戏区分)字符串,在每个好友对象中作为 id 字段的值返回。邀请口令会过期,并可能视游戏会话的不同而不同。因此,不建议缓存这些结果,也不建议尝试向指定用户分配这些口令。

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

邀请好友

每个邀请口令都可用于使用游戏请求对话框邀请玩家的好友。获取口令后,您应使用图谱 API 返回的列表构建自己的游戏内好友选择工具对话框。

在此对话框中,玩家应能够选择多个可供邀请的好友,但不应默认预先选择任何好友。

玩家选定要邀请的好友并明确表达想要邀请这些好友加入游戏的意向(即,点击“邀请”按钮)后,您应发起调用,显示请求对话框。

要发送邀请给选定的好友,请使用好友的邀请口令填充请求对话框调用的 to 参数。例如,假设玩家已选择一个具有如下所示口令的好友,您可以使用 JavaScript 版 Facebook SDK 发起此调用:

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

发起调用后,您将收到可用于追踪游戏邀请表现的 request_id

权限

“可邀请好友”需要 user_friends 权限。最佳实践是,在发起图谱 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);

具有操作/对象组合的请求

我们的翻译工具用于翻译指定了操作/对象组合的请求,即类似于“Anita asked you for a Life”或“Anita sent you a Bomb”的请求。这些请求是开放图谱对象,因此,字符串的翻译方式与开放图谱动态的翻译方式类似。这些翻译会在请求通知和首页提醒中显示。

未输入特定语言的翻译时,鉴于系统可能已经提供了翻译,会按没有操作/对象组合的情况向接收方显示该请求。对于接收方而言,在默认语言为英语且没有提供翻译时,尽管使用他们可能看不懂的语言表达的请求内容更详细,但查看以他们所用的语言表达的请求时用户体验会更好。

设置要与游戏请求一起使用的开放图谱对象后,将转到位于应用配置中“本地化”部分的翻译工具。

本地化部分的“翻译开放图谱动态”按钮

点击“翻译开放图谱动态”按钮后,系统会将您转至此处的翻译面板。您可以在此处翻译短语。但是,要让新开放图谱对象和请求的字符串在此处显示,您需要先“删除和重新导入”字符串。在此屏幕中,点击“面板”选项卡。

在“面板”选项卡中,您将看到用于“删除和重新导入”字符串的功能。点击此链接。不要担心,这不会删除您之前翻译的所有字符串。此操作只会重建需要翻译的短语,并会包括请求中的新短语。

翻译工具面板

点击“删除和重新导入所有字符串”后,返回浏览短语选项卡,查找与新对象相关的所有字符串。请记住,由于可以使用各种不同的方法来拼凑请求并在 Facebook 中显示,因此,有各种不同的短语能够与其搭配使用。仔细查看与对象相关的每条短语并翻译。

翻译工具面板

请注意,对象和操作的所有翻译都会在翻译工具中完成。无需翻译对象描述文件的元标签信息中的任何内容。通知和首页提醒中的所有请求片段,包括操作的翻译,都在翻译工具中完成。

回合请求

回合请求用于回合制游戏,其中每个玩家都需要告知其他玩家轮到对方完成自己的回合。这些请求通过 Facebook 众包方式翻译,并会在请求通知和首页提醒中显示。翻译的字符串数量取决于众包的成功程度。

进阶主题

使用无阻请求

实施无阻请求可简化发送请求的流程。无阻请求支持玩家在应用内向特定好友发送请求,无需每次都点击弹出的确认对话框。

首次向好友发送请求时,玩家可以允许向同一好友发送后续请求,无需每次都提示用户授权。这对于回合制游戏特别有用,玩家可直接向对手发送后续回合的请求,无需执行附加操作。

无阻请求对话框切换

无阻请求仅适用于请求,而不适用于邀请。好友安装游戏后,请求会变成无阻请求。还需要提供 user_friends 权限。

无阻请求十分易于实施。使用 JavaScript 版 Facebook SDK,将 FB.init 中的 frictionlessRequests 参数设置为 true,如下所示:

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

在 iOS 中,无阻请求通过 FBFrictionlessRecipientCache 类实施,该类用于缓存可以接收无阻请求的好友。以下为无阻请求的实施示例

首先,需要将 FBFrictionlessRecipientCache 实例添加到对 FBWebDialogs presentRequestsDialogModallyWithSession: 的调用中。FBFrictionlessRecipientCache 对象用于缓存好友列表的详细信息并追踪我们之前向其发送过请求的用户。首先,将 FBFrictionlessRecipientCache 的实例添加到 FacebookController 类。

前往 FacebookController.h,添加以下项目作为该类的私有静态成员:

private:
static FBFrictionlessRecipientCache* ms_friendCache;

现在,导航到文件顶部第一个类方法(我们之前创建的 CreateNewSession() 方法)上面的 FacebookController.cpp,添加下列行以实例化接收方缓存:

FBFrictionlessRecipientCache* FacebookController::ms_friendCache = NULL;

然后向下滚动至 SendRequest(const int nScore) 方法。在您定义 NSMutableDictionary* params 对象的位置下面,添加以下代码:

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

这会创建 FBFrictionlessRecipientCache 对象(如果该对象尚未初始化),还将为当前会话预先获取接收无阻请求的好友的列表并缓存该列表。

最后,在对 presentRequestsDialogModallyWithSession 的调用(生成请求对话框)中,将好友缓存添加到最终方法参数。

您的代码结尾应类似下文:

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

在 Android 中,由玩家选择是否允许不经过确认步骤即发送请求。在 Android 平台上,游戏客户端无法识别此设置。

向玩家发送对象

要在请求中发送对象和操作,您将需要创建可以在请求中发送的游戏内项目的开放图谱表达。

为请求创建开放图谱对象的方法与为自定义开放图谱动态创建对象的方法一样。您甚至还可以重用在动态中使用的相同对象。但是,您无法使用标准开放图谱类型的实例,并且必须使用自己的自定义开放图谱类型。

通过请求发送的对象必须为应用所有,以便这些对象处于公开状态,可供所有人查看。

对于想要在请求中使用的每种类型的对象,您将需要为其设置一个自定义开放图谱对象类型以及一个该类型的实例。例如,如果要发送炸弹和生命,您需要为两者分别设置开放图谱对象类型,并创建类型的实例。

要创建自定义开放图谱类型,请按照“创建对象类型”文档中的说明操作。

以下是本指南其他部分使用的炸弹示例的对象类型。仅需要提供 og:typeog:title 属性。

Friend Smash 中炸弹的开放图谱对象类型页面。

请求中未使用对象实例的其他属性(图片、说明等)。请求中显示的信息基于对象类型的名称。

使用对象浏览器工具可以轻松快速地创建对象实例。

构建好友选择工具

通过构建自己的好友选择工具,您可以自定义选择工具的外观和风格,使其与游戏的其他部分保持一致。此外,您可以使用可能拥有的任何其他信息优化流程,以便显示与游戏最相关的好友。

如果在网页上使用 Flash 或 Unity 构建游戏,您就需要创建原生好友选择工具,而不是使用 Facebook 网页对话框。同理,在 iOS 或 Android 中创建原生流程通常会比默认的 Facebook 实施机制的体验更流畅。因此,Facebook 开放平台上的大部分顶尖游戏开发者都会选择实施自定义好友选择工具。

将数据附加到请求

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

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

最佳实践

筛选邀请

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

使用游戏请求对话框实施邀请时,app_non_users 是一个常用的筛选条件。此筛选条件可阻止游戏请求对话框显示之前玩过您的游戏的用户。您可以考虑使用的其他筛选条件包括:最近互动过的玩家,或您管理的类似游戏的玩家。如需获取可用筛选条件的完整列表,请参阅游戏请求对话框 — 参数参考文档。

创建有吸引力的机制

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

让对象对玩家有价值

提供对玩家有价值的对象,让玩家能够将它们用于增强游戏性或社交体验。

细分玩家并根据背景提供请求

评估玩家并将玩家划分为对您的游戏而言有意义的各个小组(例如,新玩家、构建装备的玩家、多好友玩家、高参与度玩家等)。思考相对于玩家所处的关卡而言,哪类对象对玩家具有吸引力,并为每个受众细分提供特定对象。