Facebook 游戏开发更新文档 API 参考文档 v5.0

2024-11-07 技术教程

Facebook 游戏开发更新文档API 参考文档 v5.0

更新日志

1.广告 API两款全新的 API 可方便投放插屏广告和奖励式视频广告。要求配置游戏以便在小游戏中投放广告。

2.Player StatsAPI，用于设置、获取并自动增加与玩家相关的整数统计数据。辅以捆绑包配置的新增内容，可为玩家统计数据配置元数据，通过 Facebook 平台级集成显示统计数据。

3.getEntryPointAsyncAPI，获取启动游戏的入口点。

4.Custom Update Dev Localization自定义更新 API 的增补，让开发者能够提供更新内容的本地化版本。

5.重大更改将 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(),

}

}));

});// [{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(),

}

}));

});// [{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!',

}

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

Facebook 游戏开发更新文档 API 参考文档 v5.0

热门

最新文章

随机文章

TAGS标签

Facebook 游戏开发更新文档 API 参考文档 v5.0

相关推荐

相关推荐

热门

最新文章

随机文章

TAGS标签