关系链数据 | MOGS API 文档

# 关系链数据

为了丰富游戏的社交玩法，我们为开发者提供关系链数据能力。通过关系链数据能力，可满足游戏内排行榜、好友超越等使用场景。

每一个用户的关系链数据包括 3 部分：

该用户好友的用户数据
该用户所在的某个群的群成员的用户数据
该用户的可能对该游戏感兴趣的好友列表

获取关系链数据的 API：

mogs.getFriendCloudStorage 获取当前用户也玩该小游戏的好友的用户数据 mogs.getGroupCloudStorage 获取当前用户在某个群中也玩该小游戏的成员的用户数据（QQ平台暂不支持） mogs.getPotentialFriendList 获取当前用户对游戏感兴趣的未注册的好友名单这三个 API 的返回结果都是一个对象数组，数组的每一个元素都是一个表示用户数据的对象，其结构如下：

属性	类型	说明
openId	string	用户的 openId
avatarUrl	string	用户的平台头像 url
nickName	string	用户的平台昵称
data	Object	用户的游戏数据（普通型托管数据）

用户的游戏数据指的是用户的段位、战绩等游戏业务特有的数据，通过调用 mogs.setUserCloudStorage() 可以将当前用户的游戏数据托管在平台后台（如微信、QQ、MOGS）。只有被托管过数据的用户，才会被视为玩过该小游戏的用户，才会出现在 mogs.getFriendCloudStorage() 和 mogs.getGroupCloudStorage() 返回的对象数组中。

除此之外，我们还提供了以下 API：

mogs.removeUserCloudStorage() 删除用户托管数据中指定字段的数据 mogs.getUserCloudStorage() 获取当前用户的托管数据 mogs.getUserCloudStorage、mogs.getFriendCloudStorage() 和 mogs.getGroupCloudStorage() 只能在开放数据域中调用。 mogs.setUserCloudStorage() 和 mogs.removeUserCloudStorage() 可以同时在主域和开放数据域中调用。

# 开放数据域

开放数据域是一个封闭、独立的 JavaScript 作用域。

# 开启方式

# 手动开启

要让代码运行在开放数据域，需要在 game.json 中添加配置项 openDataContext 指定开放数据域的代码目录。添加该配置项表示小游戏启用了开放数据域，这将会导致一些限制。

{
  "deviceOrientation": "portrait",
  "openDataContext": "src/myOpenDataContext"
}

1
2
3
4

同时还需要在该目录下创建 index.js 作为开放数据域的入口文件，其代码运行在开放数据域。game.js 是整个游戏的入口文件，其代码运行在主域。对应以上配置，应该有如下的目录结构：

├── src
|   └── myOpenDataContext
|       ├── index.js
|       └── ...
├── game.js
├── game.json
└── ...

1
2
3
4
5
6
7

src/myOpenDataContext 是开放数据域的代码目录，除 src/myOpenDataContext 以外是主域的代码目录。

# 借助引擎

Cocos Creator：可在构建项目时配置 “开放数据域目录”，构建 “微信小游戏开放数据域” 项目，具体见接入微信小游戏的开放数据域 (opens new window)

# 包导入

开放数据域下的包使用 @timi/mogs-sdk-open。

// 导入
import mogs from '@timi/mogs-sdk-open';

// 使用 API
mogs.getUserCloudStorage({
  keyList: ['1'],
});

1
2
3
4
5
6
7

# 限制

# require/import 限制

主域和开放数据域中的代码不能相互 require。以如下的目录结构为例：

├── src
|   └── myOpenDataContext
|       ├── index.js
|       ├── util.js
|       └── ...
├── lib
|   └── render.js
└── game.js

1
2
3
4
5
6
7
8

在 game.js 中不能 require('src/myOpenDataContext/util') 在 src/myOpenDataContext/index.js 中不能 require('../../lib/render.js')

# 通信

开放数据域不能向主域发送消息。

主域可以向开放数据域发送消息。调用 mogs.getOpenDataContext() 方法可以获取开放数据域实例，调用实例上的 OpenDataContext.postMessage() 方法可以向开放数据域发送消息。

// game.js
let openDataContext = mogs.getOpenDataContext()
openDataContext.postMessage({
  text: 'hello',
  year: (new Date()).getFullYear()
})

1
2
3
4
5
6

在开放数据域中通过 mogs.onMessage() 方法可以监听从主域发来的消息。

// src/myOpenDataContext/index.js
mogs.onMessage(data => {
  console.log(data)
  /* {
    text: 'hello',
    year: 2018
  } */
})

1
2
3
4
5
6
7
8

# 展示关系链数据

# 使用原生 API

如果想要展示通过关系链 API 获取到的用户数据，如绘制排行榜等业务场景，需要将排行榜绘制到 sharedCanvas 上，再在主域将 sharedCanvas 渲染上屏。

// src/myOpenDataContext/index.js
let sharedCanvas = mogs.getSharedCanvas()

function drawRankList (data) {
  data.forEach((item, index) => {
    // ...
  })
}

mogs.getFriendCloudStorage({
  success: res => {
    let data = res.data
    drawRankList(data)
  }
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

sharedCanvas 是主域和开放数据域都可以访问的一个离屏画布。在开放数据域调用 mogs.getSharedCanvas() 将返回 sharedCanvas。

// src/myOpenDataContext/index.js
let sharedCanvas = mogs.getSharedCanvas()
let context = sharedCanvas.getContext('2d')
context.fillStyle = 'red'
context.fillRect(0, 0, 100, 100)

1
2
3
4
5

在主域中可以通过开放数据域实例访问 sharedCanvas，通过 drawImage() 方法可以将 sharedCanvas 绘制到上屏画布。

// game.js
let openDataContext = mogs.getOpenDataContext()
let sharedCanvas = openDataContext.canvas

let canvas = mogs.createCanvas()
let context = canvas.getContext('2d')
context.drawImage(sharedCanvas, 0, 0)

1
2
3
4
5
6
7

sharedCanvas 的宽高只能在主域设置，不能在开放数据域中设置。

// game.js
sharedCanvas.width = 400
sharedCanvas.height = 200

1
2
3

sharedCanvas 本质上也是一个离屏 Canvas，而重设 Canvas 的宽高会清空 Canvas 上的内容。所以要通知开放数据域去重绘 sharedCanvas。

// game.js

openDataContext.postMessage({
  command: 'render'
})
// src/myOpenDataContext/index.js
openDataContext.onMessage(data => {
  if (data.command === 'render') {
    // ... 重绘 sharedCanvas
  }
})

1
2
3
4
5
6
7
8
9
10
11

# 借助引擎

Cocos Creator：可在主域添加 SubContextView 组件，另外构建一个小游戏开放数据域项目。具体可见 cocos creator 接入微信小游戏的开放数据域 (opens new window)

# 限制

当小游戏启动开放数据域，即在 game.json 中添加 openDataContext 配置项时。小游戏环境会对主域和开放数据域应用一些限制。

# 主域

sharedCanvas 只能被绘制到上屏 canvas 上。
上屏 canvas 不能调用 toDataURL，其 context 不能调用 getImageData、readPixels。
sharedCanvas 不能调用 toDataURL 和 getContext。
不能将上屏 canvas 和 sharedCanvas 以任意形式绘制到其他 canvas 上，包括 drawImage、createPattern、texImage2D、texSubImage2D。
sharedCanvas 的宽高只能在主域设置。

# 开放数据域

不能设置 sharedCanvas 的宽高

# 开放数据域下的 API

开放数据域只能调用有限的 API，如下所示：

# 帧率

requestAnimationFrame()
cancelAnimationFrame()

# Timer

setTimeout()
clearTimeout()
setInterval()
clearInterval()

# 系统信息

mogs.getSystemInfo()
mogs.getSystemInfoSync()

# 触摸事件

mogs.onTouchStart()
mogs.onTouchMove()
mogs.onTouchEnd()
mogs.onTouchCancel()
mogs.offTouchStart()
mogs.offTouchMove()
mogs.offTouchEnd()
mogs.offTouchCancel()

# 画布

mogs.createCanvas()

开放数据域的所有 canvas 只支持 2d 渲染模式，同时不可使用 toDataURL 以及 toTempFilePath(Sync)

# 图片

mogs.createImage()

微信限制：开放数据域的 Image 只能使用本地或微信 CDN 的图片，不能使用开发者自己服务器上的图片。对于非本地或非微信 CDN 的图片，可以先从主域 mogs.downloadFile() 下载图片文件，再通过 OpenDataContext.postMessage() 把文件路径传给开放数据域去使用。

# 开放数据

mogs.getFriendCloudStorage()
mogs.getGroupCloudStorage()
mogs.getUserCloudStorage()
mogs.setUserCloudStorage()
mogs.removeUserCloudStorage()

# 监听主域消息

mogs.onMessage()

# 开放数据域下的数据限制

开放数据域下的用户数据以 key-value 对的形式存储，使用 mogs.setUserClousStorage() 可以对其进行写入。key-value 列表有如下限制：

每个 openid 所标识的用户在每个游戏上托管的数据不能超过 128 个 key-value 对。
上报的 key-value 列表当中每一项的 key+value 长度都不能超过 1K(1024) 字节。
上报的 key-value 列表当中每一个 key 长度都不能超过 128 字节。

← 渲染关系链互动数据 →