Facebook InstantGame API v4.0 说明

如果您需要 SDK 对应的 jsd.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 一个用来检索数据的key的数组

代码示例:

FBInstant.player
  .getDataAsync(['achievements', 'currentLife'])
  .then(function(data) {
     console.log('data is loaded');
     var achievements = data['achievements'];
     var currentLife = data['currentLife'];
});

返回值 Promise 如果发送的Key存在,则通过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 返回一个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_CNen_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 返回客户端支持的 API 函数列表

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

你可能感兴趣的:(Facebook InstantGame API v4.0 说明)