抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • 服务端 API 介绍
  • 接口调用凭证
  • 登录
  • 直播间能力
  • 数据开放说明

    收藏
    我的收藏

    变更记录

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

    可靠性协议

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

    接入流程

      抖音平台将「一定周期内直播间数据推送给开发服务器的行为抽象为“数据推送任务”」数据推送任务由(直播间id, 小玩法id, 直播间消息类型)三者唯一确定,在小玩法被挂载的过程中,允许开发者自主多次启动和停止推送任务。
      抖音平台提供启动任务/停止任务/查询任务状态/回查丢失数据的接口给开发者接入,接口支持幂等调用,开发者只需要关注以下几条逻辑链路:B: 启动直播间数据推送任务:注意,只有直播间中正在被挂载的小玩法才允许开发者启动数据推送任务。主播取消挂载小玩法或者关播后,抖音平台会自动停止数据推送C: 主动回查推送失败的数据:注意,当前只有礼物数据、粉丝团数据支持回查,而且有缓存数量和时间限制。一般平台支持缓存前10w条数据,缓存一天,支持一天内过来分页查询D: 停止直播间数据推送任务E:查询直播间数据推送任务状态。

    API 接口

    数据推送

    推送协议

    当前属于快速验证收益阶段,暂不支持长连接接入。后续平台会看业务发展情况,推动技术升级
    在高热直播间场景下,为了抖音平台数据推送服务的稳定运行,平台做如下数据推送限制
      1.默认数据推送QPS限制为100,直播间数据量越大,数据丢失可能性越大
      2.数据推送给开发者服务端,如果推送请求响应超过 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()); }
      开发者对回调的响应:响应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

    自查手册

    其他问题