分享组队接入指南

我的收藏

能力简介

“分享组队”是小游戏提供的一种高级社交分享能力。它允许开发者创建一种可动态更新状态的“动态消息”卡片，用于在抖音私信（IM）中邀请好友。与普通分享不同，这种卡片的内容（如队伍人数、房间状态）可以在用户分享后，由游戏服务端进行实时修改，非常适合需要多人协作、状态实时同步的游戏场景。

从客户端 30.9.0 开始，支持转发动态消息。动态消息对比普通消息，不同点是：消息发出去之后，开发者可以通过后台接口修改部分消息内容。

适用场景

•

多人组队游戏：如 MOBA、FPS 或“开黑”类游戏，房主创建房间后分享到好友群，群友可看到实时人数变化和游戏状态变化（组队中或者已开始）。

•

社交棋牌游戏：创建棋牌室后邀请牌友，卡片标题显示“好友已就位，就等你补位！”，吸引好友快速加入。

•

限时活动邀请：如“今晚 8 点 Boss 挑战，仅限 10 人”，通过动态消息实时更新剩余名额，营造紧迫感。

核心特性

•

动态更新：分享卡片发出后，其展示状态和内容（如“1/2组队中”）可通过服务端 API 实时更新，为接收方提供最及时的房间信息。

•

状态流转：消息拥有明确的生命周期（如：招募中 → 已开始 → 已结束），并支持在状态变更时更新卡片点击后的跳转逻辑（query 参数）。

•

高效触达：分享以 IM 私信卡片形式发送给指定好友或群聊，对在线用户有强提醒，点击即可直接拉起游戏，路径短、转化高。

•

数据透传：支持通过 query 参数在分享和启动链路中传递自定义信息，如房间号、邀请者 ID 等，便于实现自动进房、邀请归因与奖励发放等逻辑。

能力接入

能力申请入口

首先，登录开发者平台，找到「能力 - 能力中心 - 分享设置」进行能力的开通。

示意图	描述
	开始接入： •Step 1：点击「能力」板块 -「能力中心」 •Step 2：找到「分享设置」模块-点击「分享设置」即可开始接入 •Step 3：进入后选择「分享管理」tab •Step 4：了解相关内容后，点击「开始接入」，即开始接入流程

接入流程简述

接入流程详情

交互时序图：

Step 1：创建 `activity_id`

在每次发起组队分享前，开发者需要通过服务端调用 createActivityID接口为这次“活动”创建一个唯一标识 activity_id。后续转发动态消息以及更新动态消息都需要传入这个 activity_id。

注意：
•activity_id 是后续所有操作（客户端分享、服务端更新）的凭证，请务必妥善保存。
•活动到期后（默认 24 小时），分享卡片将自动变为“已结束”状态，且无法再被更新。

示例代码：

// 引入包 go get github.com/bytedance/douyin-openapi-sdk-go
import (
    "fmt"
    "testing"
    credential "github.com/bytedance/douyin-openapi-credential-go/client"
    openApiSdkClient "github.com/bytedance/douyin-openapi-sdk-go/client"
)
func TestShareCreateActivityId(t *testing.T) {
    // 初始化SDK client
    opt := new(credential.Config).
       SetClientKey("tt******").    // 改成自己的app_id
       SetClientSecret("cbs***") // 改成自己的secret
    sdkClient, err := openApiSdkClient.NewClient(opt)
    if err != nil {
       t.Log("sdk init err:", err)
       return
    }
    
    /* 构建请求参数，该代码示例中只给出部分参数，请用户根据需要自行构建参数值
            token:
               1.若用户自行维护token,将用户维护的token赋值给该参数即可
           2.SDK包中有获取token的函数，请根据接口path在《OpenAPI SDK 总览》文档中查找获取token函数的名字
             在使用过程中，请注意token互刷问题
        header:
           sdk中默认填充content-type请求头，若不需要填充除content-type之外的请求头，删除该参数即可
    */
    sdkRequest := &openApiSdkClient.ShareCreateActivityIdRequest{}
   sdkRequest.SetAccessToken("k23cd*****")
    // sdk调用
    sdkResponse, err := sdkClient.ShareCreateActivityId(sdkRequest)
    if err != nil {
       t.Log("sdk call err:", err)
       return
    }
    t.Log(sdkResponse)
}

Step 2：客户端分享动态消息

客户端在获取到 activity_id 后，通过调用tt.shareAppMessage接口发起分享，channel字段设置为invite，同时在extra中传入useTeamInvitationStyle: true，以及 templateInfo、activityID 参数。

参数	类型	默认值	必填	说明
`useTeamInvitationStyle`	`boolean`	false	是	固定为 `true`，用于声明此条分享为组队动态消息。
`activityID`	`string`	-	是	从第一步中获取的 `activity_id`。
`templateInfo`	`Array<TemplateInfo>`	-	是	消息模板的初始参数。`TemplateInfo` 对象包含 `name` 和 `value` 两个字段。
`versionType`	`string`	current	否	指定通过此消息启动的小游戏版本，默认为 `current` (线上版)，可设为 `latest` (开发版) 用于测试。

更多参数设置请参考：ShareParam

TemplateInfo类型说明

object 类型，属性如下：

属性	类型	默认值	必填	说明
name	string	-	是	参数名，有效值：当前房间人数`memberCount`、房间人数上限`roomLimit`
value	string	-	是	参数值

示例代码：

tt.shareAppMessage({
  templateId: "", // 替换成通过审核的分享ID
  query: "key1=val1&key2=val2", // 使用路径
  extra: {
      useTeamInvitationStyle: true,    // 标识该消息为组队消息
      activityID: "6800*****",     // 从服务端createActivityID获取
      templateInfo: [
          {
              name: "memberCount",
              value: "1" // 初始人数
          },
          {
              name: "roomLimit",
              value: "4" // 房间上限
          }
      ],
      versionType: "current"    // 指定通过动态消息进入的小游戏版本：线上版current、测试版latest
  },
  success() {
    console.log("分享成功");
    // 可在此处上报分享成功事件
  },
  fail(e) {
    console.log("分享失败");
  },
});

Step 3：服务端更新动态消息

当游戏内状态发生变化时，由开发者服务端调用 updateDynamicMessage 接口来更新已发出的分享卡片，根据 activity_id 更新指定活动的状态和模板参数。

消息状态说明 (target_state)

消息有两个状态，分别有其对应的文字内容。其中状态 0 可以转移到状态 0 和 1，状态 1 无法再转移。

字段	状态	文字内容	允许转移的状态
`target_state`	0	"{memberCount}/{roomLimit} 组队中"	0, 1
`target_state`	1	"已开始"	无

状态参数 (template_info)：与客户端分享参数templateInfo保持一致，状态 0 时有效。

示例代码：

package main

// 引入包 go get github.com/bytedance/douyin-openapi-sdk-go
import (
    credential "github.com/bytedance/douyin-openapi-credential-go/client"
    openApiSdkClient "github.com/bytedance/douyin-openapi-sdk-go/client"
    "testing"
)

func StringPtr(s string) *string {
    return &s
}

func TestShareUpdateDynamicMessage(t *testing.T) {
    // 初始化SDK client
    opt := new(credential.Config).
       SetClientKey("tt******"). // 改成自己的app_id
       SetClientSecret("cbs***") // 改成自己的secret
    sdkClient, err := openApiSdkClient.NewClient(opt)
    if err != nil {
       t.Log("sdk init err:", err)
       return
    }

    /* 构建请求参数，该代码示例中只给出部分参数，请用户根据需要自行构建参数值
           token:
              1.若用户自行维护token,将用户维护的token赋值给该参数即可
          2.SDK包中有获取token的函数，请根据接口path在《OpenAPI SDK 总览》文档中查找获取token函数的名字
            在使用过程中，请注意token互刷问题
       header:
          sdk中默认填充content-type请求头，若不需要填充除content-type之外的请求头，删除该参数即可
    */
    sdkRequest := &openApiSdkClient.ShareUpdateDynamicMessageRequest{}
    sdkRequest.SetAccessToken("k23cd*****")
    sdkRequest.SetActivityId("6800*****")
    sdkRequest.SetQuery("key1=val1&key2=val2")
    sdkRequest.SetTargetState(1)
    // 2/5 组队中
            sdkRequest.SetTemplateInfo([]*openApiSdkClient.ShareUpdateDynamicMessageRequestTemplateInfoItem{
       {
          Name:  StringPtr("memberCount"),
          Value: StringPtr("2"),
       },
       {
          Name:  StringPtr("roomLimit"),
          Value: StringPtr("5"),
       },
    })
    // 已开始
    // sdkRequest.SetTargetState(1)
    sdkRequest.SetVersionType("current")
    // sdk调用
    sdkResponse, err := sdkClient.ShareUpdateDynamicMessage(sdkRequest)
    if err != nil {
       t.Log("sdk call err:", err)
       return
    }
    t.Log(sdkResponse)
}

Step 4：好友点击卡片进入游戏

被邀请的好友点击分享卡片后，会拉起小游戏。此时，游戏客户端需要通过 tt.getLaunchOptionsSync 或 tt.onShow 来获取启动参数，判断是否由组队分享卡片进入，并获取透传的 query 信息。

示例代码：

// 在游戏启动时或 onShow 回调中
const launchOptions = tt.getLaunchOptionsSync();
console.log("游戏启动参数:", launchOptions);

if (launchOptions.query && launchOptions.query.room_id) {
  const roomId = launchOptions.query.room_id;
  console.log(`通过分享卡片进入，房间号为: ${roomId}`);
  
  // 执行加入房间的逻辑...
  joinRoom(roomId);
}

FAQ

Q：客户端最低版本要求是多少？A：支持动态消息的抖音客户端最低版本为 30.9.0。对于低于此版本的客户端，收到的动态消息会降级显示为一条普通的分享卡片，无法动态更新。建议在调用前使用 tt.canIUse 进行判断。

Q：分享卡片的消息一定能触达用户吗？A：消息会以 IM 私信形式发送。如果接收方好友在线，通常会收到强提醒 Push；如果离线，则会以普通私信形式存在于聊天列表中。触达率受用户网络状况、通知设置等多种因素影响，非 100% 保证。

Q：如果 updateDynamicMessage 接口调用失败怎么办？A：首先，检查网络连接和 access_token 是否有效。其次，根据返回的错误码排查问题，常见错误包括 activity_id 不存在或已过期、参数格式错误等。建议设计重试机制，并在多次失败后在游戏内给予用户明确提示（如“同步队伍状态失败，请稍后再试”）。

Q：分享组队需要申请特殊的模板或权限吗？A：是的。与普通分享一样，组队分享也需要使用在开发者后台审核通过的分享模板 templateId。此外，服务端 API 的调用需要获取 minigame.share 等相应的 Scope 权限。

Q：createActivityID 的调用频率有限制吗？如何保证幂等？A：平台对 OpenAPI 有通用的频率限制。建议不要在短时间内为同一个业务场景（如同一房间）重复创建 activity_id。createActivityID 接口本身不保证幂等，如果需要，开发者可以在自己的服务端通过业务逻辑（如检查同一房间是否已有有效的 activity_id）来实现。对于 updateDynamicMessage，虽然接口本身没有强制幂等，但开发者可以通过传入唯一的业务 ID（如自定义的 msg_id）并在服务端做校验来避免重复更新。

Q：用户分享出去的卡片，其他人能看到状态更新吗？A：可以。只要是通过同一个 activity_id 分享出去的卡片（无论分享给多少人或群），当服务端调用 updateDynamicMessage 时，所有这些卡片的状态都会同步更新。

Q：如果分享到群里，卡片状态如何展示？A：分享到群聊中的卡片同样支持动态更新。群内所有成员都能看到卡片状态的实时变化，非常适合在公会群、开黑群中组织活动。

Q：如何感知用户进入房间？A：当有新玩家加入房间时，由客户端通知服务端，服务端可调用抖音的updateDynamicMessage接口，并传入对应的activity_id和新的状态（如更新memberCount表示当前人数变化），以此感知用户进入房间。同时，被邀请好友点击卡片进入游戏后，游戏客户端通过tt.getLaunchOptionsSync 或tt.onShow获取启动参数，判断是否由组队分享卡片进入并获取透传的query信息，执行加入房间逻辑，也可确认用户进入房间。