时间	更新内容
2024.7.29	创建文档
2024.8.9	补充整体流程和FAQ。补充说明：礼物进阶互动效果配置为不区分阵营时，本接入指南无需接入，配置为需要区分阵营时才需要接入

一、整体流程

礼物进阶互动效果配置为不区分阵营时，本接入指南无需接入，配置为需要区分阵营时才需要接入

二、接入时序

三、接口明细

同步对局状态

接口说明

开发者在对局开始时调用，同步对局开始事件；在对局结束时再次调用，同步对局结束事件。

使用限制

小玩法app_id纬度，qps限流配置为 100/s。

基本信息

名称	描述
HTTP URL	https://webcast.bytedance.com/api/gaming_con/round/sync_status
HTTP Method	POST

请求头

名称	字段类型	是否必填	描述
content-type	String	是	固定值"application/json"
X-Token	String	是	getAccessToken

请求参数

•

Body

名称		字段类型	是否必填	描述
anchor_open_id		String	是	主播的open_id
app_id		String	是	小玩法app_id
room_id		String	是	房间Id
round_id		Int64	是	对局Id，同一个直播间room_id下，round_id需要是递增的
start_time		Int64	是	本局开始时间，秒级时间戳
end_time		Int64	否	本局结束时间，秒级时间戳。同步的对局状态为对局结束时，该字段必传。
status		Int	是	当前房间的游戏对局状态（1=已开始、2=已结束）
group_result_list		[Array Item]	否	对局结束时，阵型的结果数据同步的对局状态为[已结束]时，该字段必传。
	group_id	String	是	阵营id，取值来源来自开发者平台「进阶礼物配置」的group_id，如：red
	result	Int	是	对局结果（1=胜利、2=失败、3=平局）

请求示例

curl --location --request POST 'https://webcast.bytedance.com/api/gaming_con/round/sync_status' \
--header 'content-type: application/json' \
--header 'X-Token: 0801121846735352506a356a6' \
--data '{
    "round_id": 23,
    "room_id": "78273162632",
    "app_id": "tt411d37a0dxxxxx",
    "anchor_open_id": "UhJKbtCg3N",
    "start_time": 1722239345,
    "end_time": 1722239345,
    "status": 2,
    "group_result_list": [
        {
            "group_id": "test-01",
            "result": 1
        }
    ]
}'

响应参数

•

Body

名称	字段类型	是否必填	描述
errmsg	String	是	错误描述
errcode	Int64	是	错误码，0代表成功

响应示例

正常响应示例

{"errmsg": "","errcode": 0}

异常响应示例

{"errcode": 40004,"errmsg": "access token is expired"}

错误码

http状态码	错误码	错误码描述	排查建议
200	40001	参数错误	请求体中的必传参数是否都上传、请求的小玩法app_id是否与请求时access_token相匹配
200	4014034	请求过于频繁	接口有频控限制，建议降低请求的并发量
200	40004	access_token过期	重新生成access_token，重新请求

上报阵营数据

接口说明

观众通过评论、点赞、送礼等方式加入玩法时，调用该接口上报当前观众的阵营数据。

使用限制

小玩法app_id纬度，限流配置为 1000/s。

基本信息

名称	描述
HTTP URL	https://webcast.bytedance.com/api/gaming_con/round/upload_user_group_info
HTTP Method	POST

请求头

名称	字段类型	是否必填	描述
content-type	String	是	固定值"application/json"
X-Token	String	是	getAccessToken

请求参数

•

Body

名称	字段类型	是否必填	描述
app_id	String	是	小玩法app_id
group_id	String	是	阵营id，取值来源来自开发者平台「进阶礼物配置」的group_id，如：red
open_id	String	是	用户open_id
room_id	String	是	房间Id
round_id	Int64	是	对局Id

请求示例

curl --location --request POST 'https://webcast.bytedance.com/api/gaming_con/round/upload_user_group_info' \
--header 'X-Token: 0801121846735352506a356a6' \
--header 'content-type: application/json' \
--data '{"open_id":"mGYZLfwsH9","group_id":"test-111","round_id":1213,"room_id":"76886868223","app_id":"tt411d37a0xxxx"}'

响应参数

•

Body

名称	字段类型	是否必填	描述
errmsg	String	是	错误描述
errcode	Int64	是	错误码，0代表成功

响应示例

正常响应示例

{"errcode": 0,"errmsg": ""}

异常响应示例

{"errcode": 40001,"errmsg": "request params are invalid"}

错误码

http状态码	错误码	错误码描述	排查建议
200	40001	参数错误	请求体中的必传参数是否都上传、请求的小玩法app_id是否与请求时access_token相匹配
200	4014034	请求过于频繁	接口有频控限制，建议降低请求的并发量
200	40004	access_token过期	重新生成access_token

查询观众阵营数据（开发者提供）

接口说明

观众进入直播间打开小摇杆互动面板时，平台服务器请求该接口获取用户在指定直播间最新的阵营数据。

接口要求

•

性能要求：qps 至少要满足 200/s。

•

时延要求：P99 <= 100ms。

基本信息

名称	描述
HTTP URL	开发者在开发者控制台的「开发配置」中配置
HTTP Method	POST
签名要求	详见3.3.5签名方式部分介绍。开发者请务必校验数据签名，验证数据来源的合法性，否则存在被伪造数据攻击的危险，需自行担责

请求头

名称	字段类型	是否必填	描述
x-nonce-str	string	是	签名用的随机字符串
x-timestamp	int64	是	发送消息的毫秒级时间戳
x-roomid	string	是	房间Id
x-msg-type	string	是	消息类型 user_group：用户阵营数据
x-signature	string	是	请求签名，业务方接收后需要计算和校验签名，防伪造和篡改
content-type	string	是	固定值：application/json

签名方式

•

开发者请务必校验数据签名，验证数据来源的合法性，否则存在被伪造数据攻击的危险，需自行担责

◦

对表格中header参数(x-signature，content-type除外)，按key字典序从小到大排序, 排序后，将key-value按顺序连接起来。如：key1=value1&key2=value2。

◦

再直接拼接(无需连接符)上body字符串和secret（开发配置中配置的字段)。注意，字符串需要使用utf-8编码。

◦

把拼接好的字符串进行md5计算(16bytes)，并对md5计算结果进行base64编码，编码结果便是x-signature。

go示例：

/**
比如：
   header := map[string]string{ 
                "x-nonce-str": "123456", 
                "x-timestamp": "456789", 
                "x-roomid":    "268", 
                "x-msg-type":  "user_group", 
        }
   
   bodyStr := "abc123你好"
   secret := "123abc"

rawData为：x-msg-type=user_group&x-nonce-str=123456&x-roomid=268&x-timestamp=456789abc123你好123abc
signature为：GAkalGmhzqlUGQO/TgvMug==
*/
func signature(header map[string]string, bodyStr, secret string) string {
   keyList := make([]string, 0, 4)
   for key, _ := range header {
      keyList = append(keyList, key)
   }
   sort.Slice(keyList, func(i, j int) bool {
      return keyList[i] < keyList[j]
   })
   kvList := make([]string, 0, 4)
   for _, key := range keyList {
      kvList = append(kvList, key+"="+header[key])
   }
   urlParams := strings.Join(kvList, "&")
   rawData := urlParams + bodyStr + secret
   md5Result := md5.Sum([]byte(rawData))
   return base64.StdEncoding.EncodeToString(md5Result[:])
}

java示例：

import java.security.MessageDigest;
import java.util.*;

/**
 * @jdk >= 1.8
 * @param header = {
                        "x-nonce-str": "123456", 
                        "x-timestamp": "456789", 
                        "x-roomid":    "268", 
                        "x-msg-type":  "user_group", 
 *                 }
    * @param bodyStr = "abc123你好"
 * @param secret = "123abc"
 * @return GAkalGmhzqlUGQO/TgvMug==
 */
public static String signature(Map<String, String> header, String bodyStr, String secret) throws Exception {
    List<String> keyList = new ArrayList<>(4);
    header.forEach((key, val) -> keyList.add(key));
    Collections.sort(keyList, String::compareTo);

    List<String> kvList = new ArrayList<>(4);
    for (String key : keyList) {
        kvList.add(key + "=" + header.get(key));
    }
    String urlParams = String.join("&", kvList);
    String rawData = urlParams + bodyStr + secret;
    MessageDigest md = MessageDigest.getInstance("MD5");
    md.update(rawData.getBytes(StandardCharsets.UTF_8));
    return Base64.getEncoder().encodeToString(md.digest());
}

请求参数

•

Body

名称	字段类型	是否必填	描述
app_id	String	是	小玩法app_id
open_id	String	是	用户open_id
room_id	String	是	房间Id

响应参数

请求响应都以http 200的形式返回，具体错误由响应字段中的错误码字段来标记。

名称		字段类型	是否必填	描述
errcode		Int64	是	错误码，0代表成功
errmsg		String	是	错误描述，成功为 success
data		struct	否	errcode为0时，该字段必传
	round_id	Int64	是	当前直播间，当前的对局id。如果一个对局已经结束，但是还没有开始新的对局，则返回已经结束的对局信息。如果从来没有开始过对局，则传 0。
	round_status	Int	是	当前直播间的对局状态。（1=已开始、2=已结束）
	user_group_status	Int	是	用户是否加入阵营 - 如用户未加入阵营，则传0； - 如用户已加入阵营，则传1
	group_id	String	是	阵营id，取值来源来自开发者平台「礼物进阶配置」的group_id。 - 如用户未加入阵营，则传空字符串； - 如用户加入阵营，则传对应的group_id

响应示例

•

正常响应

{
        "errcode": 0,
        "errmsg": "success",
        "data": {
                "round_id": 12,
                "round_status": 1,
                "group_id": "test01",
                "user_group_status ": 1
        }
}

•

异常响应

{
  "errmsg": "参数不合法",
  "errcode": 1
}

错误码

HTTP 状态码	错误码	描述	排查建议
200	40001	参数错误	房间id、小玩法app_id等入参解析失败，检查参数解析逻辑
200	4014034	请求过于频繁	提高接口的处理能力（必要时可联系平台进行熔断）
200	40004	签名错误	检查签名生成代码

四、FAQ

Q：我的玩法礼物配置为不区分阵型，我是否需要接入本文档的相关接口？

回答：礼物进阶互动效果配置为不区分阵营时，本接入指南无需接入，配置为需要区分阵营时才需要接入。