Facebook 游戏开发更新文档API 参考文档 v6.0
更新日志1. 排行榜 此版本全新推出排行榜 API！提供一套强大的 API， 使得游戏可获取排行榜、查询得分 情况和设置新分数（支持分数所带的 任意元数据），并可向 Messenger 对话推送结构化的排行榜 更新消息。 2. [公测版] 游戏内切换 我们还针对游戏内交叉推广引入了一个新 API。它目前 处于封测阶段，如果您有兴趣在自己的游戏中帮忙 测试游戏内切换 API 的集成效果，请联系 您的合作伙伴经理！
FBInstant小游戏 SDK 的顶级命名空间。
player包含与当前玩家相关的功能和属性。
getID( )玩家的唯一标识。Facebook 用户的玩家编号 将保持不变，且仅限于特定游戏范围。这意味着 同一个用户在不同的游戏中有不同的玩家编号。 仅当 FBInstant.initializeAsync() 被解析后才应调用此 函数。 示例 // This function should be called after FBInstant.initializeAsync()// resolves.var playerID = FBInstant.player.getID();
getSignedPlayerInfoAsync( )获取玩家的唯一标识和签名，签名用于验证标识确实 来自 Facebook，且没有被篡改。 仅当 FBInstant.initializeAsync() 被解析后才应调用此 函数。 参数 · requestPayload 字符串？ 开发者指定的包含于 已签名响应中的负载。 · 示例 // This function should be called after FBInstant.initializeAsync()// resolves.FBInstant.player.getSignedPlayerInfoAsync('my_metadata') .then(function (result) { // The verification of the ID and signature should happen on server side. SendToMyServer( result.getPlayerID(), // same value as FBInstant.player.getID() result.getSignature(), 'GAIN_COINS', 100); }); · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE · · 抛出 CLIENT_UNSUPPORTED_OPERATION ·
getName( )经本地化显示的玩家姓名。仅当 FBInstant.startGameAsync() 被解析后 才应调用此函数。 示例 // This function should be called after FBInstant.startGameAsync()// resolves.var playerName = FBInstant.player.getName();
getPhoto( )玩家公开头像的网址。此照片始终为正方形， 尺寸至少为 200x200 像素。在游戏中显示时， 确切的尺寸可能会有所变化。建议 始终在显示之前将图片调整为需要的尺寸。 对应的值将始终为 null，直至 FBInstant.startGameAsync() 被解析。 警告：由于使用 CORS 机制，在游戏 Canvas 中使用这些照片会导致照片 损坏，这有碍于提取 Canvas 数据。 为防止出现这种情况，应将您使用的图片的 cross-origin 属性设置为 “anonymous”。 示例 var playerImage = new Image(); playerImage.crossOrigin = 'anonymous';// This function should be called after FBInstant.startGameAsync()// resolves. playerImage.src = FBInstant.player.getPhoto();
getDataAsync( )从指定的云存储中检索当前玩家的数据。 参数 · keys 数组<字符串> 唯一键数组，数据检索将针对这些键展开。 · 示例 FBInstant.player .getDataAsync(['achievements', 'currentLife']) .then(function(data) { console.log('data is loaded'); var achievements = data['achievements']; var currentLife = data['currentLife']; }); · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE · · 抛出 CLIENT_UNSUPPORTED_OPERATION · 返回 Promise<对象> 此 promise 将在获得 包含下列信息的对象时被解析：输入数组中指定的每个键的 当前键值对（如存在）。
setDataAsync( )设置要保存到指定云存储的当前玩家 的数据。对于每个独立玩家，游戏最多可存储 1MB 的数据。 参数 · data 对象 此对象包含 应该保存到云存储的一组键值对。对象必须仅包含 可序列化的值 — 任何不可序列化的值都会导致 整个修改被拒绝。 · 示例 FBInstant.player .setDataAsync({ achievements: ['medal1', 'medal2', 'medal3'], currentLife: 300, }) .then(function() { console.log('data is set'); }); · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE · · 抛出 PENDING_REQUEST · · 抛出 CLIENT_UNSUPPORTED_OPERATION · 返回 Promise 此 promise 将在输入值设定时被解析。 注意：promise 被解析并不一定 意味着输入 已被存储，而是这意味着相关数据有效 并已安排要被存储。这还能保证设置的所有值 现在可在 player.getDataAsync 中使用。
flushDataAsync( )立即将玩家数据的任何更改刷新到指定的 云存储中。此函数的调用成本较高， 应主要用于需要立即存储并告知游戏的 重要更改。非重要更改应依赖于开放平台在后台 进行存储。 注意：当此函数的结果待定时， player.setDataAsync 调用将被拒绝。 示例 FBInstant.player .setDataAsync({ achievements: ['medal1', 'medal2', 'medal3'], currentLife: 300, }) .then(FBInstant.player.flushDataAsync) .then(function() { console.log('Data persisted to FB!'); }); · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE · · 抛出 PENDING_REQUEST · · 抛出 CLIENT_UNSUPPORTED_OPERATION · 返回 Promise 此 promise 将在更改保存成功时被解析， 在更改保存失败时被拒绝。
getStatsAsync( )从指定云存储检索当前玩家的统计数据。 参数 · keys 数组<字符串>？ 唯一键数组（可选），针对这些键检索 统计数据。如果调用函数时没有设置此参数，则会提取所有统计数据。 · 示例 FBInstant.player .getStatsAsync(['level', 'zombiesSlain']) .then(function(stats)) { console.log('stats are loaded'); var level = data['level']; var zombiesSlain = data['zombiesSlain']; }); · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE · · 抛出 CLIENT_UNSUPPORTED_OPERATION · 返回 Promise<对象> 此 promise 将在获得 包含下列信息的对象时被解析：输入数组中指定的每个键的 当前键值对（如存在）。
setStatsAsync( )设置要保存到指定云存储的当前玩家 的统计数据。 参数 · stats 对象 此对象包含应作为统计数据 保存到云存储的键值对，能以各种方式显示或 使用这些数据以提高玩家参与度。对象必须 仅包含数值，任何非数值会导致整个 修改被拒绝。 · 示例 FBInstant.player .setStatsAsync({ level: 5, zombiesSlain: 27, }) .then(function() { console.log('data is set'); }); · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE · · 抛出 PENDING_REQUEST · · 抛出 CLIENT_UNSUPPORTED_OPERATION · 返回 Promise 此 promise 将在输入值设定时被解析。 注意：promise 被解析并不一定 意味着输入 已被存储，而是这意味着相关数据经过验证 并已安排要被存储。这还能保证设置的所有值 现在可在 player.getStatsAsync 中使用。
incrementStatsAsync( )保存到指定云存储的当前玩家 的增量统计数据。 参数 · increments 对象 此对象包含一组键值对， 这些键值对表示云存储中每个统计数据的增量是多少。对象必须 仅包含数值，任何非数值会导致整个 修改被拒绝。 · 示例 FBInstant.player .incrementStatsAsync({ level: 1, zombiesSlain: 17, rank: -1, }) .then(function(stats)) { console.log('increments have been made! New values'); var level = data['level']; var zombiesSlain = data['zombiesSlain']; }); · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE · · 抛出 PENDING_REQUEST · · 抛出 CLIENT_UNSUPPORTED_OPERATION · 返回 Promise<对象> 此 promise 将在获得包含下列信息的对象时被解析：输入字典中指定的每个键 的更新键值对。 注意：解析 promise 并不一定 意味着更改 已被存储，而是意味着 增量有效且已安排要被执行 。这还能保证增加的所有值 现在可在 player.getStatsAsync 中使用。
getConnectedPlayersAsync( )提取 ConnectedPlayer 对象的数组，这些对象包含与当前玩家 关联的玩家的信息。 示例 var connectedPlayers = FBInstant.player.getConnectedPlayersAsync() .then(function(players) { console.log(players.map(function(player) { return { id: player.getID(), name: player.getName(), } })); });// [{id: '123456789', name: 'Paul Atreides'}, {id: '987654321', name: 'Duncan Idaho'}] · 抛出 NETWORK_FAILURE · · 抛出 CLIENT_UNSUPPORTED_OPERATION ·
context包含与当前游戏环境相关的功能和属性。
getID( )当前游戏环境的唯一标识。这表示 玩游戏的特定环境（例如：特定的 Messenger 对话或 Facebook 帖子）。如果用户在独立环境中玩游戏，则此标识将 为 null。仅当 FBInstant.startGameAsync 被解析后 才应调用此函数。 示例 // This function should be called after FBInstant.startGameAsync()// resolves.var contextID = FBInstant.context.getID();
getType( )当前游戏环境的类型。 POST — 一个 Facebook 帖子。 THREAD — 一个 Messenger 对话。 GROUP — 一个 Facebook 小组。 SOLO — 默认环境，玩家是唯一的参与者。 仅当 FBInstant.startGameAsync 被解析后才应调用此函数。 示例 // This function should be called after FBInstant.startGameAsync()// resolves.var contextType = FBInstant.context.getType(); 返回("POST" | "THREAD" | "GROUP" | "SOLO") 当前游戏环境的类型。
isSizeBetween( )此函数用于确定加入当前游戏环境的玩家 数量是否在给定的最小值和最大值之间（包括最小值和最大值）。仅当其中一个边界值为 null 时， 才会根据另一个边界值进行检查。在特定 的游戏会话中，此函数始终会返回某 环境内发出的第一个调用的最初结果。后续调用（无论参数是什么）将返回 原始查询的答案，除非游戏环境发生变化且 查询结果被重置。 仅当 FBInstant.startGameAsync 被解析后才应调用此函数。 如果提供的一个或两个参数无效，我们没有适合当前游戏环境 的玩家数量，或者 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} console.log(FBInstant.context.isSizeBetween("test", 5)); (Context size = 4)// null console.log(FBInstant.context.isSizeBetween(0, 100)); (Context size = null)// null
switchAsync( )请求切换到指定环境。如果玩家没有进入该环境的权限， 或玩家未向游戏提供进入 该环境的权限，请求将被拒绝。 promise 将在 游戏切换到指定环境时被解析。 参数 · · 示例 console.log(FBInstant.context.getID());// 1122334455FBInstant.context .switchAsync('1234567890') .then(function() { console.log(FBInstant.context.getID()); // 1234567890 }); · 抛出 INVALID_PARAM · · 抛出 SAME_CONTEXT · · 抛出 NETWORK_FAILURE · · 抛出 USER_INPUT · · 抛出 PENDING_REQUEST · · 抛出 CLIENT_UNSUPPORTED_OPERATION · 返回 Promise 此 promise 将在游戏切换到指定环境时被解析， 在切换失败时被拒绝。
chooseAsync( )为玩家打开一个环境选择对话框。如果玩家选择可用的环境， 客户端将尝试切换到这个环境， 并在成功时解析。而如果玩家退出菜单或 客户端未能切换到新环境，此函数 将被拒绝。 参数 · options 对象？ 此对象用于指定应提供 的环境选项。 · · · · options.maxSize 数字？ 在理想情况下，推荐环境应有 的最大玩家数量。 · · options.minSize 数字？ 在理想情况下，推荐环境应有 的最小玩家数量。 · 示例 console.log(FBInstant.context.getID());// 1122334455FBInstant.context .chooseAsync() .then(function() { console.log(FBInstant.context.getID()); // 1234567890 }); console.log(FBInstant.context.getID());// 1122334455FBInstant.context .chooseAsync({ filters: ['NEW_CONTEXT_ONLY'], minSize: 3, }) .then(function() { console.log(FBInstant.context.getID()); // 1234567890 }); · 抛出 INVALID_PARAM · · 抛出 SAME_CONTEXT · · 抛出 NETWORK_FAILURE · · 抛出 USER_INPUT · · 抛出 PENDING_REQUEST · · 抛出 CLIENT_UNSUPPORTED_OPERATION · 返回 Promise 此 promise 将在游戏切换到用户选择的环境时 被解析。否则此 promise 将被拒绝 （例如用户退出对话框）。
createAsync( )尝试在指定玩家和当前玩家之间创建环境或 切换环境。如果列出的玩家不是当前玩家的关联玩家， 或玩家未提供进入新环境的权限， 则返回的 promise 将被拒绝。 当游戏切换到新环境时， promise 将被解析。 参数 · · 示例 console.log(FBInstant.context.getID());// 1122334455FBInstant.context .createAsync('12345678') .then(function() { console.log(FBInstant.context.getID()); // 5544332211 }); · 抛出 INVALID_PARAM · · 抛出 SAME_CONTEXT · · 抛出 NETWORK_FAILURE · · 抛出 USER_INPUT · · 抛出 PENDING_REQUEST · · 抛出 CLIENT_UNSUPPORTED_OPERATION · 返回 Promise 此 promise 将在游戏切换到新环境时被解析， 在切换失败时被拒绝。
getPlayersAsync( )获取 #contextplayer 对象的数组， 其中包含与当前环境相关的活跃玩家 （在过去 90 天内玩过游戏的用户）的信息。这可能包含当前 玩家。 示例 var contextPlayers = FBInstant.context.getPlayersAsync() .then(function(players) { console.log(players.map(function(player) { return { id: player.getID(), name: player.getName(), } })); });// [{id: '123456789', name: 'Luke'}, {id: '987654321', name: 'Leia'}] · 抛出 NETWORK_FAILURE · · 抛出 CLIENT_UNSUPPORTED_OPERATION · · 抛出 INVALID_OPERATION ·
支付[封闭公测] 包含与游戏商品的支付和购买相关的 函数和属性。
getCatalogAsync( )获取游戏的商品目录。 示例 FBInstant.payments.getCatalogAsync().then(function (catalog) { console.log(catalog); // [{productID: '12345', ...}, ...]}); · 抛出 CLIENT_UNSUPPORTED_OPERATION · · 抛出 PAYMENTS_NOT_INITIALIZED · · 抛出 NETWORK_FAILURE ·
purchaseAsync( )开始特定商品的购买流程。 参数 · · 示例 FBInstant.payments.purchaseAsync({ productID: '12345', developerPayload: 'foobar',}).then(function (purchase) { console.log(purchase); // {productID: '12345', purchaseToken: '54321', developerPayload: 'foobar', ...}}); · 抛出 CLIENT_UNSUPPORTED_OPERATION · · 抛出 PAYMENTS_NOT_INITIALIZED · · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE · 返回 Promise<购买> 此 promise 将在玩家成功购买 商品时被解析，否则会被拒绝。
getPurchasesAsync( )获取玩家未消费的所有购买商品。最佳做法是， 游戏在客户端表明已准备好执行支付相关操作时， 立即获取当前玩家的购买商品。游戏 随后可处理和消费正在等待被消费的任何购买商品。 示例 FBInstant.payments.getPurchasesAsync().then(function (purchases) { console.log(purchase); // [{productID: '12345', ...}, ...]}); · 抛出 CLIENT_UNSUPPORTED_OPERATION · · 抛出 PAYMENTS_NOT_INITIALIZED · · 抛出 NETWORK_FAILURE ·
consumePurchaseAsync( )消费当前玩家拥有的特定购买商品。在为玩家 配置商品效果之前，游戏应先请求 消费已购买的商品。购买的商品成功 消费后，游戏应立即向玩家呈现 购买商品的效果。 参数 · purchaseToken 字符串 应消费的购买商品的 购买口令。 · 示例 FBInstant.payments.consumePurchaseAsync('54321').then(function () { // Purchase successfully consumed! // Game should now provision the product to the player}); · 抛出 CLIENT_UNSUPPORTED_OPERATION · · 抛出 PAYMENTS_NOT_INITIALIZED · · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE · 返回 Promise 此 promise 在成功消费已购买的 商品时被解析。
onReady( )设置一个回调，在支付操作可进行时触发。 参数 · callback 函数 当支付可进行时执行的 回调函数。 · 示例 FBInstant.payments.onReady(function () { console.log('Payments Ready!')}); 返回 void
getLocale( )当前的语言设置。根据这一结果确定当前的游戏应本地化 为哪种语言。在 FBInstant.startGameAsync() 被解析之前，对应的值将不准确。 示例 // This function should be called after FBInstant.startGameAsync()// resolves.var locale = FBInstant.getLocale(); // 'en_US'
getPlatform( )当前运行游戏的平台。对应的值将始终为 null， 直至 FBInstant.initializeAsync() 被解析。 示例 // This function should be called after FBInstant.initializeAsync()// resolves.var platform = FBInstant.getPlatform(); // 'IOS'
getSDKVersion( )表示此 SDK 版本的字符串。 示例 // This function should be called after FBInstant.initializeAsync()// resolves.var sdkVersion = FBInstant.getSDKVersion(); // '2.0'
initializeAsync( )初始化 SDK 库。应在调用其他任何 SDK 函数 之前调用此函数。 示例 FBInstant.initializeAsync().then(function() { // Many properties will be null until the initialization completes. // This is a good place to fetch them: var locale = FBInstant.getLocale(); // 'en_US' var platform = FBInstant.getPlatform(); // 'IOS' var sdkVersion = FBInstant.getSDKVersion(); // '3.0' var playerID = FBInstant.player.getID();}); · 抛出 INVALID_OPERATION · 返回 Promise 此 promise 将在 SDK 可以使用时被解析。
setLoadingProgress( )报告游戏的初始加载进度。 参数 · percentage 数字 介于 0 和 100 之间的数字。 · 示例 FBInstant.setLoadingProgress(50); // Assets are 50% loaded 返回 void
getSupportedAPIs( )提供客户端支持的 API 函数的列表。 示例 // This function should be called after FBInstant.initializeAsync()// resolves.FBInstant.getSupportedAPIs();// ['getLocale', 'initializeAsync', 'player.getID', 'context.getType', ...] 返回 数组<字符串> 客户端显式支持的 API 函数 列表。
getEntryPointData( )返回与启动游戏的入口点相关的任何数据 对象。 对象内容由开发者定义，可通过不同平台 的入口点触发。对于较旧版本的移动客户端， 以及没有与特定入口点相关的数据时， 此函数会返回 null。 示例 // This function should be called after FBInstant.initializeAsync()// resolves.const entryPointData = FBInstant.getEntryPointData();
getEntryPointAsync( )返回启动游戏的入口点 示例 // This function should be called after FBInstant.startGameAsync()// resolves.FBInstant.getEntryPointAsync().then(entrypoint => console.log(entrypoint));// 'admin_message' 仅当 FBInstant.startGameAsync() 被解析后 才应调用此函数。
setSessionData( )为当前环境设置与单个游戏会话相关的 数据。 当游戏需要更新当前的会话数据时， 应调用此函数。此会话数据可用于填充各种负载， 如玩游戏 Webhook。 参数 · sessionData 对象 一个随机数据对象，转变为字符串后，必须小于 或等于 1000 个字符。 · 示例 FBInstant.setSessionData({coinsEarned: 10, eventsSeen: ['start', ...]}); 返回 void
startGameAsync( )表示游戏已完成初始加载， 并准备就绪可以开始游戏。当返回的 promise 被解析时， 环境信息即为最新。 示例 FBInstant.startGameAsync().then(function() { myGame.start();}); · 抛出 INVALID_PARAM · · 抛出 CLIENT_UNSUPPORTED_OPERATION ·
shareAsync( )此函数会调用一个对话框，让用户以下列方式分享指定的内容：在 Messenger 中发送消息，或在用户时间线上发布帖子。可以在分享中添加数据块， 通过此次分享启动的每个游戏会话 都可以通过 FBInstant.getEntryPointData() 访问此数据块。转变为字符串时， 此数据必须小于或等于 1000 个字符。用户 可以选择取消分享操作和关闭对话框， 但无论用户实际是否分享了内容， 返回的 promise 都将在对话框关闭时解析。 参数 · · 示例 FBInstant.shareAsync({ intent: 'REQUEST', image: base64Picture, text: 'X is asking for your help!', data: { myReplayData: '...' },}).then(function() { // continue with the game.}); · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE · · 抛出 PENDING_REQUEST · · 抛出 CLIENT_UNSUPPORTED_OPERATION · · 抛出 INVALID_OPERATION · 返回 Promise 此 promise 将在分享完成或取消时 被解析。
updateAsync( )向 Facebook 通知游戏内发生的更新。这会 暂时将控制权移交给 Facebook，且 Facebook 将确定要 根据更新内容采取什么操作。返回的 promise 将在 Facebook 把 控制权返还给游戏时解析/拒绝。 参数 · payloadUpdatePayload 描述更新的负载。 · 示例 // 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({ action: 'CUSTOM', cta: 'Join The Fight', image: base64Picture, text: { default: 'X just invaded Y\'s village!', localizations: { ar_AR: 'X \u0641\u0642\u0637 \u063A\u0632\u062A ' + '\u0642\u0631\u064A\u0629 Y!', en_US: 'X just invaded Y\'s village!', es_LA: '\u00A1X acaba de invadir el pueblo de Y!', } } template: 'VILLAGE_INVASION', data: { myReplayData: '...' }, strategy: 'IMMEDIATE', notification: 'NO_PUSH',}).then(function() { // closes the game after the update is posted. FBInstant.quit();}); · 抛出 INVALID_PARAM · · 抛出 PENDING_REQUEST · · 抛出 INVALID_OPERATION · 返回 Promise 此 promise 将在 Facebook 把控制权交还给游戏时 被解析。
switchGameAsync( )请求客户端切换到另一个小游戏。切换 失败时，API 将拒绝，否则客户端将加载 新游戏。 参数 · · · data 字符串？ 可选的数据负载。这将设为 要切换到的游戏的入口点数据。转变为字符串时， 必须小于或等于 1000 个字符。 · 示例 FBInstant.switchGameAsync('12345678').catch(function (e) { // Handle game change failure}); · 抛出 USER_INPUT · · 抛出 INVALID_PARAM · · 抛出 PENDING_REQUEST · · 抛出 CLIENT_REQUIRES_UPDATE ·
quit( )退出游戏。 示例 FBInstant.quit(); 返回 void
logEvent( )参数 · eventName 字符串 事件名称。必须为 2 到 40 个字符， 且只能包含“_”、“-”、“ ”和字母数字字符。 · · valueToSum 数字 可选的数值，Facebook 分析利用此参数来 计算总和。 · · parameters 对象 可选的对象，最多可包含 25 个要与事件一同记录的键值对。键必须为 2 到 40 个字符， 且只能包含“_”、“-”、“ ”和 字母数字字符。值的长度必须小于 100 个字符。 · 示例 var logged = FBInstant.logEvent( 'my_custom_event', 42, {custom_property: 'custom_value'},);
onPause( )设置发生暂停事件时将触发的回调。 参数 · · 示例 FBInstant.onPause(function() { console.log('Pause event was triggered!');}) 返回 void
getInterstitialAdAsync( )尝试创建插屏广告的实例。此实例可在之后 预载和显示。 参数 · placementID 字符串 在 Audience Network 设置中设置的 版位编号。 · 示例 FBInstant.getInterstitialAdAsync( 'my_placement_id',).then(function(interstitial) { interstitial.getPlacementID(); // 'my_placement_id'}); · 抛出 ADS_TOO_MANY_INSTANCES · · 抛出 CLIENT_UNSUPPORTED_OPERATION ·
getRewardedVideoAsync( )尝试创建奖励式视频广告的实例。此实例可在之后 预载和显示。 参数 · placementID 字符串 在 Audience Network 设置中设置的 版位编号。 · 示例 FBInstant.getRewardedVideoAsync( 'my_placement_id',).then(function(rewardedVideo) { rewardedVideo.getPlacementID(); // 'my_placement_id'}); · 抛出 ADS_TOO_MANY_INSTANCES · · 抛出 CLIENT_UNSUPPORTED_OPERATION ·
matchPlayerAsync( )[封闭公测] 尝试将当前玩家与等待他人加入游戏的其他玩家 进行匹配。如果匹配成功，将为匹配的玩家创建 一个新的 Messenger 群聊，且玩家的游戏环境将切换到 该群聊。 参数 · matchTag 字符串？ 玩家的可选额外信息，可用于将玩家 加到具有相似玩家的群聊中。具有完全相同标签的玩家 才会加入同一群聊。标签只能包含 字母、数字和下划线，且长度不能超过 100 个 字符。 · · switchContextWhenMatched boolean 可选的额外参数， 指定当找到匹配时，是否将玩家 立即切换到新环境。默认设置为 false，亦即 玩家在匹配成功后，需要明确点击玩游戏按钮 才会切换到新环境。 · 示例 FBInstant .matchPlayerAsync('level1') .then(function() { console.log(FBInstant.context.getID()); // 12345 }); FBInstant .matchPlayerAsync() .then(function() { console.log(FBInstant.context.getID()); // 3456 }); FBInstant .matchPlayerAsync(null, true) .then(function() { console.log(FBInstant.context.getID()); // 3456 }); · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE · · 抛出 USER_INPUT · · 抛出 PENDING_REQUEST · · 抛出 CLIENT_UNSUPPORTED_OPERATION · · 抛出 INVALID_OPERATION · 返回 Promise 当玩家已加入群聊并切换到 群聊环境时，此 promise 被解析。
checkCanPlayerMatchAsync( )[封闭公测] 检查当前玩家是否符合 matchPlayerAsync API 的条件。 示例 FBInstant .checkCanPlayerMatchAsync() .then(canMatch => { if (canMatch) { FBInstant.matchPlayerAsync('level1'); } }); · 抛出 NETWORK_FAILURE · · 抛出 CLIENT_UNSUPPORTED_OPERATION · 返回 Promise<boolean> 当玩家符合与其他玩家匹配的条件时， 此 promise 被解析为 true，否则解析为 false。
getLeaderboardAsync( )获取这款小游戏中的特有排行榜。 参数 · name 字符串 排行榜的名称。小游戏的每个 排行榜必须具有唯一的名称。 · 示例 FBInstant.getLeaderboardAsync('my_awesome_leaderboard') .then(leaderboard => { console.log(leaderboard.getName()); // 'my_awesome_leaderboard' }); · 抛出 LEADERBOARD_NOT_FOUND · · 抛出 NETWORK_FAILURE · · 抛出 CLIENT_UNSUPPORTED_OPERATION · · 抛出 INVALID_OPERATION · · 抛出 INVALID_PARAM · 返回 Promise<排行榜> 此 promise 在获得匹配的排行榜时被解析， 在未找到匹配时被拒绝。
LocalizationsDict
APIError小游戏 SDK 返回的 API 错误
code相关的错误代码
message描述错误的消息
ConnectedPlayer代表与当前玩家关联的玩家的信息。
getID( )获取关联玩家的编号。
getName( )获取玩家的全名。
getPhoto( )获取玩家公开头像的网址。
SignedPlayerInfo代表玩家信息，并包含签名， 签名用于验证对应信息确实来源于 Facebook。
getPlayerID( )获取玩家的编号。 示例 FBInstant.player.getSignedPlayerInfoAsync() .then(function (result) { result.getPlayerID(); // same value as FBInstant.player.getID() });
getSignature( )用于验证此对象确实来源于 Facebook 的签名。此字符串 使用 base64url 编码， 并根据 OAuth 2.0 协议使用 HMAC 版本的应用密钥签名。 您可以通过以下步骤进行验证： 1. 将签名分为两个部分，以“.”字符隔开。 2. 对第一部分（编码签名）执行以下替换操作： 3. o 将短横线 ('-') 替换为加号 ('+') o o 将下划线 ('_') 替换为正斜杠 ('/') o 4. 使用 base64url 编码对产生的字符串解码。 5. 6. 通过 base64url 编码对第二部分（响应负载）进行解码， 第二部分应该是代表 JSON 对象（包含下列字段）的字符串： 7. o algorithm — 始终等于 HMAC-SHA256 o o issued_at — 发出此响应的 unix 时间戳。 o o player_id — 玩家的唯一标识。 o o request_payload — 调用 FBInstant.player.getSignedPlayerInfoAsync 时 指定的 requestPayload 字符串。 o 8. 请采用 HMAC SHA-256 和您的应用密钥散列处理 整个响应负载字符串，并确定它等同于经编码的签名。 9. 10. 还建议您验证响应负载中 的 issued_at 时间戳，确保请求是最近发出的。 应仅在您的服务器中进行签名验证。 不要在客户端进行签名验证， 因为客户端可能会泄漏您的应用密钥。 示例 //// In your game's client//FBInstant.player.getSignedPlayerInfoAsync('my_payload') .then(function (result) { MyServer.send(result.getSignature()); // Example result.getSignature() // 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'// }
ContextPlayer代表与当前玩家在相同环境中玩游戏 的玩家的信息。
getID( )获取相同环境玩家的编号。
getName( )获取经本地化显示的玩家姓名。
getPhoto( )获取玩家公开头像的网址。
AdInstance代表广告实例。
getPlacementID( )返回此广告实例的 Audience Network 版位编号。
loadAsync( )预加载广告。返回的 promise 将在预加载完成时被解析， 在预加载失败时被拒绝。 示例 FBInstant.getInterstitialAdAsync( 'my_placement_id',).then(function(interstitial) { return interstitial.loadAsync();}).then(function() { // Ad loaded}); · 抛出 ADS_FREQUENT_LOAD · · 抛出 ADS_NO_FILL · · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE ·
showAsync( )代表广告。返回的 promise 将在用户 观看完广告时被解析，在广告展示失败或 用户在广告展示期间关闭广告时被拒绝。 示例 var ad = null;FBInstant.getRewardedVideoAsync( 'my_placement_id',).then(function(rewardedVideo) { ad = rewardedVideo; return ad.loadAsync();}).then(function() { // Ad loaded return ad.showAsync();}).then(function() { // Ad watched}); · 抛出 ADS_NOT_LOADED · · 抛出 INVALID_PARAM · · 抛出 NETWORK_FAILURE ·
排行榜小游戏排行榜
getName( )排行榜的名称。 示例 FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { console.log(leaderboard.getName()); // my_leaderboard });
getContextID( )与排行榜相关联环境的编号，如果 排行榜未与特定环境关联，则为 null。 示例 FBInstant.getLeaderboardAsync('contextual_leaderboard') .then(function(leaderboard) { console.log(leaderboard.getContextID()); // 12345678 }); FBInstant.getLeaderboardAsync('global_leaderboard') .then(function(leaderboard) { console.log(leaderboard.getContextID()); // null });
getEntryCountAsync( )获取排行榜中玩家上榜分数的总数量。 示例 FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.getEntryCountAsync(); }) .then(function(count) { console.log(count); }); // 24 · 抛出 NETWORK_FAILURE ·
setScoreAsync( )更新玩家的分数。如果玩家已有分数， 只有新分数更好时，才会替换旧分数。 注意：如果排行榜与特定环境关联，游戏必须处于 该环境，才能为玩家设置分数。 参数 · score 数字 玩家的新分数。必须为 64 位 整数。 · · extraData 字符串？= ion。 与保存的分数关联的元数据。 大小必须小于 2KB。 · 示例 FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.setScoreAsync(42, '{race: "elf", level: 3}'); }) .then(function(entry) { console.log(entry.getScore()); // 42 console.log(entry.getExtraData()); // '{race: "elf", level: 3}' }); · 抛出 LEADERBOARD_WRONG_CONTEXT · · 抛出 NETWORK_FAILURE · · 抛出 INVALID_PARAM · · 抛出 INVALID_OPERATION ·
getPlayerEntryAsync( )检索当前玩家的排行榜上榜分数，或在玩家尚无 上榜分数时返回 null。 示例 FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.getPlayerEntryAsync(); }) .then(function(entry) { console.log(entry.getRank()); // 2 console.log(entry.getScore()); // 42 console.log(entry.getExtraData()); // '{race: "elf", level: 3}' }); · 抛出 NETWORK_FAILURE · · 抛出 INVALID_OPERATION ·
getEntriesAsync( )检索一组排行榜上榜分数，按排行榜上的得分名次 排序。 参数 · count 数字 尝试从排行榜获取的上榜分数 总数量。如果未指定，默认为 10。每条查询命令最多可获取 100 个上榜分数。 · · offset 数字 从排行榜顶部检索 上榜分数的偏移量。 · 示例 FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.getEntriesAsync(); }) .then(function(entries) { console.log(entries.length); // 10 console.log(entries[0].getRank()); // 1 console.log(entries[0].getScore()); // 42 console.log(entries[1].getRank()); // 2 console.log(entries[1].getScore()); // 40 }); FBInstant.getLeaderboardAsync('my_leaderboard') .then(function(leaderboard) { return leaderboard.getEntriesAsync(5, 3); }) .then(function(entries) { console.log(entries.length); // 5 console.log(entries[0].getRank()); // 4 console.log(entries[0].getScore()); // 34 console.log(entries[1].getRank()); // 5 console.log(entries[1].getScore()); // 31 }); · 抛出 NETWORK_FAILURE ·
商品表示游戏的商品信息。 属性 · · · · · · · · · · · priceCurrencyCode 字符串 商品的货币代码 ·
ContextFilter适用于环境选择操作的筛选条件。 “NEW_CONTEXT_ONLY”— 仅显示之前玩游戏未使用过的环境。 “INCLUDE_EXISTING_CHALLENGES”— 包括“当前挑战”部分， 显示玩家积极在其中玩游戏的环境。 “NEW_PLAYERS_ONLY”— 在包含个人信息的部分， 筛选出之前未玩过游戏的用户， 类型：("NEW_CONTEXT_ONLY" | "INCLUDE_EXISTING_CHALLENGES" | "NEW_PLAYERS_ONLY")
购买表示游戏商品的单笔购买。 属性 · developerPayload 字符串？ 开发者指定的字符串， 在商品购买期间提供 · · · · · · purchaseTime 字符串 购买发生时的 Unix 时间戳 · · purchaseToken 字符串 代表该笔购买的一个口令， 可用来消费购买的商品 · · ·
平台代表用户当前在哪个平台玩游戏。 类型：("IOS" | "ANDROID" | "WEB" | "MOBILE_WEB")
ContextSizeResponse如果当前环境的规模介于对象中 指定的 minSize 和 maxSize 值之间， answer 字段为 true，否则为 false。
SharePayload代表用户分享的内容。 属性 · intent("INVITE" | "REQUEST" | "CHALLENGE" | "SHARE") 表示分享的意图。 · · image 字符串 要分享的 base64 编码图片。 · · · · data 对象？ 要附加到分享中的数据块。通过分享 开始的所有游戏会话都可以通过 FBInstant.getEntryPointData() 访问此数据块。 ·
错误代码小游戏 API 可能会返回的错误代码 属性 · ADS_FREQUENT_LOAD 字符串 广告加载太频繁。 · · ADS_NO_FILL 字符串 我们无法向当前的用户投放 广告。如果用户在设备中退订基于兴趣的广告 ，或我们没有广告可展示给该用户，就会出现这种情况 · · ADS_NOT_LOADED 字符串 尝试显示此前未成功 加载的广告。 · · ADS_TOO_MANY_INSTANCES 字符串 同时展示的广告实例 太多。建议您先加载和展示现有广告实例，再新建广告。 · · ANALYTICS_POST_EXCEPTION 字符串 分析 API 在尝试发布事件 时遇到问题。 · · 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 用户界面的其他任何调用。 · · SAME_CONTEXT 字符串 游戏尝试切换到 当前环境。 · · UNKNOWN 字符串 发生了未知或未指定的问题。这是 客户端未指定代码时返回的默认错误代码。 · · USER_INPUT 字符串 用户的选择导致 被拒绝。例如，如果游戏调用环境切换对话框， 而玩家关闭此对话框， 则 promise 拒绝中就会包含此错误代码。 · 示例 FBInstant.startGameAsync().catch(function(e) { console.log(e);});// {code: 'CLIENT_UNSUPPORTED_OPERATION', message: '...'}
UpdateAction表示要执行的更新操作类型。 属性 · CUSTOM 字符串 一项自定义更新，所有内容都由游戏 指定。 · · LEADERBOARD 字符串 与小游戏排行榜相关的 一项更新。 ·
ErrorCodeType
SignedPurchaseRequest示例 Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ
PurchaseConfig注册到游戏的商品的购买请求配置。 属性 · · · developerPayload 字符串？ 由开发者指定的可选负载， 包含在所返回购买的签名请求中。 ·
CustomUpdatePayload代表 FBInstant.updateAsync 的自定义更新。 属性 · · · · · cta （字符串？| LocalizableContent？） 可选的行动号召按钮 文本。默认情况下，我们会使用经本地化的“Play”作为按钮文本。 若要提供自定义行动号召的本地化版本， 应传递一个包含默认行动号召的对象作为“default”值，以及将语言键映射到翻译的 另一个对象作为“localizations”值。 · · image 字符串 base64 编码图片的数据网址。 · · · · data 对象？ 要附加到更新中的数据块。通过更新 开始的所有游戏会话都可以通过 FBInstant.getEntryPointData() 访问此数据块。转变为字符串时， 此数据块必须小于或等于 1000 个字符。 · · strategy 字符串？ 指定更新的发布 方式。可以是下列方式之一： “IMMEDIATE”— 更新应立即发布。 “LAST”— 更新应在游戏会话结束时发布。使用 “LAST”策略发送的是最近发送的更新。 “IMMEDIATE_CLEAR”— 更新将立即发布，并清除其他任何待处理的 更新（如通过“LAST”策略发布的更新）。 如果未指定策略，我们将默认为“IMMEDIATE”。 · · notification 字符串？ 指定自定义更新的 通知设置。可以是“NO_PUSH”或“PUSH”，默认为“NO_PUSH”。 仅将推送通知用于 对接收人来说非常显著且可立即操作的更新。另请注意，并不一定 会发送推送通知，具体取决于用户设置和平台政策。 ·
LeaderboardUpdatePayload表示 FBInstant.updateAsync 的一项排行榜更新。 属性 · action UpdateAction 对于排行榜更新，此属性应为 “LEADERBOARD”。 文本。默认情况下，我们会使用经本地化的“Play Now”作为按钮文本。 · · · · text 字符串？ 可选的文本消息。如果未指定，将会提供 一条经本地化的回退消息。 ·
LocalizableContent代表一个字符串，其中包含最终使用的本地化内容和默认值。 属性 · default 字符串 要使用的字符串的默认值 （查看者的语言设置不是 localizations 对象中的键时）。 · · ·
LeaderboardEntry小游戏排行榜上的一个上榜分数
getScore( )获取上榜分数的分值。 示例 leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getScore()); // 9001 });
getFormattedScore( )获取与上榜分数相关的分值，采用 与排行榜相同的分值格式。 示例 leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getFormattedScore()); // '90.01 meters' });
getTimestamp( )获取排行榜上榜分数的上次更新时间戳。 示例 leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getTimestamp()); // 1515806355 });
getRank( )获取玩家分数在排行榜中的排行。 示例 leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getRank()); // 2 });
getExtraData( )获取与分数相关的开发者指定负载， 或在没有设定时返回 null。 示例 leaderboard.setScoreAsync(42, '{race: "elf", level: 3}'); .then(function(entry) { console.log(entry.getExtraData()); // '{race: "elf", level: 3}' }); 返回 字符串？ 与分数相关的开发者指定负载，为可选 参数。
getPlayer( )获取与上榜分数相关玩家的信息。 示例 leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getPlayer().getName()); // Sally });
LeaderboardPlayer与上榜分数相关玩家的详情。
getName( )获取经本地化显示的玩家姓名。 示例 leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getPlayer().getName()); // Sally });
getPhoto( )返回玩家公开头像的网址。 示例 leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getPlayer().getPhoto()); // <photo_url> });
getID( )获取玩家在游戏中的唯一标识。 示例 leaderboard.setScoreAsync(9001) .then(function(entry) { console.log(entry.getPlayer().getID()); // 12345678 }); 为方便大家群策群力，我们创建了一个 Facebook Instant Game 交流群：814298516 。 欢迎同学们加入交流开发和运营经验。
| 
官方Q群
发表于 2018-8-16 10:59:51
收藏