实时互动-教育版
有奖捉虫：行业应用 & 管理与支持文档专题 HOT
文档中心 > 实时互动-教育版 > 监听服务端事件回调

监听服务端事件回调

最近更新时间：2024-04-15 18:43:21

我的收藏

本页目录：

概述

说明：
低代码互动课堂提供服务回调，支持将业务的状态通知回调至业务方，帮助业务方实现课前、课中以及课后的统计需求。



1. 回调地址配置。
通过低代码互动课堂控制台 应用管理 中操作字段下的应用配置回调配置，完成回调地址（Callback）的配置。

2. 用户可以通过 获取房间事件接口 主动拉取房间事件。该接口仅支持房间结束1小时内拉取，过期房间事件会被释放。
3. 回调事件列表。
事件类型
事件名称
事件描述
房间事件
RoomStart
房间开始事件
RoomEnd
房间结束事件
RoomExpire
房间过期事件
录制事件
RecordFinish
录制完成事件
成员事件
MemberJoin
成员进入事件
MemberQuit
成员退出事件
文档事件
DocumentTranscodeFinish
文档转码完成事件
DocumentCreate
文档创建事件
DocumentDelete
文档删除事件
伪直播事件
FakeLiveStart
伪直播开始
FakeLiveStop
伪直播结束
自定义事件
TaskUpdate
自定义事件

回调签名方法

注意：
回调鉴权服务并非必须，但为了业务安全，建议业务层完成回调的鉴权校验。
对接回调鉴权部分，我们会提供 CallbackKey，用于对回调消息的鉴权。签名算法如下：
Sign = md5(CallbackKey+ExpireTime)

示例：
CallbackKey = NjFGoDEy 
ExpireTime = 1614151508 
Sign = md5(NjFGoDEy1614151508) = b9454ab5a85f9b7ad36071f5688ed34d
其中 ExpireTime 是签名过期时间，如果一条消息通知中的 ExpireTime 值所指定的时间已经过期，则可以判定这条通知无效，进而可以防止网络重放攻击。格式为十进制 UNIX 时间戳，即从1970年01月01日（UTC/GMT 的午夜）开始所经过的秒数。例如：
Go
Java
Python3
package main

import (
    "crypto/md5"
    "fmt"
)

func main() {
    callbackKey := "NjFGoDEy"
    expire := 1614151508
    sign := fmt.Sprintf("%x", md5.Sum([]byte(callbackKey+fmt.Sprintf("%d", expire))))
    fmt.Printf(fmt.Sprintf("sign:%s", sign))   // sign:b9454ab5a85f9b7ad36071f5688ed34d
}
String md5Str = DigestUtils.md5DigestAsHex("NjFGoDEy1614151508".getBytes());
# Python 3 code to demonstrate the
# working of MD5 (string - hexadecimal)
 
import hashlib
 
# initializing string
str2hash = "NjFGoDEy1614151508"
result = hashlib.md5(str2hash.encode())
 
# printing the equivalent hexadecimal value.
print("sign:", end ="")
print(result.hexdigest())    #sign:b9454ab5a85f9b7ad36071f5688ed34d
在您收到回调请求时，会携带 ExpireTime 和 Sign 参数，您可以依据这两个值和回调密钥进行计算校验请求来源的正确性。

事件回调协议

我们会向注册的回调地址发起事件回调的形式是 HTTP POST 请求，请求体为 JSON 格式，内容为：
参数名称
类型
描述
Timestamp
Integer
事件生成的 Unix 时间戳，单位秒。
ExpireTime
Integer
签名的过期时间的 Unix 时间戳，单位秒，如果当前时间晚于过期时间，后台可以判断该请求不合法。
Sign
String
回调签名，可以根据事件回调鉴权中描述的方法校验签名是否匹配以校验该请求来源是否合法。
SdkAppId
Integer
本次事件所属的应用。
EventType
String
详见各回调类型描述。
EventData
JSON
详见各回调类型描述。
回调事件示例
回调应答示例
POST xxxxxxxxxxxxxxx(user-callback-url)
Content-Type: application/json; charset=utf-8
Accept: application/json

{
    "Timestamp":1679279232,
    "ExpireTime":1679279832,
    "Sign":"fbfd23733e6262f49e402247024fbc29",   // 参考 回调签名方法 
    "SdkAppId":3520371,
    "EventType":"RoomStart",
    "EventData":{
        "RoomId":366317280
    }
}
应答：HTTP STATUS CODE = 200，客户应答内容应该携带 JSON： {"error_code":0}


HTTP STATUS CODE 200 OK

HTTP BODY:
{
    "error_code":0
}

事件列表

房间开始事件

事件类型
RoomStart
事件说明
当房间开始时发出通知。
数据字段
字段名
类型
描述
RoomId
Integer
房间 ID
示例
{
    "Timestamp":1679279232,
    "ExpireTime":1679279832,
    "Sign":"fbfd23733e6262f49e402247024fbc29",
    "SdkAppId":3520371,
    "EventType":"RoomStart",
    "EventData":{
        "RoomId":366317280
    }
}

房间结束事件

事件类型
RoomEnd
事件说明
当房间结束时发出通知。
数据字段
字段名
类型
描述
RoomId
Integer
房间 ID
示例
{
    "Timestamp":1679279195,
    "ExpireTime":1679279795,
    "Sign":"696560af8fec9374b4cd58c6318c6448",
    "SdkAppId":3520371,
    "EventType":"RoomEnd",
    "EventData":{
        "RoomId":311601250
    }
}

房间过期事件

事件类型
RoomExpire
事件说明
当房间过期时发出通知。
数据字段
字段名
类型
描述
RoomId
Integer
房间 ID
示例
{
    "Timestamp":1679282220,
    "ExpireTime":1679282820,
    "Sign":"07e504e36a3738cf17a47f47b37c0d3c",
    "SdkAppId":3520371,
    "EventType":"RoomExpire",
    "EventData":{
        "RoomId":310096990
    }
}

录制完成事件

事件类型
RecordFinish
事件说明
当录制完成生成回放地址时发出通知。
数据字段
字段名
类型
描述
RoomId
Integer
房间 ID
Duration
Integer
录制时长，单位秒
RecordUrl
String
录制地址（协议为 https）
RecordSize
Integer
录制文件大小，单位 bit
示例
{
    "Timestamp":1679279203,
    "ExpireTime":1679279803,
    "Sign":"7ada1f46f27ce6f1cdeb22339d71e094",
    "SdkAppId":3520371,
    "EventType":"RecordFinish",
    "EventData":{
        "Duration":63,
        "RecordSize":698472,
        "RecordUrl":"https://xxxxxxx.vod2.myqcloud.com/xxxx/xxxxxxx/f0.mp4",
        "RoomId":311601250
    }
}

成员进入事件

事件类型
MemberJoin
事件说明
当成员进入房间时发出通知。
数据字段
字段名
类型
描述
RoomId
Integer
房间 ID
UserId
String
用户 ID
示例
{
    "Timestamp":1679279225,
    "ExpireTime":1679279825,
    "Sign":"6fcaf48026fe95d76d1615c44ea98ede",
    "SdkAppId":3520371,
    "EventType":"MemberJoin",
    "EventData":{
        "RoomId":366317280,
        "UserId":"2Lzh8d3Rw7zOlpEnNgHPe6HDiDn"
    }
}

成员退出事件

事件类型
MemberQuit
事件说明
当成员退出房间时发出通知。
数据字段
字段名
类型
描述
RoomId
Integer
房间 ID
UserId
String
用户 ID
Reason
Integer
退出原因，详细见下表
Reason枚举值
值
描述
0
主动退出
1
被踢
2
永久被踢
4
失去心跳下线
示例
{
    "Timestamp":1679279260,
    "ExpireTime":1679279860,
    "Sign":"03d41254d4ba7a05e13299a4841c3d99",
    "SdkAppId":3520371,
    "EventType":"MemberQuit",
    "EventData":{
        "RoomId":397322814,
        "UserId":"2NG5xjpnYLGo3bq1taJbItY1TPf",
        "Reason":0
    }
}

文档转码完成事件

事件类型
DocumentTranscodeFinish
事件说明
当文档转码完成（成功或失败）时发出通知。
数据字段
字段名
类型
描述
DocumentId
String
文档 ID
State
Integer
文档状态
Result
String
转码结果，如果成功则为转码后地址，如果失败则为错误码
Info
String
转码信息
Thumbnail
String
缩略图地址，PPT 缩略图一般有多页，第一页的地址为 thumbnail_url/1.jpg
示例
{
    "Timestamp":1679281156,
    "ExpireTime":1679281756,
    "Sign":"1597c5c8aaafb623ece9d1690dc0e780",
    "SdkAppId":3520371,
    "EventType":"DocumentTranscodeFinish",
    "EventData":{
        "DocumentId":"sixkzoak",
        "Info":"",
        "Result":"https://xxx.cos.ap-shanghai.myqcloud.com/doc/xxxxxx/picture/",
        "State":3,
        "Thumbnail":"https://xxxxx.cos.ap-shanghai.myqcloud.com/doc/xxxxx/thumbnail/"
    }
}

文档创建事件

事件类型
DocumentCreate
事件说明
当客户端文档创建成功时发出通知。
数据字段
字段名
类型
描述
DocId
String
文档 ID
DocName
String
文档名称
Owner
String
文档拥有者的 UserId
DocSize
Integer
文档大小 单位字节
DocUrl
String
文档链接
Permission
Integer
文档权限。 0：私有文档；1：公共文档。
示例
{
    "Timestamp":1679281150,
    "ExpireTime":1679281750,
    "Sign":"44f0a2e422ede67100a1f419df3ef51c",
    "SdkAppId":3520371,
    "EventType":"DocumentCreate",
    "EventData":{
        "DocId":"sixkzoak",
        "DocName":"test.pdf",
        "DocSize":4162606,
        "DocUrl":"https://xxxx.cos.ap-shanghai.myqcloud.com/uploads/xxxxx/xxxxxx/xxxxxx.pdf",
        "Owner":"2Lzh8d3Rw7zOlpEnNgHPe6HDiDn",
        "Permission":0
    }
}

文档删除事件

事件类型
DocumentDelete
事件说明
当客户端文档删除成功时发出通知。
数据字段
字段名
类型
描述
DocId
String
文档 ID
示例
{
    "Timestamp":1679281184,
    "ExpireTime":1679281784,
    "Sign":"964ff6d9463280d6a3bd4f7416213be9",
    "SdkAppId":3520371,
    "EventType":"DocumentDelete",
    "EventData":{
        "DocId":"sixkzoak"
    }
}

伪直播开始事件

事件类型
FakeLiveStart
事件说明
当伪直播开始时发出通知。
数据字段
字段名
类型
描述
RoomId
Integer
房间 ID
示例
{
    "Timestamp":1679281184,
    "ExpireTime":1679281784,
    "Sign":"964ff6d9463280d6a3bd4f7416213be9",
    "SdkAppId":3520371,
    "EventType":"FakeLiveStart",
    "EventData":{
        "RoomId":324896216
    }
}

伪直播结束事件

事件类型
FakeLiveStop
事件说明
当伪直播结束时发出通知。
数据字段
字段名
类型
描述
RoomId
Integer
房间 ID
Error.Code
String
错误码(正常结束无此字段)
Error.Message
String
错误描述(正常结束无此字段)
示例
{
    "Timestamp":1679281184,
    "ExpireTime":1679281784,
    "Sign":"964ff6d9463280d6a3bd4f7416213be9",
    "SdkAppId":3520371,
    "EventType":"FakeLiveStop",
    "EventData":{
        "RoomId":324896216,
        "Error":{
            "Code":"streamInterruption",
            "Message":"streamInterruption"
        }
    }
}

自定义事件

事件类型
TaskUpdate
事件说明
在自定义 UI 中调用 JSAPI updateTask，并传入参数 enableCallback = true 时发出通知。
数据字段
字段名
类型
描述
RoomId
String
房间 ID
TaskId
String
任务 ID（对应 updateTask 的 taskId 参数，可自定义）
CustomData
String
自定义参数（对应 updateTask 的 content 参数）
事件示例
JS 代码示例
{
    "Timestamp": 1679281184,
    "ExpireTime": 1679281784,
    "Sign": "964ff6d9463280d6a3bd4f7416213be9",
    "SdkAppId": 3520371,
    "EventType": "TaskUpdate",
    "EventData": {
        "RoomId": "397322814",
        "TaskId": "your-task-id",
        "CustomData": "{\\"key1\\":\\"value1\\",\\"key2\\":\\"value2\\"}"
    }
}
TCIC.SDK.instance.updateTask(
  'your-task-id', // taskId
  JSON.stringify({ key1: 'value1', key2: 'value2' }), // content
  -1, // duration
  false, // createOnly
  '', // bindingUser
  true, // enableCallback
);
中国站