开放平台V2文档

# 游戏圈（选接）

通过游戏圈组件，可以在游戏内为用户提供游戏交流、用户互动、反馈收集等社区能力；同时，游戏圈内容也会在微信各场景（例如：发现-游戏）被用户看见，了解详情可查看《微信开放文档 - 游戏圈》 (opens new window)说明。

# 准备事项

在微信官方平台申请相应插件权限，用于补充游戏一些额外的游戏圈基础功能，如：分享图片到游戏圈、推送小游戏动态、展示R活动等。

# 申请插件权限

登录《微信公众平台》 (opens new window)，申请插件权限：申请地址 (opens new window)

# 在配置中声明使用插件

在微信小游戏的 game.json 配置文件中申明使用插件，如下所示：

"plugins": {
  "MiniGameCommon": {
    "version": "latest",
    "provider": "wxaed5ace05d92b218",
    "contexts": [
      {
        "type": "isolatedContext"
      }
    ]
  }
}

# 基础库最低可用版本

  • 请确保游戏基础库最低可用版本不低于 2.0.3（设置路径：《微信公众平台》 (opens new window) > 设置 > 基本设置 > 版本设置 > 基础库最低可用版本），因 createGameClubButton 接口的部分参数要求，这里建议选择不低于 2.30.3 的版本；
  • 请在游戏项目工程根目录下的 project.config.json 配置中，将 libVersion 选项设置为《微信公众平台》 (opens new window)后台选择的版本号；
  • 如果游戏项目工程根目录中存在 project.private.config.json 配置文件，且其中也包含 libVersion 选项（无则忽略），同样需要将其设置为《微信公众平台》 (opens new window)后台选择的版本号。

以上针对基础库最低可用版本的三点说明，请确保设置正确，否则将可能导致游戏圈的部分功能不可用！

# 创建游戏圈入口

# 接口说明

用于在游戏内创建一个用于打开游戏圈的按钮，并在点击时跳转至游戏圈主页，该按钮也支持打开游戏圈不同页面，包括指定帖子、指定话题、指定活动，满足游戏内不同场景需要。

sdkInstance.createGameClubButton(options);

最低基础库版本要求

若用户客户端基础库版本低于 2.0.3，调用 sdkInstance.createGameClubButton(options) 接口将弹出升级提示，并返回 undefined，需要游戏客户端对返回值做兼容处理！

若传递了 openlink 参数，则要求用户客户端基础库版本不低于 2.30.3！

# 参数说明

选项 类型 必填 默认值 说明
type string 是 text

按钮类型

  • text - 文本按钮，允许自定义文本及背景色
  • image - 图片按钮，仅允许设置背景贴图，背景贴图会直接拉伸至按钮的宽高
text string 否 -- 文本按钮的文本，仅当 type 为 text 时有效
icon string 否 --

图片按钮的图标，仅当 type 为 image 时有效

  • green - 绿色图标
  • white - 白色图标
  • dark - 有黑色圆角背景的白色图标
  • light - 有白色圆角背景的绿色图标
image string 否 -- 图片按钮的背景图片，仅当 type 为 image 时有效
style object 是 -- 按钮样式
    style.top number 是 0 按钮左上角纵坐标
    style.left number 是 0 按钮左上角横坐标
    style.width number 是 100 按钮宽度
    style.height number 是 32 按钮高度
    style.borderWidth number 否 0 按钮边框宽度
    style.borderRadius number 否 0 按钮边框圆角
    style.borderColor string 否 #07c160 按钮边框颜色，格式为 6 位 16 进制数
    style.backgroundColor string 否 #07c160 按钮背景颜色，格式为 6 位 16 进制数
    style.color string 否 #ffffff 按钮文本颜色，格式为 6 位 16 进制数
    style.fontSize number 否 12 按钮文本字号
    style.textAlign string 否 center

按钮文本水平居中方式

  • left - 居左
  • center - 居中
  • right - 居右
    style.lineHeight number 否 32 按钮文本行高
openlink string 否 -- 设置后可以跳转到对应的活动页面，可登录《微信公众平台》后台，进入“功能 > 游戏运营工具箱 > 游戏圈 > 管理”，由帖子或话题的"游戏内跳转ID"生成；不设置时默认跳转至游戏圈主页（注意，该参数必须设置为真实有效的值，没有的情况下请直接去除该参数，不允许留空，否则将导致点击按钮时报错）
hasRedDot boolean 否 true 当传递了openlink 值时，此字段生效，决定创建的按钮是否显示红点

# 返回值说明

调用 sdkInstance.createGameClubButton(options) 接口，将返回一个用于打开游戏圈的按钮实例。具体实例方法如下表所示：

方法 类型 说明
show function 用于显示游戏圈按钮
hide function 用于隐藏游戏圈按钮
destroy function 用于销毁游戏圈按钮
onTap function 用于绑定游戏圈按钮的点击事件回调函数
offTap function 用于注销游戏圈按钮的点击事件回调函数

# 特别说明

注意，由于微信的策略限制，打开游戏圈的动作无法由游戏原生按钮触发，必须使用上述API创建指定按钮，并在点击时自动跳转。但往往游戏拥有自己的视觉设计体系，而该API创建的按钮并不符合美术需求，遇到这种情况可通过以下两种方式解决：

  • 设置 type 为 text 时，将按钮文本、边框颜色及背景颜色均置空，以便创建一个视觉透明的按钮，并利用宽高及横纵坐标将其覆盖在游戏原生按钮上；
  • 设置 type 为 image 时，将游戏的按钮图片素材作为背景图片。

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 创建游戏圈按钮
const gameClubButton = sdkInstance.createGameClubButton({
  type: "text",
  text: "游戏圈",
  style: {
    top: 376,
    left: 40,
    width: 100,
    height: 32,
    backgroundColor: "#07c160",
    borderWidth: 0,
    borderColor: "#07c160",
    borderRadius: 0,
    color: "#ffffff",
    fontSize: 12,
    textAlign: "center",
    lineHeight: 32
  }
});

// 先判断 gameClubButton 是否存在再使用
// 因为当用户的客户端基础库版本低于 2.0.3 时，调用 sdkInstance.createGameClubButton 接口将返回 undefined
// 若传递了 openlink 参数，且用户的客户端基础库版本低于 2.30.3，调用 sdkInstance.createGameClubButton 接口也将返回 undefined
if (gameClubButton) {
  // 显示游戏圈按钮
  gameClubButton.show();

  // 隐藏游戏圈按钮
  gameClubButton.hide();

  // 销毁游戏圈按钮
  gameClubButton.destroy();

  // 添加或移除游戏圈按钮的点击事件监听函数
  const listener = function(response) {
    console.log(response.code); // 事件响应状态码，为0时表示打开游戏圈成功，其他非0状态码表示打开失败
    console.log(response.message); // 打开成功或失败时的相应描述信息
  };

  gameClubButton.onTap(listener);
  gameClubButton.offTap(listener);
}

# 分享网络图片到游戏圈

# 接口说明

用于在游戏内分享网络图片到游戏圈。

sdkInstance.shareImageToGameClub(options);

# 参数说明

选项 类型 必填 默认值 说明
title string 是 -- 分享标题
content string 是 -- 分享文案
url string 否 -- 分享图片的网络路径，其对应的域名需要添加至“服务器域名（downloadFile 合法域名）”中
success function 否 -- 接口调用成功的回调函数
fail function 否 -- 接口调用失败的回调函数
complete function 否 -- 接口调用完成的回调函数，成功或失败均会调用

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

sdkInstance.shareImageToGameClub({
  title: "xxxx",
  content: "xxxxxxxxxx",
  url: "https://www.example.com/static/images/1.jpg",
  success: function(response) {
    console.log(response);
  },
  fail: function(error) {
    console.log(error);
  },
  complete: function(result) {
    // do something here...
  }
});

# 分享Canvas截图到游戏圈

# 接口说明

用于在游戏内分享Canvas截图（一般为游戏画面截图）到游戏圈。

sdkInstance.shareCanvasToGameClub(options);

# 参数说明

选项 类型 必填 默认值 说明
title string 是 -- 分享标题
content string 是 -- 分享文案
x number 否 0 截取 canvas 的左上角横坐标
y number 否 0 截取 canvas 的左上角纵坐标
width number 否 canvas 的宽度 截取 canvas 的宽度
height number 否 canvas 的高度 截取 canvas 的高度
destWidth number 否 canvas 的宽度 目标文件的宽度，会将截取的部分拉伸或压缩至该数值
destHeight number 否 canvas 的高度 目标文件的高度，会将截取的部分拉伸或压缩至该数值
fileType string 否 png

目标文件的类型

  • png - PNG图片
  • jpg - JPG图片
quality number 否 1.0 JPG图片的质量，仅当 fileType 为 jpg 时有效；取值范围为 0.0 ~ 1.0，不含 0，不在范围内时视作 1.0
success function 否 -- 接口调用成功的回调函数
fail function 否 -- 接口调用失败的回调函数
complete function 否 -- 接口调用完成的回调函数，成功或失败均会调用

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

sdkInstance.shareCanvasToGameClub({
  title: "xxxx",
  content: "xxxxxxxxxx",
  success: function(response) {
    console.log(response);
  },
  fail: function(error) {
    console.log(error);
  },
  complete: function(result) {
    // do something here...
  }
});

# 获取用户游戏圈数据

# 接口说明

用于在游戏内获取用户游戏圈数据，该接口需要在用户授权登录成功后调用。

sdkInstance.getGameClubData(options);

最低基础库版本要求

若用户客户端基础库版本低于 2.25.4，调用 sdkInstance.getGameClubData(options) 接口将中断用户当前操作并弹出升级提示，不会报错！

# 参数说明

选项 类型 必填 默认值 说明
dataTypeList object[] 是 -- 需要获取的数据指标对象数组
    dataTypeList[n].type number 是 -- 见下文 type 表格说明
    dataTypeList[n].subKey string 否 -- 部分 type 需要传，见下文数据指标 type 说明
success function 否 -- 获取成功的回调函数
fail function 否 -- 获取失败的回调函数
complete function 否 -- 获取完成的回调函数，成功或失败均会调用

# 数据指标 type 说明

取值 说明 subKey
1 加入游戏圈时间，秒级Unix时间戳 无需传入
3 用户禁言状态；0：正常，1：禁言 无需传入
4 当天（自然日）点赞贴子数 无需传入
5 当天（自然日）评论贴子数 无需传入
6 当天（自然日）发表贴子数 无需传入
7 当天（自然日）发表视频贴子数 无需传入
8 当天（自然日）点赞官方贴子数 无需传入
9 当天（自然日）评论官方贴子数 无需传入
10 当天（自然日）发表到游戏圈话题的贴子数 传入话题ID，从《微信公众平台》 > 游戏圈话题管理处获取

# 返回值说明

选项 类型 说明
code number 响应状态码，为 0 时表示获取成功，其他非 0 状态码均表示获取失败
data object 获取成功时返回用户游戏圈数据，失败时返回 null
    data.signature string 使用 sha1(rawData sessionkey) 得到的字符串，用于校验用户信息
    data.encryptedData string 包括 GameClubData 在内的加密数据，详见加密数据解密算法
    data.iv string 加密算法的初始向量
    data.cloudID string 敏感数据对应的云ID，开通云开发的游戏才会返回，可通过云调用直接获取开放数据
    data.dataList string 经过解密处理的 GameClubData 数据，见下文 GameClubData 数据结构说明
message string 获取成功或失败时的相应描述信息

# GameClubData 数据结构

选项 类型 说明
dataList object[] 游戏圈相关数据的对象数组
    dataList[n].dataType object 与输入的 dataType 数据指标对象一致
    dataList[n].value number 不同 type 返回的 value 含义不同，见上文数据指标 type 说明

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 若用户客户端基础库版本低于 2.25.4，调用此接口将中断用户当前操作并弹出升级提示，不会报错！
sdkInstance.getGameClubData({
  dataTypeList: [
    { type: 1 },
    { type: 3 },
    { type: 4 },
    { type: 5 },
    { type: 6 },
    { type: 7 },
    { type: 8 },
    { type: 9 }
  ],
  success: function(response) {
    console.log(response);
  },
  fail: function(error) {
    console.log(error);
  },
  complete: function(result) {
    // do something here...
  }
});
Last Updated: 2024/11/10 18:46:15

← 游戏对局回放（选接） →