开放平台V2文档

# 群标签能力（选接）

群标签能力是抖音小游戏继粉丝群、官方群后提供的第三大群聊能力，接入后玩家在群内聊天时，昵称后会自动携带由开发者配置并下发的称号标签，点击标签即可查询获得方式以及启动游戏。了解更多内容请阅读抖音小游戏官方文档《群标签能力接入方案》 (opens new window)。

注意，群标签依托抖音群聊展示，需游戏已具备官方群或公会群，且由群主在群聊设置中挂载该游戏的标签后才会生效。群聊能力的接入说明请查看《群聊能力》章节。

# 核心优势

  • 群内玩家称号铭牌：玩家在群聊中的昵称后自动携带开发者下发的称号标签，丰富群聊话题，增加粉丝聊天积极性。
  • 群内复访入口：其他群成员点击该铭牌即可查看称号的获得方式，并从铭牌卡直接启动游戏，为游戏增加一个群内复访入口。

# 示例介绍

群聊发现标签 点击标签查看铭牌卡&游戏入口 铭牌规则详情页&游戏入口

# 接入收益

  • 提高群活跃度：丰富群聊话题，增加粉丝聊天积极性，提高群的整体活跃度。
  • 提高用户留存：增加群内复访游戏入口，提高用户留存。

# 接入流程简述

群标签能力的整体业务路径如下图所示：

# 接入流程介绍

# 开通群标签能力

登录《抖音开放平台控制台》 (opens new window)后台，进入「能力」-「能力中心」-「运营能力」-「抖音群聊能力」-「群标签能力」进行能力开通

# 完成基础配置

基础配置指的是配置铭牌卡的背景图，此图应用于该游戏的所有标签卡片。

若调整背景图，将同步更新所有标签卡片；最多可上传 1 张图，图片尺寸 400*180，大小不超 1M，支持 jpg、jpeg、png 格式；图片上传后会进入审核链路，审核结果将通过开放平台站内信同步。

基础配置入口 上传背景图

# 新增标签配置

新增标签配置指的是配置标签的展示文案，包括标签 ICON、标签名称、标签颜色、获取规则、有效期。

这里不涉及任何接口能力，只是用于配置标签的展示样式；成功提交后进入审核流程，审核通过会以站内信&端内通知，审核通过后可以获得标签 ID 用于技术配置；单游戏最多上架 9 个标签。

新增标签入口 配置标签文案&图片素材

# API接入

# API说明

# 获取用户群聊标签信息

# 接口说明

用于获取当前登录玩家已佩戴的群聊标签信息（2.4.0 版本新增）。

sdkInstance.getUserGroupTagInfo(options);

最低基础库版本要求

当用户的客户端基础库版本低于 3.80.0 时，调用 sdkInstance.getUserGroupTagInfo(options) 接口将直接触发失败回调函数，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）！

注意，已删除的标签不会出现在返回的 userGroupTags 列表中。

# 调用时机

在需要展示玩家当前称号时调用；也可在下发标签前调用，若玩家已佩戴目标标签则跳过下发，避免重复调用。

# 参数说明

参数说明如下表所示：

选项 类型 必填 默认值 说明
success function 否 -- 接口调用成功的回调函数
fail function 否 -- 接口调用失败的回调函数
complete function 否 -- 接口调用完成的回调函数，成功或失败均会调用

# 返回值说明

注意

返回值格式：JSON 格式。

选项 类型 说明
code string / number 响应状态码，为 0 时表示接口调用成功，其他非 0 状态码均表示接口调用失败
data object 接口调用成功时返回标签数据，失败时返回 null
    data.userGroupTags object[] 玩家已佩戴的群聊标签对象数组，无标签时为空数组，见下文 userGroupTags 数据结构说明
message string 接口调用成功或失败时的相应描述信息

# userGroupTags 数据结构

选项 类型 说明
userGroupTags[n].id string 标签 ID，在抖音开放平台配置标签并审核通过后获得
userGroupTags[n].status number 群聊标签的佩戴状态，为 1 时表示已佩戴

# 示例代码

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

// 当用户的客户端基础库版本低于 3.80.0 时，调用此接口将直接触发失败回调函数，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）！
sdkInstance.getUserGroupTagInfo({
  success: function(response) {
    // 获取所有标签列表
    const userGroupTags = response.data.userGroupTags;

    // 玩家当前没有佩戴任何标签
    if (userGroupTags.length === 0) {
      return console.log("玩家当前未佩戴称号");
    }

    // 在游戏内展示玩家当前的称号，注意：这是一段伪代码，具体由开发者自行实现
    showUserTitle(userGroupTags[0].id);
  },
  fail: function(error) {
    console.log(error);
  },
  complete: function(result) {
    // do something here...
  }
});

# 设置用户群聊标签

# 接口说明

用于为当前登录玩家佩戴或删除群聊标签（2.4.0 版本新增）。佩戴后，玩家在群聊中的昵称后会展示对应的称号铭牌，其他群成员点击铭牌可查看该称号的获得规则并启动游戏。

sdkInstance.setGroupTag(options);

最低基础库版本要求

当用户的客户端基础库版本低于 3.80.0 时，调用 sdkInstance.setGroupTag(options) 接口将直接触发失败回调函数，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）！

# 调用时机

在玩家达成称号条件的那一刻调用（如通关指定关卡、赛季排名达标、参与限时活动等），或在玩家登录后按其当前最高成就统一结算下发。当称号需要被摘除时（如赛季结束、称号过期、条件不再满足），传入 status 为 3 调用本接口。

# 参数说明

参数说明如下表所示：

选项 类型 必填 默认值 说明
tagId string 是 -- 标签 ID，在抖音开放平台配置标签并审核通过后获得
status number 否 1

群聊标签的佩戴状态：

  • 1 - 佩戴
  • 3 - 删除
success function 否 -- 接口调用成功的回调函数
fail function 否 -- 接口调用失败的回调函数
complete function 否 -- 接口调用完成的回调函数，成功或失败均会调用

# 返回值说明

注意

返回值格式：JSON 格式。

选项 类型 说明
code string / number 响应状态码，为 0 时表示接口调用成功，其他非 0 状态码均表示接口调用失败
data object / null 接口调用成功时返回设置结果，失败时返回 null
    data.isSandboxRequest boolean 是否为沙盒环境调用，当标签状态为「待上架」时返回 true，表示本次调用不会对真实用户设置生效
message string 接口调用成功或失败时的相应描述信息

# 示例代码

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

// 玩家达成称号条件时，为其佩戴对应的称号标签
// 当用户的客户端基础库版本低于 3.80.0 时，调用此接口将直接触发失败回调函数，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）！
sdkInstance.setGroupTag({
  tagId: "7382919283746152", // 标签ID，在抖音开放平台配置标签并审核通过后获得
  status: 1, // 1：佩戴，3：删除
  success: function(response) {
    // 标签处于「待上架」状态时为 true，表示本次调用不会对真实用户生效，仅用于联调
    if (response.data.isSandboxRequest) {
      return console.log("当前标签尚未上架，本次调用不会对真实用户生效");
    }

    // 打印结果
    console.log("称号佩戴成功");
  },
  fail: function(error) {
    console.log(error);
  },
  complete: function(result) {
    // do something here...
  }
});

// 赛季结束时，摘除玩家的赛季称号
// 当用户的客户端基础库版本低于 3.80.0 时，调用此接口将直接触发失败回调函数，并在正式版环境下于控制台输出错误提示（非正式版环境下，以弹窗形式展示）！
sdkInstance.setGroupTag({
  tagId: "7382919283746152",
  status: 3, // 1：佩戴，3：删除
  success: function(response) {
    console.log("称号已摘除");
  },
  fail: function(error) {
    console.log(error);
  },
  complete: function(result) {
    // do something here...
  }
});

# 群标签下发规则说明

注意

本期一个玩家只能展示一个标签，后续才会支持多个标签且能够顺延标签；
新下发的标签会替换掉上一个标签，平台不保存上一个标签是什么。因此称号升级时无需先删除旧标签，直接下发新标签即可；
玩家历史获得过哪些称号，平台不做记录，需要开发者自行在游戏侧留存。

下发和删除操作的结果如下表所示：

下发和删除操作 结果

下发后删除：

  • 给 A 玩家佩戴一个标签 123
  • 给 A 玩家删除一个标签 123
 无标签

连续下发标签：

  • 给 A 玩家佩戴一个标签 123
  • 给 A 玩家佩戴一个标签 456
 佩戴 456

删除最早的一个标签：

  • 给 A 玩家佩戴一个标签 123
  • 给 A 玩家佩戴一个标签 456
  • 给 A 玩家删除一个标签 123
 佩戴 456

删除最后一个标签：

  • 给 A 玩家佩戴一个标签 123
  • 给 A 玩家佩戴一个标签 456
  • 给 A 玩家删除一个标签 456
 无标签

# 风险提示（推荐接入）

注意

称号标签属于荣誉性资产，本文档提供的「设置用户群聊标签」接口在客户端执行，存在被玩家篡改客户端代码伪造下发的风险！

针对上述风险，建议的解决思路：

1、对于不敏感的称号（如活动参与纪念、新手引导完成等），可直接使用客户端接口下发；
2、对于需要防刷的称号（如排行榜名次、付费等级等），建议由游戏服务端调用抖音的服务端接口下发，相关文档：《设置用户群标签》 (opens new window)、《查询用户群标签》 (opens new window)。

Last Updated: 2026/8/13 18:07:52

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