接口调用凭证

直播间能力

数据开放说明

我的收藏

变更记录

时间	更新内容
2024.07.24	创建文档
2024.09.22	•礼物数据-payload 新增被送礼嘉宾open_id

可靠性协议

消息类型	时效性保证	时序性保证	重复性保证	可靠性保证	备注
评论消息	秒级别	不保证绝对时序，但是时间段内相对时序基本是有保证的	可能会重复，需要开发者根据消息id做重复判断	不保证可靠性，会有数据丢失的情况
礼物消息	秒级别	不保证绝对时序，但是时间段内相对时序基本是有保证的	可能会重复，需要开发者根据消息id做重复判断	尽力而为地保证可靠性，提供有限的丢失消息回查接口供开发者回查
点赞消息	秒级别	不保证绝对时序，但是时间段内相对时序基本是有保证的	可能会重复，需要开发者根据消息id做重复判断	不保证可靠性，会有数据丢失的情况
粉丝团消息	秒级别	不保证绝对时序，但是时间段内相对时序基本是有保证的	可能会重复，需要开发者根据消息id做重复判断	尽力而为地保证可靠性，提供有限的丢失消息回查接口供开发者回查

接入流程

•

抖音平台将「一定周期内直播间数据推送给开发服务器的行为抽象为“数据推送任务”」，数据推送任务由（直播间id, 小玩法id, 直播间消息类型）三者唯一确定，在小玩法被挂载的过程中，允许开发者自主多次启动和停止推送任务。

•

抖音平台提供启动任务/停止任务/查询任务状态/回查丢失数据的接口给开发者接入，接口支持幂等调用，开发者只需要关注以下几条逻辑链路：B: 启动直播间数据推送任务：注意，只有直播间中正在被挂载的小玩法才允许开发者启动数据推送任务。主播取消挂载小玩法或者关播后，抖音平台会自动停止数据推送C: 主动回查推送失败的数据：注意，当前只有礼物数据、粉丝团数据支持回查，而且有缓存数量和时间限制。一般平台支持缓存前10w条数据，缓存一天，支持一天内过来分页查询D: 停止直播间数据推送任务E：查询直播间数据推送任务状态。

API 接口

启动任务

停止任务

查询任务状态

分页查询推送失败数据(仅支持礼物、粉丝团数据)

获取粉丝团信息

数据推送

推送协议

当前属于快速验证收益阶段，暂不支持长连接接入。后续平台会看业务发展情况，推动技术升级

在高热直播间场景下，为了抖音平台数据推送服务的稳定运行，平台做如下数据推送限制：

默认数据推送QPS限制为100，直播间数据量越大，数据丢失可能性越大

数据推送给开发者服务端，如果推送请求响应超过 2秒 (礼物数据是3s）或者返回【非2XX】状态码，平台认为推送失败，连续10次推送失败会触发推送的熔断，平台会直接丢弃数据若干秒再尝试推送

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

•

推送方式：http回调

•

推送参数：

Method	POST
参数形式	参数名	类型	说明
Header	x-nonce-str	string	签名用的随机字符串
	x-timestamp	int64	发送消息的毫秒级时间戳
	x-signature	string	请求签名，业务方接收后需要计算和校验签名，防伪造和篡改
	x-roomid	string	房间id
	x-msg-type	string	消息类型 live_comment: 直播间评论 live_gift: 直播间送礼 live_like: 直播间点赞
	content-type	string	固定值：application/json
body	~	string	具体类型消息payload对象的json序列化字符串

•

签名方式：开发者请务必校验数据签名，验证数据来源的合法性，否则存在被伪造数据攻击的危险，需自行担责对表格中header参数(x-signature，content-type除外)，按key字典序从小到大排序, 排序后，将key-value按顺序连接起来。如：key1=value1&key2=value2。再直接拼接(无需连接符)上body字符串和secret（推送配置中的字段), 也就是前置工作中需要开发者提供给开平的签名秘钥。注意，字符串需要使用utf-8编码把拼接好的字符串进行md5计算(16bytes)，并对md5计算结果进行base64编码，编码结果便是signature

go 示例：

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

rawData为：x-msg-type=live_gift&x-nonce-str=123456&x-roomid=268&x-timestamp=456789abc123你好123abc
signature为：PDcKhdlsrKEJif6uMKD2dw==
*/
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":  "live_gift",
 *                 }
 * @param bodyStr = "abc123你好"
 * @param secret = "123abc"
 * @return PDcKhdlsrKEJif6uMKD2dw==
 */
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());
    return Base64.getEncoder().encodeToString(md.digest());
}

js 示例：抖音小玩法校验数据签名-js

•

开发者对回调的响应：响应2XX就平台会认为是成功的ack

如果开放平台推送请求收到的应答不符合规范或超时未收到，开放平台会认为推送失败且不会继续推送。http 应答码为 2XX 才会当作正常响应，推送成功率会影响后续推送的频率。

评论数据-payload

[ 
  {
    msg_id: "123456781", // string类型id
    sec_openid: "xxxx", // 评论用户的加密openid, 当前其实没有加密
    content: "xxxx", // 评论内容
    avatar_url: "xxx", // 评论用户头像
    nickname: "xxxx", // 评论用户昵称(不加密)
    timestamp: 1649068964, // 评论毫秒级时间戳
  },
];

礼物数据-payload

开发者请务必校验礼物数据中test字段，如果 test字段为 true ，代表推送的是测试数据，应在数据统计场景进行过滤（如榜单场景），否则存在数据统计异常的风险，需自行担责。

测试数据生产来源说明：1）开放平台控制台的自查工具模拟发送的测试数据；2）版本发布时，因平台审核玩法交互表现等，模拟发送的测试数据；

[ 
  {
    msg_id: "123456782", // string类型id
    sec_openid: "xxxx", // 用户的加密openid，当前其实没有加密
    sec_gift_id: "xxxx", // 加密的礼物id
    gift_num: 123, // 送出的礼物数量
    gift_value: 10000, // 礼物总价值，单位分
    avatar_url: "xxx", // 用户头像
    nickname: "xxxx", // 用户昵称(不加密)
    timestamp: 1649068964, // 礼物毫秒级时间戳
    test: true, // 如果是抖音平台的测试数据，则会下发该字段且值为 true。测试工具下发的送礼数据属于调试模式，不会有该字段
    audience_sec_open_id:"xxx" // 被送礼的嘉宾openid，当前没有加密
  },
];

点赞数据-payload

[
  { 
    msg_id: "123456783", // string类型id
    sec_openid: "xxxx", // 点赞用户的加密openid，当前其实没有加密
    like_num: 123,     // 点赞数量，上游2s合并一次数据
    avatar_url: "xxx", // 点赞用户头像
    nickname: "xxxx", // 点赞用户昵称(不加密)
    timestamp: 1649068964, // 点赞毫秒级时间戳
  },
];

粉丝团数据-payload

[ 
  {
    msg_id: "123456789",
    sec_openid: "xxxx", // 粉丝团用户的openid
    avatar_url: "xxx", // 用户头像
    nickname: "xxxx", // 用户昵称(不加密)
    timestamp: 1649068964, // 毫秒级时间戳
    fansclub_reason_type: 2, // 粉丝团消息类型：1-升级，2-加团
    fansclub_level: 1, // 用户粉丝团等级，加团消息下默认传1
  },
];

FAQ

自查手册

直播间接入数据开放能力-FAQ & 自查手册

其他问题

其他开发调试问题