Facebook 游戏开发更新文档
API 参考文档 v5.0
更新日志
广告 API 两款全新的 API 可方便投放插屏广告和奖励式视频广告。要求 配置游戏以便在小游戏中投放广告。
Player Stats API，用于设置、获取并自动增加与玩家相关的 整数统计数据。辅以捆绑包配置的新增内容， 可为玩家统计数据配置元数据， 通过 Facebook 平台级集成显示统计数据。
getEntryPointAsync API，获取启动游戏的入口点。
Custom Update Dev Localization 自定义更新 API 的增补， 让开发者能够提供更新内容的本地化版本。
重大更改将 CLIENT_REQUIRES_UPDATE 更名为 CLIENT_UNSUPPORTED_OPERATION
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
·
返回 Promise<SignedPlayerInfo> 以 #signedplayerinfo 对象解析的 promise。
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 对象的数组，这些对象包含与当前玩家 关联的玩家的信息。
注意：只有当 FBInstant.startGameAsync() 被解析时，此 promise 才会解析。
示例
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
·
返回 Promise<数组<ConnectedPlayer>> 此 promise 将在 获得关联玩家对象列表时被解析。
context
包含与当前游戏环境相关的功能和属性。
getID( )
当前游戏环境的唯一标识。这表示 玩游戏的特定环境（例如：特定的 Messenger 对话或 Facebook 帖子）。如果用户在独立环境中玩游戏，则此标识将 为 null。仅当 FBInstant.startGameAsync 被解析后 才应调用此函数。
示例
// This function should be called after FBInstant.startGameAsync()// resolves.var contextID = FBInstant.context.getID();
返回字符串？ 当前游戏环境的唯一标识。
getType( )
当前游戏环境的类型。
仅当 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。
参数
·
minSize数字？ 环境规模查询的最小边界值。
·
·
minSize数字？ 环境规模查询的最大边界值。
·
·
maxSize数字？
·
示例
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
返回 ContextSizeResponse？
switchAsync( )
请求切换到指定环境。如果玩家没有进入该环境的权限， 或玩家未向游戏提供进入 该环境的权限，请求将被拒绝。 promise 将在 游戏切换到指定环境时被解析。
参数
·
id字符串 目标环境的编号。
·
示例
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.filters数组<ContextFilter>？ 适用于环境推荐的一组筛选条件 。
·
·
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 将被解析。
参数
·
playerID字符串 玩家的编号
·
示例
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 天内玩过游戏的用户）的信息。这可能包含当前 玩家。
注意：只有当 FBInstant.startGameAsync() 被解析时，此 promise 才会解析。
示例
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
·
返回 Promise<数组<ContextPlayer>>
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'
返回字符串 SDK 版本。
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。
仅当 FBInstant.startGameAsync() 被解析后 才应调用此函数。
示例
// This function should be called after FBInstant.initializeAsync()// resolves.const entryPointData = FBInstant.getEntryPointData();
返回对象？ 与当前入口点相关的数据。
getEntryPointAsync( )
返回启动游戏的入口点
示例
// This function should be called after FBInstant.initializeAsync()// resolves.FBInstant.getEntryPointAsync().then(entrypoint => console.log(entrypoint));// 'admin_message'
返回字符串 用户启动游戏时所在的入口点的 名称
setSessionData( )
为当前环境设置与单个游戏会话相关的 数据。
当游戏需要更新当前的会话数据时， 应调用此函数。此会话数据可用于填充各种负载， 如玩游戏 webhook。
参数
·
sessionData对象 一个随机数据对象，转变为字符串后，必须小于 或等于 1000 个字符。
·
示例
FBInstant.setSessionData({coinsEarned: 10, eventsSeen: ['start', ...]});
返回 void
startGameAsync( )
表示游戏已完成初始加载， 并准备就绪可以开始游戏。当返回的 promise 被解析时， 环境信息即为最新。
示例
FBInstant.startGameAsync().then(function() {
myGame.start();});
·
抛出 INVALID_PARAM
·
·
抛出 CLIENT_UNSUPPORTED_OPERATION
·
返回 Promise 此 promise 将在游戏应该启动时被解析。
shareAsync( )
此函数会调用一个对话框，让用户以下列方式分享指定的内容：在 Messenger 中发送消息，或在用户时间线上发布帖子。可以在分享中添加数据块， 通过此次分享启动的每个游戏会话 都可以通过 FBInstant.getEntryPointData() 访问此数据块。转变为字符串时， 此数据必须小于或等于 1000 个字符。用户 可以选择取消分享操作和关闭对话框， 但无论用户实际是否分享了内容， 返回的 promise 都将在对话框关闭时解析。
参数
·
payloadSharePayload，指定要分享的内容。详情 请参阅示例。
·
示例
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 把 控制权返还给游戏时解析/拒绝。
参数
·
payloadCustomUpdatePayload 描述更新的负载。
·
示例
// 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
·
返回 Promise 此 promise 将在 Facebook 把控制权交还给游戏时 被解析。
quit( )
退出游戏。
示例
FBInstant.quit();
返回 void
logEvent( )
通过 Facebook 分析记录应用事件。请参阅 https://developers.facebook.com/docs/javascript/reference/v2.8#app_events 详细了解 Fcaebook 分析。
参数
·
eventName字符串 事件名称。必须为 2 到 40 个字符， 且只能包含“_”、“-”、“ ”和字母数字字符。
·
·
valueToSum数字 可选的数值，Facebook 分析利用此参数来 计算总和。
·
·
parameters对象 可选的对象，最多可包含 25 个要与事件一同记录的键值对。键必须为 2 到 40 个字符， 且只能包含“_”、“-”、“ ”和 字母数字字符。值的长度必须小于 100 个字符。
·
示例
var logged = FBInstant.logEvent(
'my_custom_event',
42,
{custom_property: 'custom_value'},);
返回 APIError？ 如果事件记录错误，将返回错误； 否则返回 null。
onPause( )
设置发生暂停事件时将触发的回调。
参数
·
func函数 发生暂停事件时将调用的函数。
·
返回 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
·
返回 Promise 此 promise 将在获得 #adinstance 时被解析；在获得 #apierror 时被拒绝 （如果未能创建）。
getRewardedVideoAsync( )
尝试创建奖励式视频广告的实例。此实例可在之后 预载和显示。
参数
·
placementID字符串 在 Audience Network 设置中设置的 版位编号。
·
示例
FBInstant.getRewardedVideoAsync(
'my_placement_id',).then(function(rewardedVideo) {
rewardedVideo.getPlacementID(); // 'my_placement_id'});
·
抛出 ADS_TOO_MANY_INSTANCES
·
·
抛出 CLIENT_UNSUPPORTED_OPERATION
·
返回 Promise 此 promise 将在获得 #adinstance 时被解析；在获得 #apierror 时被拒绝 （如果未能创建）。
LocalizationsDict
代表特定字符串的语言设置与翻译之间的映射。 每个属性均为可选且包含五个字符的 Facebook 语言代码，格式为 xx_XX。 请参阅https://www.facebook.com/translations/FacebookLocales.xml， 获取受支持的语言代码的完整列表。
类型：对象
APIError
小游戏 SDK 返回的 API 错误
code
相关的错误代码
类型：ErrorCodeType
message
描述错误的消息
类型：字符串
SignedPlayerInfo
代表玩家信息，并包含签名， 签名用于验证对应信息确实来源于 Facebook。
getPlayerID( )
获取玩家的编号。
返回字符串 玩家的编号
getSignature( )
用于验证此对象确实来源于 Facebook 的签名。此字符串 使用 base64url 编码， 并根据 OAuth 2.0 协议使用 HMAC 版本的应用密钥签名。
您可以通过以下 4 步进行验证：
·
将签名分为两个部分，以“.”字符隔开。
·
·
通过 base64url 编码对第一部分（编码后的签名）进行解码。
·
·
通过 base64url 编码对第二部分（响应负载）进行解码， 第二部分应该是代表 JSON 对象（包含下列字段）的字符串： ** algorithm — 始终等于 HMAC-SHA256。 ** issued_at — 发出此响应的 unix 时间戳。 ** player_id — 玩家的唯一标识。 ** request_payload — 您在调用 FBInstant.player.getSignedPlayerInfoAsync 时 指定的 requestPayload 字符串。
·
·
请采用 HMAC SHA-256 和您的应用密钥散列处理 整个响应负载字符串，并确定它等同于经编码的签名。
·
·
还建议您验证响应负载中 的 issued_at 时间戳，确保请求是最近发出的。
·
应仅在您的服务器中进行签名验证。不要在客户端进行签名验证， 因为客户端可能会泄漏您的应用密钥。
示例
Eii6e636mz5J47sfqAYEK40jYAwoFqi3x5bxHkPG4Q4.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTUwMDM5ODY3NSwicGxheWVyX2lkIjoiMTI0OTUyNTMwMTc1MjIwMSIsInJlcXVlc3RfcGF5bG9hZCI6Im15X2ZpcnN0X3JlcXVlc3QifQ
返回字符串 签名字符串。
ConnectedPlayer
代表与当前玩家关联的玩家的信息。
getID( )
获取关联玩家的编号。
返回字符串 关联玩家的编号
getName( )
获取玩家的全名。
返回字符串？ 即玩家的全名
getPhoto( )
获取玩家公开头像的网址。
返回字符串？ 玩家公开头像的网址
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
·
返回 Promise
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
·
返回 Promise
ContextFilter
适用于环境选择操作的筛选条件。 “NEW_CONTEXT_ONLY”— 仅显示之前玩游戏未使用过的环境。 “INCLUDE_EXISTING_CHALLENGES”— 包括“当前挑战”部分， 显示玩家积极在其中玩游戏的环境。 “NEW_PLAYERS_ONLY”— 在包含个人信息的部分， 筛选出之前未玩过游戏的用户，
类型：("NEW_CONTEXT_ONLY" | "INCLUDE_EXISTING_CHALLENGES" | "NEW_PLAYERS_ONLY")
平台
代表用户当前在哪个平台玩游戏。
类型：("IOS" | "ANDROID" | "WEB" | "MOBILE_WEB")
ContextSizeResponse
如果当前环境的规模介于对象中 指定的 minSize 和 maxSize 值之间， answer 字段为 true，否则为 false。
类型：{answer: boolean, minSize: number?, maxSize: number?}
SharePayload
代表用户分享的内容。
类型：对象
属性
·
intent("INVITE" | "REQUEST" | "CHALLENGE" | "SHARE") 表示分享的意图。
·
·
image字符串 要分享的 base64 编码图片。
·
·
text字符串 要分享的文本消息。
·
·
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 的参数 无效。可表示错误类型、参数的无效数字，或 语义问题（例如，将不可序列化的对象传递到 序列化函数）。
·
·
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: '...'}
ErrorCodeType
小游戏错误代码，#errorcode 中的一种
类型：字符串
CustomUpdatePayload
代表 FBInstant.updateAsync 的自定义更新。
类型：对象
属性
·
action字符串 对于自定义更新，此属性应为“CUSTOM”。
·
·
template字符串 此自定义更新所使用模板的编号。 模板应在 fbapp-config.json 中预定义。请参阅 [捆绑包配置文档]https://developers.facebook.com/docs/games/instant-games/bundle-config，获取有关 fbapp-config.json 的文档。
·
·
cta（字符串？| LocalizableContent？） 可选的行动号召按钮 文本。默认情况下，我们会使用经本地化的“Play”作为按钮文本。 若要提供自定义行动号召的本地化版本， 应传递一个包含默认行动号召的对象作为“default”值，以及将语言键映射到翻译的 另一个对象作为“localizations”值。
·
·
image字符串 base64 编码图片的数据网址。
·
·
text（字符串 | LocalizableContent） 一条文本消息， 或者是一个包含默认文本作为“default”值的对象 以及另一个将语言键映射到翻译内容作为“localizations”值的对象。
·
·
data对象？ 要附加到更新中的数据块。通过更新 开始的所有游戏会话都可以通过 FBInstant.getEntryPointData() 访问此数据块。转变为字符串时， 此数据块必须小于或等于 1000 个字符。
·
·
strategy字符串？ 指定更新的发布 方式。可以是下列方式之一： “IMMEDIATE”— 更新应立即发布。 “LAST”— 更新应在游戏会话结束时发布。使用 “LAST”策略发送的是最近发送的更新。 “IMMEDIATE_CLEAR”— 更新将立即发布，并清除其他任何待处理的 更新（如通过“LAST”策略发布的更新）。 如果未指定策略，我们将默认为“IMMEDIATE”。
·
·
notification字符串？ 指定自定义更新的 通知设置。可以是“NO_PUSH”或“PUSH”，默认为“NO_PUSH”。 仅将推送通知用于 对接收人来说非常显著且可立即操作的更新。另请注意，并不一定 会发送推送通知，具体取决于用户设置和平台政策。
·
LocalizableContent
代表一个字符串，其中包含最终使用的本地化内容和默认值。
类型：对象
属性
·
default字符串 要使用的字符串的默认值 （查看者的语言设置不是 localizations 对象中的键时）。
·
·
localizationsLocalizationsDict 指定每种语言设置中用于观看者 的字符串。 请参阅 https://www.facebook.com/translations/FacebookLocales.xml， 获取受支持的完整语言列表。
为方便大家群策群力，我们创建了一个 Facebook Instant Game 交流群：814298516 。 欢迎同学们加入交流开发和运营经验。
