Facebook Instant Game游戏开发更新文档 API 参考文档 v6.0 - Facebook开发者社区

1. 排行榜 此版本全新推出排行榜 API！提供一套强大的 API，使得游戏可获取排行榜、查询得分情况和设置新分数（支持分数所带的任意元数据），并可向 Messenger 对话推送结构化的排行榜更新消息。

2. [公测版] 游戏内切换 我们还针对游戏内交叉推广引入了一个新 API。它目前处于封测阶段，如果您有兴趣在自己的游戏中帮忙测试游戏内切换 API 的集成效果，请联系您的合作伙伴经理！

玩家的唯一标识。Facebook 用户的玩家编号将保持不变，且仅限于特定游戏范围。这意味着同一个用户在不同的游戏中有不同的玩家编号。仅当 FBInstant.initializeAsync() 被解析后才应调用此函数。

// This function should be called after FBInstant.initializeAsync()// resolves.var playerID = FBInstant.player.getID();

获取玩家的唯一标识和签名，签名用于验证标识确实来自 Facebook，且没有被篡改。仅当 FBInstant.initializeAsync() 被解析后才应调用此函数。

// This function should be called after FBInstant.initializeAsync()// resolves.FBInstant.player.getSignedPlayerInfoAsync('my_metadata')

经本地化显示的玩家姓名。仅当 FBInstant.startGameAsync() 被解析后才应调用此函数。

// This function should be called after FBInstant.startGameAsync()// resolves.var playerName = FBInstant.player.getName();

玩家公开头像的网址。此照片始终为正方形，尺寸至少为 200x200 像素。在游戏中显示时，确切的尺寸可能会有所变化。建议始终在显示之前将图片调整为需要的尺寸。对应的值将始终为 null，直至 FBInstant.startGameAsync() 被解析。

警告：由于使用 CORS 机制，在游戏 Canvas 中使用这些照片会导致照片损坏，这有碍于提取 Canvas 数据。为防止出现这种情况，应将您使用的图片的 cross-origin 属性设置为 “anonymous”。

playerImage.crossOrigin = 'anonymous';// This function should be called after FBInstant.startGameAsync()// resolves.

返回 Promise<对象> 此 promise 将在获得包含下列信息的对象时被解析：输入数组中指定的每个键的当前键值对（如存在）。

设置要保存到指定云存储的当前玩家的数据。对于每个独立玩家，游戏最多可存储 1MB 的数据。

data对象此对象包含应该保存到云存储的一组键值对。对象必须仅包含可序列化的值 — 任何不可序列化的值都会导致整个修改被拒绝。

返回 Promise 此 promise 将在输入值设定时被解析。注意：promise 被解析并不一定意味着输入已被存储，而是这意味着相关数据有效并已安排要被存储。这还能保证设置的所有值现在可在 player.getDataAsync 中使用。

立即将玩家数据的任何更改刷新到指定的云存储中。此函数的调用成本较高，应主要用于需要立即存储并告知游戏的重要更改。非重要更改应依赖于开放平台在后台进行存储。注意：当此函数的结果待定时， player.setDataAsync 调用将被拒绝。

keys数组<字符串>？唯一键数组（可选），针对这些键检索统计数据。如果调用函数时没有设置此参数，则会提取所有统计数据。

返回 Promise<对象> 此 promise 将在获得包含下列信息的对象时被解析：输入数组中指定的每个键的当前键值对（如存在）。

stats对象此对象包含应作为统计数据保存到云存储的键值对，能以各种方式显示或使用这些数据以提高玩家参与度。对象必须仅包含数值，任何非数值会导致整个修改被拒绝。

返回 Promise 此 promise 将在输入值设定时被解析。注意：promise 被解析并不一定意味着输入已被存储，而是这意味着相关数据经过验证并已安排要被存储。这还能保证设置的所有值现在可在 player.getStatsAsync 中使用。

increments对象此对象包含一组键值对，这些键值对表示云存储中每个统计数据的增量是多少。对象必须仅包含数值，任何非数值会导致整个修改被拒绝。

返回 Promise<对象> 此 promise 将在获得包含下列信息的对象时被解析：输入字典中指定的每个键的更新键值对。注意：解析 promise 并不一定意味着更改已被存储，而是意味着增量有效且已安排要被执行。这还能保证增加的所有值现在可在 player.getStatsAsync 中使用。

返回 Promise<数组<ConnectedPlayer>> 此 promise 将在获得关联玩家对象列表时被解析。注意：只有当 FBInstant.startGameAsync() 被解析时，此 promise 才会解析。

当前游戏环境的唯一标识。这表示玩游戏的特定环境（例如：特定的 Messenger 对话或 Facebook 帖子）。如果用户在独立环境中玩游戏，则此标识将为 null。仅当 FBInstant.startGameAsync 被解析后才应调用此函数。

// This function should be called after FBInstant.startGameAsync()// resolves.var contextID = FBInstant.context.getID();

当前游戏环境的类型。 POST — 一个 Facebook 帖子。 THREAD — 一个 Messenger 对话。 GROUP — 一个 Facebook 小组。 SOLO — 默认环境，玩家是唯一的参与者。

// This function should be called after FBInstant.startGameAsync()// resolves.var contextType = FBInstant.context.getType();

此函数用于确定加入当前游戏环境的玩家数量是否在给定的最小值和最大值之间（包括最小值和最大值）。仅当其中一个边界值为 null 时，才会根据另一个边界值进行检查。在特定的游戏会话中，此函数始终会返回某环境内发出的第一个调用的最初结果。后续调用（无论参数是什么）将返回原始查询的答案，除非游戏环境发生变化且查询结果被重置。

如果提供的一个或两个参数无效，我们没有适合当前游戏环境的玩家数量，或者 API 在 startGameAsync() 解析之前被调用，此参数都会为 null。

console.log(FBInstant.context.isSizeBetween(3, 5)); (Context size = 4)// {answer: true, minSize: 3, maxSize: 5}

console.log(FBInstant.context.isSizeBetween(5, 7)); (Context size = 4)// {answer: false, minSize: 5, maxSize: 7}

console.log(FBInstant.context.isSizeBetween(2, 10)); (Context size = 3)// {answer: true, minSize: 2, maxSize: 10}

console.log(FBInstant.context.isSizeBetween(4, 8)); (Still in same context)// {answer: true, minSize: 2, maxSize: 10}

console.log(FBInstant.context.isSizeBetween(3, null)); (Context size = 4)// {answer: true, minSize: 3, maxSize: null}

console.log(FBInstant.context.isSizeBetween(null, 3)); (Context size = 4)// {answer: false, minSize: null, maxSize: 3}

请求切换到指定环境。如果玩家没有进入该环境的权限，或玩家未向游戏提供进入该环境的权限，请求将被拒绝。 promise 将在游戏切换到指定环境时被解析。

为玩家打开一个环境选择对话框。如果玩家选择可用的环境，客户端将尝试切换到这个环境，并在成功时解析。而如果玩家退出菜单或客户端未能切换到新环境，此函数将被拒绝。

返回 Promise 此 promise 将在游戏切换到用户选择的环境时被解析。否则此 promise 将被拒绝（例如用户退出对话框）。

尝试在指定玩家和当前玩家之间创建环境或切换环境。如果列出的玩家不是当前玩家的关联玩家，或玩家未提供进入新环境的权限，则返回的 promise 将被拒绝。当游戏切换到新环境时， promise 将被解析。

获取 #contextplayer 对象的数组，其中包含与当前环境相关的活跃玩家（在过去 90 天内玩过游戏的用户）的信息。这可能包含当前玩家。

获取玩家未消费的所有购买商品。最佳做法是，游戏在客户端表明已准备好执行支付相关操作时，立即获取当前玩家的购买商品。游戏随后可处理和消费正在等待被消费的任何购买商品。

消费当前玩家拥有的特定购买商品。在为玩家配置商品效果之前，游戏应先请求消费已购买的商品。购买的商品成功消费后，游戏应立即向玩家呈现购买商品的效果。

当前的语言设置。根据这一结果确定当前的游戏应本地化为哪种语言。在 FBInstant.startGameAsync() 被解析之前，对应的值将不准确。

// This function should be called after FBInstant.startGameAsync()// resolves.var locale = FBInstant.getLocale(); // 'en_US'

当前运行游戏的平台。对应的值将始终为 null，直至 FBInstant.initializeAsync() 被解析。

// This function should be called after FBInstant.initializeAsync()// resolves.var platform = FBInstant.getPlatform(); // 'IOS'

// This function should be called after FBInstant.initializeAsync()// resolves.var sdkVersion = FBInstant.getSDKVersion(); // '2.0'

// This function should be called after FBInstant.initializeAsync()// resolves.FBInstant.getSupportedAPIs();// ['getLocale', 'initializeAsync', 'player.getID', 'context.getType', ...]

对象内容由开发者定义，可通过不同平台的入口点触发。对于较旧版本的移动客户端，以及没有与特定入口点相关的数据时，此函数会返回 null。

// This function should be called after FBInstant.initializeAsync()// resolves.const entryPointData = FBInstant.getEntryPointData();

// This function should be called after FBInstant.startGameAsync()// resolves.FBInstant.getEntryPointAsync().then(entrypoint => console.log(entrypoint));// 'admin_message'

当游戏需要更新当前的会话数据时，应调用此函数。此会话数据可用于填充各种负载，如玩游戏 Webhook。

sessionData对象一个随机数据对象，转变为字符串后，必须小于或等于 1000 个字符。

表示游戏已完成初始加载，并准备就绪可以开始游戏。当返回的 promise 被解析时，环境信息即为最新。

此函数会调用一个对话框，让用户以下列方式分享指定的内容：在 Messenger 中发送消息，或在用户时间线上发布帖子。可以在分享中添加数据块，通过此次分享启动的每个游戏会话都可以通过 FBInstant.getEntryPointData() 访问此数据块。转变为字符串时，此数据必须小于或等于 1000 个字符。用户可以选择取消分享操作和关闭对话框，但无论用户实际是否分享了内容，返回的 promise 都将在对话框关闭时解析。

向 Facebook 通知游戏内发生的更新。这会暂时将控制权移交给 Facebook，且 Facebook 将确定要根据更新内容采取什么操作。返回的 promise 将在 Facebook 把控制权返还给游戏时解析/拒绝。

// This will post a custom update. If the game is played in a messenger// chat thread, this will post a message into the thread with the specified// image and text message. And when people launch the game from this// message, those game sessions will be able to access the specified blob// of data through FBInstant.getEntryPointData().FBInstant.updateAsync({

请求客户端切换到另一个小游戏。切换失败时，API 将拒绝，否则客户端将加载新游戏。

appID字符串要切换到的小游戏相应的应用编号。应用必须为小游戏，且必须和当前游戏属于同一商家所有。要将不同游戏关联到相同商家，您可使用商务管理平台：https://developers.facebook.com/docs/apps/business-manager#update-business。

data字符串？可选的数据负载。这将设为要切换到的游戏的入口点数据。转变为字符串时，必须小于或等于 1000 个字符。

通过 Facebook 分析记录应用事件。请参阅 https://developers.facebook.com/docs/javascript/reference/v2.8#app_events 详细了解 Fcaebook 分析。

eventName字符串事件名称。必须为 2 到 40 个字符，且只能包含“_”、“-”、“ ”和字母数字字符。

parameters对象可选的对象，最多可包含 25 个要与事件一同记录的键值对。键必须为 2 到 40 个字符，且只能包含“_”、“-”、“ ”和字母数字字符。值的长度必须小于 100 个字符。

返回 Promise 此 promise 将在获得 #adinstance 时被解析；在获得 #apierror 时被拒绝（如果未能创建）。

[封闭公测] 尝试将当前玩家与等待他人加入游戏的其他玩家进行匹配。如果匹配成功，将为匹配的玩家创建一个新的 Messenger 群聊，且玩家的游戏环境将切换到该群聊。

matchTag字符串？玩家的可选额外信息，可用于将玩家加到具有相似玩家的群聊中。具有完全相同标签的玩家才会加入同一群聊。标签只能包含字母、数字和下划线，且长度不能超过 100 个字符。

switchContextWhenMatchedboolean 可选的额外参数，指定当找到匹配时，是否将玩家立即切换到新环境。默认设置为 false，亦即玩家在匹配成功后，需要明确点击玩游戏按钮才会切换到新环境。

返回 Promise<boolean> 当玩家符合与其他玩家匹配的条件时，此 promise 被解析为 true，否则解析为 false。

返回 Promise<排行榜> 此 promise 在获得匹配的排行榜时被解析，在未找到匹配时被拒绝。

代表特定字符串的语言设置与翻译之间的映射。每个属性均为可选且包含五个字符的 Facebook 语言代码，格式为 xx_XX。请参阅 https://origincache.facebook.com/developers/resources/?id=FacebookLocales.xml，获取受支持的语言代码的完整列表。

用于验证此对象确实来源于 Facebook 的签名。此字符串使用 base64url 编码，并根据 OAuth 2.0 协议使用 HMAC 版本的应用密钥签名。

通过 base64url 编码对第二部分（响应负载）进行解码，第二部分应该是代表 JSON 对象（包含下列字段）的字符串：

request_payload — 调用 FBInstant.player.getSignedPlayerInfoAsync 时指定的 requestPayload 字符串。

请采用 HMAC SHA-256 和您的应用密钥散列处理整个响应负载字符串，并确定它等同于经编码的签名。

应仅在您的服务器中进行签名验证。 不要在客户端进行签名验证，因为客户端可能会泄漏您的应用密钥。

// Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ

//// In your server (node.js example)//const CryptoJS = require('crypto-js');var firstpart = signedRequest.split('.')[0];

firstpart = firstpart.replace(/-/g, '+').replace(/_/g, '/');const signature = CryptoJS.enc.Base64.parse(firstpart).toString();const dataHash = CryptoJS.HmacSHA256(signedRequest.split('.')[1], '<APP_SECRET>').toString();var isValid = signature === dataHash;

const json = crypto.enc.Base64.parse(signedRequest.split('.')[1]).toString(crypto.enc.Utf8);const encodedData = JSON.parse(json);

// Example encodedData:// {// algorithm: 'HMAC-SHA256',// issued_at: 1520009634,// player_id: '123456789',// request_payload: 'my_payload'// }

代表广告。返回的 promise 将在用户观看完广告时被解析，在广告展示失败或用户在广告展示期间关闭广告时被拒绝。

更新玩家的分数。如果玩家已有分数，只有新分数更好时，才会替换旧分数。注意：如果排行榜与特定环境关联，游戏必须处于该环境，才能为玩家设置分数。

count数字尝试从排行榜获取的上榜分数总数量。如果未指定，默认为 10。每条查询命令最多可获取 100 个上榜分数。

适用于环境选择操作的筛选条件。 “NEW_CONTEXT_ONLY”— 仅显示之前玩游戏未使用过的环境。 “INCLUDE_EXISTING_CHALLENGES”— 包括“当前挑战”部分，显示玩家积极在其中玩游戏的环境。 “NEW_PLAYERS_ONLY”— 在包含个人信息的部分，筛选出之前未玩过游戏的用户，

如果当前环境的规模介于对象中指定的 minSize 和 maxSize 值之间， answer 字段为 true，否则为 false。

data对象？要附加到分享中的数据块。通过分享开始的所有游戏会话都可以通过 FBInstant.getEntryPointData() 访问此数据块。

ADS_NO_FILL字符串我们无法向当前的用户投放广告。如果用户在设备中退订基于兴趣的广告，或我们没有广告可展示给该用户，就会出现这种情况

ADS_TOO_MANY_INSTANCES字符串同时展示的广告实例太多。建议您先加载和展示现有广告实例，再新建广告。

CLIENT_REQUIRES_UPDATE字符串 [已停用] — 客户端要求获得更新，以便访问返回此结果的功能。如果在网页端返回这一结果，则意味着该网页客户端还不支持此功能。v5.0 及更高版本已停用这一代码，以便支持 CLIENT_UNSUPPORTED_OPERATION

CLIENT_UNSUPPORTED_OPERATION字符串客户端不支持当前操作。这可能是因为客户端版本或平台不提供相关支持，或不允许对游戏或玩家执行此操作。

INVALID_OPERATION字符串所请求的操作无效，或表示当前的游戏状态。这包括违反限制（如超出存储上限）或不适用于特定状态（如在独立的环境中针对特定环境发出请求）的情况。

INVALID_PARAM字符串传递给 API 的参数无效。可表示错误类型、参数的无效数字，或语义问题（例如，将不可序列化的对象传递到序列化函数）。

LEADERBOARD_NOT_FOUND字符串找不到所请求名称的排行榜。这是因为排行榜尚不存在，或其名称与游戏中登记的任何排行榜配置都不匹配。

LEADERBOARD_WRONG_CONTEXT字符串尝试写入的排行榜关联了不同于当前玩游戏环境的其他环境。

NETWORK_FAILURE字符串客户端处理网络请求时出现问题。这可能是由暂时性问题导致的，如玩家的网络连接中断。

PENDING_REQUEST字符串表示因存在与此请求冲突的一项请求而被拒绝。例如，当某个依赖于 Facebook 用户界面的请求处于待处理状态时，我们就会拒绝显示 Facebook 用户界面的其他任何调用。

UNKNOWN字符串发生了未知或未指定的问题。这是客户端未指定代码时返回的默认错误代码。

USER_INPUT字符串用户的选择导致被拒绝。例如，如果游戏调用环境切换对话框，而玩家关闭此对话框，则 promise 拒绝中就会包含此错误代码。

Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ

developerPayload字符串？由开发者指定的可选负载，包含在所返回购买的签名请求中。

template字符串此自定义更新所使用模板的编号。模板应在 fbapp-config.json 中预定义。请参阅 [捆绑包配置文档]https://developers.facebook.com/docs/games/instant-games/bundle-config，获取有关 fbapp-config.json 的文档。

cta（字符串？| LocalizableContent？）可选的行动号召按钮文本。默认情况下，我们会使用经本地化的“Play”作为按钮文本。若要提供自定义行动号召的本地化版本，应传递一个包含默认行动号召的对象作为“default”值，以及将语言键映射到翻译的另一个对象作为“localizations”值。

text（字符串 | LocalizableContent）一条文本消息，或者是一个包含默认文本作为“default”值的对象以及另一个将语言键映射到翻译内容作为“localizations”值的对象。

data对象？要附加到更新中的数据块。通过更新开始的所有游戏会话都可以通过 FBInstant.getEntryPointData() 访问此数据块。转变为字符串时，此数据块必须小于或等于 1000 个字符。

strategy字符串？指定更新的发布方式。可以是下列方式之一： “IMMEDIATE”— 更新应立即发布。 “LAST”— 更新应在游戏会话结束时发布。使用 “LAST”策略发送的是最近发送的更新。 “IMMEDIATE_CLEAR”— 更新将立即发布，并清除其他任何待处理的更新（如通过“LAST”策略发布的更新）。如果未指定策略，我们将默认为“IMMEDIATE”。

notification字符串？指定自定义更新的通知设置。可以是“NO_PUSH”或“PUSH”，默认为“NO_PUSH”。仅将推送通知用于对接收人来说非常显著且可立即操作的更新。另请注意，并不一定会发送推送通知，具体取决于用户设置和平台政策。

actionUpdateAction 对于排行榜更新，此属性应为 “LEADERBOARD”。文本。默认情况下，我们会使用经本地化的“Play Now”作为按钮文本。

text字符串？可选的文本消息。如果未指定，将会提供一条经本地化的回退消息。

default字符串要使用的字符串的默认值（查看者的语言设置不是 localizations 对象中的键时）。

localizationsLocalizationsDict 指定每种语言设置中用于观看者的字符串。请参阅 https://origincache.facebook.com/developers/resources/?id=FacebookLocales.xml，获取受支持的语言值的完整列表。

为方便大家群策群力，我们创建了一个 Facebook Instant Game 交流群：814298516 。欢迎同学们加入交流开发和运营经验。