概述
说明:
低代码互动课堂提供服务回调,支持将业务的状态通知回调至业务方,帮助业务方实现课前、课中以及课后的统计需求。
1. 回调地址配置。
2. 用户可以通过 获取房间事件接口 主动拉取房间事件。该接口仅支持房间结束1小时内拉取,过期房间事件会被释放。
3. 回调事件列表。
事件类型 | 事件名称 | 事件描述 |
房间事件 | 房间开始事件 | |
| 房间结束事件 | |
| 房间过期事件 | |
录制事件 | 录制完成事件 | |
成员事件 | 成员进入事件 | |
| 成员退出事件 | |
文档事件 | 文档转码完成事件 | |
| 文档创建事件 | |
| 文档删除事件 | |
伪直播事件 | 伪直播开始 | |
| 伪直播结束 | |
自定义事件 | 自定义事件 |
回调签名方法
注意:
回调鉴权服务并非必须,但为了业务安全,建议业务层完成回调的鉴权校验。
对接回调鉴权部分,我们会提供 CallbackKey,用于对回调消息的鉴权。签名算法如下:
Sign = md5(CallbackKey+ExpireTime)示例:CallbackKey = NjFGoDEyExpireTime = 1614151508Sign = md5(NjFGoDEy1614151508) = b9454ab5a85f9b7ad36071f5688ed34d
其中 ExpireTime 是签名过期时间,如果一条消息通知中的 ExpireTime 值所指定的时间已经过期,则可以判定这条通知无效,进而可以防止网络重放攻击。格式为十进制 UNIX 时间戳,即从1970年01月01日(UTC/GMT 的午夜)开始所经过的秒数。例如:
package mainimport ("crypto/md5""fmt")func main() {callbackKey := "NjFGoDEy"expire := 1614151508sign := 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 stringstr2hash = "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-8Accept: 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 OKHTTP 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
事件说明
数据字段
字段名 | 类型 | 描述 |
RoomId | String | 房间 ID |
TaskId | String | 任务 ID(对应 updateTask 的 taskId 参数,可自定义) |
CustomData | String | 自定义参数(对应 updateTask 的 content 参数) |
{"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', // taskIdJSON.stringify({ key1: 'value1', key2: 'value2' }), // content-1, // durationfalse, // createOnly'', // bindingUsertrue, // enableCallback);
转存开始事件
事件类型
MixedFlowTransferStart
事件说明
当自定义转存开始时发出通知。
数据字段
字段名 | 类型 | 描述 |
RoomId | Integer | 房间 ID |
TransferStatus.Code | String | 错误码(TransferSucceed、TransferFailed、UnauthorizedOperation) |
TransferStatus.Message | String | 错误描述(正常开始无此字段) |
{"Timestamp":1679281184,"ExpireTime":1679281784,"Sign":"964ff6d9463280d6a3bd4f7416213be9","SdkAppId":3520371,"EventType":"MixedFlowTransferStart","EventData":{"RoomId":324896216,"TransferStatus":{"Code":"TransferSucceed","Message":""}}}
转存结束事件
事件类型
MixedFlowTransferEnd
事件说明
当自定义转存开始时发出通知。
数据字段
字段名 | 类型 | 描述 |
RoomId | Integer | 房间 ID |
TransferDuration | Integer | 转存文件时长,单位秒 |
TransferSize | Integer | 转存文件大小,单位M |
TransferFileId | String | 转存 vod 文件 fileid |
TransferUrl | String | 转存 vod 的地址链接 |
RecordUrl | String | 互动课堂侧的录制文件地址 |
TransferStatus.Code | String | 错误码(0、TransferFailed、UnauthorizedOperation) |
TransferStatus.Message | String | 错误描述 |
{"Timestamp": 1679281184,"ExpireTime": 1679281784,"Sign": "964ff6d9463280d6a3bd4f7416213be9","SdkAppId": 3520371,"EventType": "MixedFlowTransferStart","EventData": {"RoomId": 350389385,"TransferDuration": 8,"TransferSize": 6,"TransferFileId": "1253642697459575214","TransferUrl": "https://1500029853.vod-qcloud.com/6cc0b3e3vodcq1500029853/7792888c1253642697459575214/f0.mp4","RecordUrl": "https://1500015970.vod2.myqcloud.com/6cac6e5evodcq1500015970/d6c3f4f41253642697457297772/f0.mp4","TransferStatus": {"Code": "0","Message": "SUCCESS"}}}