You need to enable JavaScript to run this app.
文档中心
企业直播

企业直播

请输入
  • 文档首页
    • 企业直播直播消息回调观众状态变化回调
复制全文
下载 pdf
我的收藏
直播消息回调
观众状态变化回调
复制全文
下载 pdf
我的收藏
观众状态变化回调

作用

当发生以下事件导致观众状态变化时，企业直播会向您设置的回调地址发送回调消息。

  • 观众进入直播间
  • 观众离开直播间
  • 观众开始观看预告
  • 观众停止观看预告
  • 观众开始观看直播
  • 观众停止观看直播
  • 观众开始观看回放
  • 观众停止观看回放

例如，直播状态从直播中变为回放，则会分别触发观众停止观看直播事件和观众开始观看回放事件的 2 次回调。
如需触发观众开始观看预告事件或观众结束观看预告事件的回调，请确保预告状态期间有预告片正在播放。例如，直播状态从预告变为直播中，但预告状态期间并未播放预告片，则仅会触发观众开始观看直播事件的 1 次回调。

配置方式

完成回调配置。详见回调配置。

详情

完成回调配置后，当发生特定事件导致观众状态变化时，企业直播会将具体的事件、事件发生时间、观众的用户 ID 和观众的设备类型等信息以 POST 方式提交给您设置的回调地址。
请求示例如下所示：

POST /xxxxx HTTP/1.1
Header1: ...
Header2: ...
...
{
     "ActivityID": "17211234",
     "EventType": "ActivityUserEnterCallBack",
     "EnterTimestamp": "1721099280120",
     "UserID": "123987123",
     "ExternalUserID": "81239871232",
     "Timestamp": "1721099426120",
     "Sign": "b96c2ac3d6aed7557a8bec33****",
     "Status": "1",
     "UserDevice": "android",
     "UsageType": "saas",
     "SubAccountName" : "admin@bytedance.com"
}

超时重试

回调服务器在发送消息通知后，5 秒内没有收到您的服务器的响应，即认为通知失败。后续会以 5 秒为间隔继续重试 2 次。

参数

参数

类型

说明

ActivityID

String

直播间 ID。

EventType

String

回调通知的事件类型，固定取值为 ActivityUserEnterCallBack。

Status

String

导致观众状态变化的事件。取值如下：

  • 1：观众进入直播间
  • 2：观众离开直播间
  • 3：观众开始观看预告
  • 4：观众停止观看预告
  • 5：观众开始观看直播
  • 6：观众停止观看直播
  • 7：观众开始观看回放
  • 8：观众停止观看回放

Timestamp

String

事件的发生时间。Unix 时间戳，单位为毫秒。

EnterTimestamp

String

  • 当 Status 取值为 2、4、6 、8 时，该参数分别表示 Status 取值为 1、3、5、7 时事件的发生时间。Unix 时间戳，单位为毫秒。例如，当 Status 取值为 4 时，该参数表示观众开始观看预告的时间。
  • 当 Status 取值为 1、3、5、7 时，该参数取值固定为 0。

UserID

String

观众的用户 ID。

说明

观众未输入昵称或未登录直播间时，取值为 0。

ExternalUserID

String

关联用户 ID，即观众在第三方平台的唯一标识。
您可以根据该关联用户 ID 识别企业自身的用户身份，以便于按需实现用户洞察和进行数据分析。
观众通过不同方式登录直播间，关联用户 ID 的取值如下所示。

  • 微信：观众在企业直播微信服务号的 OpenID。
  • 企业微信：绑定企业直播的企业内部成员 OpenID。
  • 自定义：自定义登录时通过 UserId 传入的值。详见自定义登录。
  • OAuth 2.0：您自有账号系统中用户 ID 对应的字段。
  • 飞书：绑定企业直播的飞书企业成员 Open ID。
  • 手机号：观众通过手机号注册企业直播后生成的 passport_id。
  • 白名单：观众输入的白名单校验信息。

说明

如果您集成了观播 SDK，且 SDK 的鉴权模式为自定义模式，关联用户 ID 的取值为调用 GetSDKTokenAPI 接口时、或调用 GetActivityLoginSecret 后生成 JWT 时，传入的 UserIdStr（观众 ID）。

Sign

String

校验签名。
完成以下步骤，计算校验签名。

  1. 按照 AccountSecret、ActivityID、EnterTimestamp、 EventType、ExternalUserID、Status、Timestamp、UserID 的顺序，拼接对应的参数值。
  2. 将拼接后的内容进行 MD5 加密生成 32 位小写字符串。

说明

AccountSecret 的取值可通过控制台获取。详见步骤二：获取鉴权密钥。

UserDevice

String

观众的终端类型。例如 iOS、android、windows10、mac os 等。

UsageType

String

观众所在的观看页的接入方式。取值如下：

  • saas：SaaS 观看页
  • websdk：接入 Web 观播 SDK 的观看页
  • miniprogram：接入微信小程序观播 SDK 的观看页
  • nativesdk：接入 iOS/Android 观播 SDK 的观看页

SubAccountName

String

创建直播间的账号。参数值 admin@bytedance.com 表示直播间为主账号创建。

最近更新时间：2025.11.20 15:34:19
这个页面对您有帮助吗？
有用
有用
无用
无用