如果您需要 SDK
对应的 js
和 d.ts
文件,可以在这个 Github 仓下载 FBInstantGameDTS
FBInstant
Instant Games SDK 的顶级命名空间.
player
包含当前用户信息的一些方法和属性
getID()
玩家的唯一标识ID。一个Facebook用户的id是不会改变的。同一个Facebook的用户,在不同的游戏里会有不用的id。
注意,该方法必须放在 FBInstant.initializeAsync() 的回调里。
代码示例:
// 该方法必须放在 FBInstant.initializeAsync() 的回调里
var playerID = FBInstant.player.getID();
返回值:string,用户的唯一ID
getName()
用户的名字。
注意,该方法必须放在 FBInstant.initializeAsync() 的回调里。
代码示例:
//该方法必须放在 FBInstant.initializeAsync() 的回调里。
var playerName = FBInstant.player.getName();
返回值:string,用户的名字
getPhoto()
用户头像的链接地址。头像的图片始终为正方形,尺寸最小为200x200。建议在游戏中使用的时候,先将图像缩放到所需的大小。
注意,该方法必须放在 FBInstant.initializeAsync() 的回调里。
警告:由于跨域的问题,在 canvas 里使用图片会有问题。要防止此情况,请将图像的 cross-origin 属性设置为 "anonymous"
代码示例:
var playerImage = new Image();
playerImage.crossOrigin = 'anonymous';
playerImage.src = FBInstant.player.getPhoto();
返回值:string,用户的头像的链接地址
getDataAsync()
取回当前用户在FB平台储存的数据
参数
• keys Array
代码示例:
FBInstant.player
.getDataAsync(['achievements', 'currentLife'])
.then(function(data) {
console.log('data is loaded');
var achievements = data['achievements'];
var currentLife = data['currentLife'];
});
返回值 Promise
setDataAsync()
把当前用户的数据储存在FB平台上。每个用户可以储存1MB的数据。
代码示例:
参数
• data Object 需要储存的数据,包含key-value的数据对象。对象只能包含可以序列号的值,任何不可序列化的值都会导致储存失败。
代码示例:
FBInstant.player
.setDataAsync({
achievements: ['medal1', 'medal2', 'medal3'],
currentLife: 300,
})
.then(function() {
console.log('data is set');
});
返回值 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!');
});
返回值 Promise 数据储存成功会返回一个promise,如果保存失败则返回拒绝
getConnectedPlayersAsync()
获取和当前玩家有关联的玩家列表信息。
代码示例:
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'}]
返回值 Promise
context
包含当前游戏环境的一些方法和属性
getID()
当前游戏来源的唯一id。它代表了当前游戏是在哪玩的(例如:是在 messenger 的对话里还是 facebook 的网页里)。如果是在独立页面玩的游戏,这个id值为 null。只有在 FBInstant.startGameAsync 方法被调用后,这个结果才能保证是正确的。
代码示例:
//该方法必须放在 FBInstant.startGameAsync() 的回调里。
var contextID = FBInstant.context.getID();
返回值 string,当前游戏环境的id。
getType()
当前游戏的环境类型。
代码示例:
//该方法必须放在 FBInstant.startGameAsync() 的回调里。
var contextType = FBInstant.context.getType();
返回值 ("POST" | "THREAD" | "GROUP" | "SOLO") 当前游戏环境的类型。
switchAsync()
请求切换到指定的游戏环境。如果玩家没有进入该环境的权限,或者玩家没有允许切换到该环境,该方法都会被拒绝。如果成功切换到指定游戏环境,将会返回一个 promise.
参数
• id string 想要进入的环境ID
代码示例:
console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
.switchAsync('1234567890')
.then(function() {
console.log(FBInstant.context.getID());
// 1234567890
});
返回值 Promise 当游戏切换到指定环境,返回一个 promise,失败会被拒绝。
chooseAsync()
为玩家打开一个游戏环境选择列表。如果玩家选择了一个可用的环境,客户端将尝试切到那个环境,如果成功,返回 resolve。如果王佳退出菜单,或者客户端未能切换到新环境,返回 reject.
请求切换到指定的游戏环境。如果玩家没有进入该环境的权限,或者玩家没有允许切换到该环境,该方法都会被拒绝。如果成功切换到指定游戏环境,将会返回一个 promise.
参数
• options Object 提供可选择的环境对象。
• options.filters Array
• options.maxSize number 理想情况下,环境对象的最大值
• options.minSize number 理想情况下,环境对象的最小值
代码示例:
console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
.chooseAsync()
.then(function() {
console.log(FBInstant.context.getID());
// 1234567890
});
console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
.chooseAsync({
filters: ['NEW_CONTEXT_ONLY'],
minSize: 3,
})
.then(function() {
console.log(FBInstant.context.getID());
// 1234567890
});
返回值 Promise 当游戏切换到指定环境,返回一个 promise,失败会返回reject(例如,用户取消了对话框)
createAsync()
在当前玩家和指定玩家之间,尝试创建或切换一个环境。如果指定玩家不能玩这个游戏,或者玩家决绝进入新环境,则返回 promise 的 recject。如果成功切换到新游戏的环境时,则返回 promise 的 resolve。
参数
• playerID string 用户的 ID
代码示例:
console.log(FBInstant.context.getID());
// 1122334455
FBInstant.context
.createAsync('12345678')
.then(function() {
console.log(FBInstant.context.getID());
// 5544332211
});
返回值 Promise 当游戏成功切换到指定环境,返回一个 promise 的 resolve,失败会返回reject
getLocale()
获取用户的地域信息。 例如 zh_CN、 en_US
全部的地域信息数据,请看此链接 https://www.facebook.com/translations/FacebookLocales.xml 。
该方法必须放在 FBInstant.initializeAsync() 的回调里
代码示例:
// 该方法必须放在 FBInstant.initializeAsync() 的回调里
var locale = FBInstant.getLocale(); // 'en_US'
返回值 string,当前地域信息。
getPlatform()
当前游戏运行在哪个平台。该方法必须放在 FBInstant.initializeAsync() 的回调里
代码示例:
该方法必须放在 FBInstant.initializeAsync() 的回调里
var platform = FBInstant.getPlatform(); // 'IOS'
返回值 string,当前游戏运行的平台("IOS" | "ANDROID" | "WEB" | "MOBILE_WEB")
getSDKVersion()
获取SDK的版本号,用字符串来表示。
代码示例:
var sdkVersion = FBInstant.getSDKVersion(); // '4.0'
返回值 string,SDK 的版本号。
initializeAsync()
初始化SDK,应当在任何其他的API使用前调用。
代码示例:
FBInstant.initializeAsync().then(function() {
// 在初始化完成之前,下面这些属性都是无法得到的。必须要放在这个回调方法里。
var locale = FBInstant.getLocale(); // 'en_US'
var platform = FBInstant.getPlatform(); // 'IOS'
var sdkVersion = FBInstant.getSDKVersion(); // '4.0'
var playerID = FBInstant.player.getID();
});
返回值 Promise当sdk 初始化完成后会返回 promise
setLoadingProgress()
告诉平台游戏初始化资源加载的进度
参数
• percentage number 0到100之间的数字
代码示例:
FBInstant.setLoadingProgress(50); // 50%的资源被加载了
getSupportedAPIs()
提供当前客户端支持的 API 函数列表。
代码示例:
//该方法必须放在 FBInstant.initializeAsync() 的回调里
FBInstant.getSupportedAPIs();
// ['getLocale', 'initializeAsync', 'player.getID', 'context.getType', ...]
返回值 Array
getEntryPointData()
返回与游戏启动的入口点相关的数据对象。
对象的内容是开发人员定义的,并且可以在不同平台的入口点触发。在老的移动客户端上会返回 null。如果特定的入口点没有数据时,也会返回 null。
代码示例:
//该方法必须放在 FBInstant.initializeAsync() 的回调里
const entryPointData = FBInstant.getEntryPointData();
返回值 Object 与当前入口点相关的数据。
setSessionData()
为当前环境设置游戏的数据。
每当游戏想要更新当前会话的数据时,可以调用该方法。本次会话的数据可以用于填充多种有效载荷,如游戏webhooks
参数
• sessionData Object 一个任意的数据对象,必须小于1000个字符
代码示例:
FBInstant.setSessionData({coinsEarned: 10, eventsSeen: ['start', ...]});
返回值 void
startGameAsync()
这表明游戏已经加载完资源,可以开始玩了。当返回 promise 的 resolve 时,环境信息将会更新。
代码示例:
FBInstant.startGameAsync().then(function() {
//在这我们可以确定用户点击了开始游戏的按钮
myGame.start();
});
返回值 Promise当游戏应当开始玩的时候会返回 promise
shareAsync()
这将启动一个对话框,让用户共享指定的内容,可能是一个 Messenger 里的消息,或者是用户时间线上的一个帖子。一个blob数据可以附加在分享上,当游戏通过分享启动时,可以通过 FBInstant.getEntryPointData() 方法获取。这个数据必须少于1000个字符。用户可以选择取消分享,或者关闭对话框,但不论用户是否真的分享了内容,都会返回 promise 的 resolve。
参数
• payload SharePayload 要分享的内容,请看示例代码
代码示例:
FBInstant.shareAsync({
intent: 'REQUEST',
image: base64Picture,
text: 'X is asking for your help!',
data: { myReplayData: '...' },
}).then(function() {
// 继续游戏
});
返回值 Promise 不管分享成功或失败,都会返回 promise 的 resolve
updateAsync()
通知Facebook在游戏中发生的更新。这将暂时把控制权交给Facebook,而Facebook将决定根据更新的内容来做什么。当Facebook将控制权归还给游戏时,将返回 promise 的 resolve/reject.
参数
• payload **CustomUpdatePayload ** 要更新的内容
代码示例:
//这将发送一个自定义更新。如果游戏是运行在一个 messenger 的对话里,
//它将发送一条带有图文的消息到指定的对话里。
//如果其他用户通过这条消息启动了游戏,
//这些游戏会话将可以通过 FBInstant.getEntryPointData()
//方法获取附加的 blob 数据。
FBInstant.updateAsync({
action: 'CUSTOM',
cta: 'Join The Fight',
template:'join_fight',
image: base64Picture,
text: 'X just invaded Y\'s village!',
data: { myReplayData: '...' },
strategy: 'IMMEDIATE',
notification: 'NO_PUSH',
}).then(function() {
// closes the game after the update is posted.
FBInstant.quit();
});
返回值 Promise 当Facebook将控制权归还给游戏时返回 promise
quit()
退出游戏
代码示例:
FBInstant.quit();
返回值 void
logEvent()
使用 Facebook 来分析一个 app,更多细节请参见: https://developers.facebook.com/docs/javascript/reference/v2.8#app_events
参数
• eventName string 事件的名称。必须是2到40个字符,只能包含'_', '-', ' '和字母数字的字符。
• valueToSum number 一个可选的数字,FB分析可以计算它。
• parameters Object 一个可选的对象,它可以包含多达25个 key-value,以记录事件。key 必须是2-40个字符,只能包含'_', '-', ' '和字母数字的字符。 Value 必须少于100个字符。
代码示例:
var logged = FBInstant.logEvent(
'my_custom_event',
42,
{custom_property: 'custom_value'},
);
返回值 CodeError 如果事件记录失败,返回错误信息,否则返回 null.
onPause()
设置一个暂停事件触发时调用的回调方法。
参数
• func Function 当暂停事件触发时调用的方法。
返回值 void
ConnectedPlayer
表示与当前玩家有关联的其他玩家的信息。
getID()
得到关联玩家的ID
返回值 string 关联玩家的ID
getName()
得到关联玩家的名字
返回值 string 关联玩家的名字
getPhoto()
得到关联玩家的公开头像
返回值 string 关联玩家的公开头像的 url