关系链互动数据

# 关系链互动数据

在开放关系链数据能力的基础上，小游戏新增互动型托管数据 ,提供关系链互动能力，用于实现小游戏内QQ好友互动（点赞，送礼物等）的功能。

关系链互动数据能力支持：

好友间互赠 50 种游戏内道具
提供成功互动后的主域回调，满足互动后激励的场景。
开发者配置互动交互文案后，用户可在QQ游戏其他场景，获得互动提醒。
用户发起互动后，可通过QQ分享消息告诉好友。
从定向分享进入游戏，可向分享发起者发起一次免确认的互动，用于满足分享后激励的场景。

互动型托管数据与普通托管数据的对比如下：

-	普通托管数据	互动型托管数据
单用户数据大小	128块不大于1K的数据	只提供1个32位整形存储。
数据来源	开放数据域/主域/后台	开放数据域/后台
数据流向	开放数据域	开放数据域/主域
写入方式	覆盖写	递增(在开放数据域)，覆盖写(后台)
写入时机	任意时机	用户点击弹框确认
写入对象	任意（本人/好友)	只能写好友(在开放数据域)，本人(后台)
读取对象	任意（本人/好友)	只能读本人

关系链互动数据可以从小游戏主域直接读取。

提供以下前端接口读写关系链互动数据

qq.getUserInteractiveStorage读取当前用户关系链互动数据
qq.modifyFriendInteractiveStorage修改当前用户好友的关系链互动数据

提供以下后端接口读写关系链互动数据

setUserInteractiveData 写当前用户的关系链互动数据

# qq.getUserInteractiveStorage(Object object)

获取当前用户互动型托管数据对应 key 的数据

# 参数

# Object object

属性	类型	必填	说明
keyList	string	是	要获取的 key 列表
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

# object.success 回调函数

# 参数

# Object res

属性	类型	说明
encryptedData	string	加密数据，包含互动型托管数据的值。解密后的结果为一个 KVDataList，每一项为一个 KVData。用户数据的签名验证和加解密
iv	string	加密算法的初始向量，详见用户数据的签名验证和加解密

# object.fail 回调函数

# 参数

# Object res

属性	类型	说明
errMsg	string	错误信息

# qq.modifyFriendInteractiveStorage(Object object)

修改好友的互动型托管数据，该接口只可在开放数据域下使用。

# 参数

# Object object

属性	类型	默认值	必填	说明
key	string		是	需要修改的数据的 key，目前可以为 '1' - '50'
opNum	number		是	需要修改的数值，目前只能为 1
operation	string		是	修改类型
friendInfo	object		是	发送对象的 friendInfo
title	string		否	分享标题，如果设置了这个值，则在交互成功后自动询问用户是否分享给好友（需要配置模板规则）
imageUrl	string		否	分享图片地址，详见 qq.shareMessageToFriend 同名参数（需要配置模板规则）
quiet	boolean	false	否	是否静默修改（不弹框），静默修改需要用户通过快捷分享消息卡片进入才有效，代表分享反馈操作，无需填写 toUser，直接修改分享者与被分享者交互数据
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

# object.operation 的合法值

值	说明
add	加

# object.fail 回调函数

# 参数

# Object res

属性	类型	说明
errMsg	string	错误信息

# 使用模板规则进行交互

每次调用该接口会弹窗询问用户是否确认执行该操作，需要在 game.json 中设置 modifyFriendInteractiveStorageTemplates 来定制交互的文案。 modifyFriendInteractiveStorageTemplates 是一个模板数组，每一个模板需要有 key, action, object 参数，还有一个可选参数 ratio，详细说明见示例配置：

{
  "modifyFriendInteractiveStorageTemplates": [
    {
      "key": "1", // 这个 key 与接口中同名参数相对应，不同的 key 对应不同的模板
      "action": "赠送", // 互动行为
      "object": "金币", // 互动物品
      "ratio": 10 // 物品比率，opNum * ratio 代表物品个数
    }
  ]
}

1
2
3
4
5
6
7
8
9
10

最后生成的文案为 "确认 ${action} ${nickname} ${object}？"，或者 "确认 ${action} ${nickname} ${object} x ${opNum * ratio}？"

# jsserver

安全可控的后台JS运行环境
提供读写用户关系链数据的能力

# 代码编写规范要求

1.定义函数main

2.export函数main

//checkInteractiveData.js
exports.main = function (arg) {
   console.log(arg);
   return JSON.stringify({ "ret": true });
}

1
2
3
4
5

# 代码上传/下载

1.工具配置文件 project.config.json 新增配置项

// project.config.json
{
    "jsserverRoot": "jsserver"
}

1
2
3
4

2.配置生效后，该目录不参与编译，所以建议该目录不在小游戏代码根目录里。

├── game.js
├── jsserver 
│   └── checkInteractiveData.js

1
2
3

3.鼠标右键点击对应目录，可以看到新建JS的选择项，点击即可创建一个JS文件，这里一个JS文件即为一个小游戏前端请求JSServer的入口，文件名即入口标识，如果已经有开发者创建同名JS，会失败, 目前只支持上传 checkInteractiveData.js。

4.工具可以下载该小游戏已经上传的JS代码,分为开发版和正式版。

正式版小程序发起请求会拉取正式版的JSServer代码执行
开发版,体验版小程序以及开发工具发起的请求会拉取开发版的JSServer代码执行
请注意开发版本和正式版本各自只有一份代码

# JSServer提供的开放接口

获取用户本人的openid

接口名：qq.getOpenId()

参数：无

返回：openid

let openid = qq.getOpenId()

读取用户托管数据存储

接口名：qq.getFriendUserStorage()

参数：Array.<String>

返回：Array.<KVData>

const friendsStorage = qq.getFriendUserStorage(["friendGift"]);
const userList = friendsStorage.user_item;

1
2

写用户托管数据存储

接口名：qq.setFriendUserStorage()

参数：openid，Array.<KVData>

返回：{"errcode":0}

注意：KVData中的key不要使用下划线_

let ret = qq.setFriendUserStorage(openid, [{
  key: "friendGift",
  value: JSON.stringify(giftRecords)
}]
)
if (ret.errcode != 0){
   console.error("set err") //console 所打印的日志会通过接口返回给前端
} else {
   console.log("set success")
}

1
2
3
4
5
6
7
8
9
10

# 备注

JSServer内所有接口均为同步。
JSServer单次处理请求超时时间为1s，超过后任务会被终止。

# 互动型托管数据结合JSServer实现好友互动能力

qq.modifyFriendInteractiveData 接口在具体写入操作之前会默认执行开发者托管在JSServer上的一段代码，要求开发者使用开发者工具上传文件checkInteractiveData.js。
开发者在checkInteractiveData.js可以拿到参数
- 用户本人openid:qq.getOpenId()
- 目标好友openid:toUser
- 增加的数据:opNum
- 修改数据的index(1 ~ 50): key
- 要求返回字段bool型 "ret" 字段告诉微信请求是否合法
开发者可以在checkInteractiveData.js中读写普通托管数据来存储用户互动记录。

# 定向分享

提供给定向分享能力，支持用户游戏内向指定好友发起分享。

# qq.shareMessageToFriend(Object object)

给指定的好友分享游戏信息，该接口只可在开放数据域下使用

# 参数

# Object object

属性	类型	必填	说明
friendInfo	object	是	发送对象的 friendInfo
title	string	否	转发标题，不传则默认使用当前小游戏的昵称。
imageUrl	string	否	转发显示图片的链接，可以是网络图片路径（仅 QQ CDN 域名路径）或本地图片文件路径或相对代码包根目录的图片文件路径。显示图片长宽比是 5:4
success	function	否	接口调用成功的回调函数
fail	function	否	接口调用失败的回调函数
complete	function	否	接口调用结束的回调函数（调用成功、失败都会执行）

定向分享不允许直接在开放数据域设置 query 参数需要设置请参见游戏域 qq.setMessageToFriendQuery 接口

# friendInfo

用户信息

# 属性

# string avatarUrl

用户的QQ头像 url

# string nickname

用户的QQ昵称

# string openid

用户 openid

# KVData

托管的 KV 数据

# 属性

# string key

数据的 key

# string value

数据的 value

# boolean qq.setMessageToFriendQuery(Object object)

设置 qq.shareMessageToFriend 接口 query 字段的值

# 参数

# Object object

属性	类型	默认值	必填	说明
shareMessageToFriendScene	number		是	需要传递的代表场景的数字，需要在 0 - 50 之间

# 返回值

# boolean

是否设置成功

← 消息虚拟支付 →