文档

# qq.shareMessageToFriend

# 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 接口

# qq.setMessageToFriendQuery

# boolean qq.setMessageToFriendQuery(Object object)

设置 qq.shareMessageToFriend 接口 query 字段的值，该接口在游戏主域使用

# 参数

# Object object

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

# 返回值

# boolean

是否设置成功

# qq.setUserCloudStorage

# qq.setUserCloudStorage(Object object)

对用户托管数据进行写数据操作。允许同时写多组 KV 数据。

# 参数

# Object object
属性 类型 默认值 必填 说明
KVDataList Array.<KVData> 是 要修改的 KV 数据列表
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

# 托管数据的限制

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

# qq.removeUserCloudStorage

# qq.removeUserCloudStorage(Object object)

删除用户托管数据当中对应 key 的数据。

# 参数

# Object object
属性 类型 默认值 必填 说明
keyList Array.<string> 是 要删除掉 key 列表
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

# qq.onInteractiveStorageModified

# qq.onInteractiveStorageModified(function callback)

监听成功修改好友的互动型托管数据事件，该接口在游戏主域使用

# 参数

# function callback

事件发生的回调函数，只有一个参数为 qq.modifyFriendInteractiveStorage 传入的 key

# qq.modifyFriendInteractiveStorage

# 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}？"

# qq.getUserInteractiveStorage

# 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.getUserCloudStorage

# qq.getUserCloudStorage(Object object)

获取当前用户托管数据当中对应 key 的数据。该接口只可在开放数据域下使用

# 参数

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

参数

Object res

属性 类型 说明
KVDataList Array.<KVData> 用户托管的 KV 数据列表

# qq.getSharedCanvas

# Canvas qq.getSharedCanvas()

获取主域和开放数据域共享的 sharedCanvas。只有开放数据域能调用。

# 返回值

# Canvas

# qq.getGroupCloudStorage

# qq.getGroupCloudStorage(Object object)

获取群同玩成员的游戏数据。小游戏通过群分享卡片打开的情况下才可以调用。该接口只可在开放数据域下使用。

# 参数

# Object object
属性 类型 默认值 必填 说明
shareTicket string 是 群分享对应的 shareTicket
keyList Array.<string> 是 要拉取的 key 列表
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）
# object.success 回调函数

参数

Object res

属性 类型 说明
data Array.<UserGameData> 群同玩成员的托管数据

# qq.getFriendCloudStorage

# qq.getFriendCloudStorage(Object object)

拉取当前用户所有同玩好友的托管数据。该接口只可在开放数据域下使用

# 参数

# Object object
属性 类型 默认值 必填 说明
keyList Array.<string> 是 要拉取的 key 列表
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）
# object.success 回调函数

参数

Object res

属性 类型 说明
data Array.<UserGameData> 同玩好友的托管数据

# qq.getPotentialFriendList

# qq.getPotentialFriendList(Object object)

获取可能对游戏感兴趣的未注册的好友名单。每次调用最多可获得 5 个好友，此接口只能在开放数据域中使用

# 参数

# Object object
属性 类型 默认值 必填 说明
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）
# object.success 回调函数

参数

Object res

属性 类型 说明
list Array.<FriendInfo> 可能对游戏感兴趣的未注册好友名单

# qq.getReactiveFriendList

| 基础库 1.20.0 开始支持，低版本需做兼容处理。

# qq.getReactiveFriendList(Object object)

获取曾经玩过游戏但最近不常玩的好友名单。每次调用最多可获得 5 个好友，此接口只能在开放数据域中使用

# 参数

# Object object
属性 类型 默认值 必填 说明
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）
# object.success 回调函数

参数

Object res

属性 类型 说明
list Array.<FriendInfo> 曾经玩过游戏，但最近不常玩的好友名单

# FriendInfo

用户信息

# 属性

# string avatarUrl

用户的 QQ 头像 url

# string nickname

用户的 QQ 昵称

# string openid

用户 openid

# UserGameData

托管数据

# 属性

# string avatarUrl

用户的 QQ 头像 url

# string nickname

用户的 QQ 昵称

# string openid

用户的 openid

# Array.<KVData> KVDataList

用户的托管 KV 数据列表

# KVData

托管的 KV 数据

# 属性

# string key

数据的 key

# string value

数据的 value

# 举例 1

比如某小游戏有一个分数排行榜，分数排行榜需要记录分数以及获得分数的耗时（游戏内的排行榜需要展示耗时），可以在qqgame同级别定义一个cost_ms字段，存储耗时的毫秒数。 分配一个不和已定义的托管数据的 key 相冲突的 key 作为分数排行榜的 key，如 "score"。

在玩家耗时 36500ms 后，获得本周最高分 16 分，则需要更新分数，假设当前时间戳为 1513080573， 则完整 value 在序列化之前的内容如下：

{
  "qqgame": {
    "score": 16,
    "update_time": 1513080573
  },
  "cost_ms": 36500
}
1
2
3
4
5
6
7

最终序列化为 string 后，value 为"{"qqgame":{"score":16,"update_time": 1513080573},"cost_ms":36500}"。

# 举例 2

比如要在手 Q 下拉或游戏中心的好友 PK 王等处展示排行榜(与举例 1 中游戏内的排行榜不同),value 值直接传string类型的分数,战力或关卡等数字即可。

# OpenDataContext-qq.getUserInfo

# qq.getUserInfo(Object object)

在无须用户授权的情况下，批量获取用户信息。该接口只在开放数据域下可用

# 参数

# Object object
属性 类型 默认值 必填 说明
openIdList Array.<string> [] 否 要获取信息的用户的 openId 数组，如果要获取当前用户信息，则将数组中的一个元素设为 'selfOpenId'
lang string en 否 显示用户信息的语言
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

object.lang 的合法值

值 说明
en 英文
zh_CN 简体中文
zh_TW 繁体中文
# object.success 回调函数

参数

Object res

属性 类型 说明
data Array.<Object> 用户信息列表

res.data 的结构

属性 类型 说明
avatarUrl string 用户头像图片 url
city string 用户所在城市
country string 用户所在国家
gender number 用户性别
language string 显示 country province city 所用的语言
nickName string 用户昵称
openId string 用户 openId
province string 用户所在省份

# 示例代码

获取当前用户和其他几个用户的用户信息

qq.getUserInfo({
  openIdList: [
    "selfOpenId",
    "ownAP0b9qt6AzvYOSWOX8VX8KMq0",
    "ownAP0QJHIN2w3X60EUsj2Vah5Ig",
    "ownAP0f8ANWUCcloXN1oZPfxtz0g",
  ],
  lang: "zh_CN",
  success: (res) => {
    console.log("success", res.data);
  },
  fail: (res) => {
    reject(res);
  },
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

← 安全内容 →