相关回调及校验说明

相关回调

描述

云端播放器运行过程中，会以 POST 方式向回调地址发起 HTTP 请求，请求包体为 JSON 格式。

回调参数

• EventType 为 1 时 Detail 成员列表如下：

  参数	类型	描述
  CreateTime	Number	云端播放器创建成功的 Unix 时间戳（秒）。
  PlayTime	Number	云端播放器开始播放媒体流的 Unix 时间戳（秒）。
  MaxIdleTime	Number	云端播放器处于空闲状态的最大时长（秒），即媒体流为非播放状态的最大时长。
  StreamUrl	String	媒体资源的地址。

• EventType 为 2 时 Detail 成员列表如下：

  参数	类型	描述
  PlayTime	Number	云端播放器开始播放媒体流的 Unix 时间戳（秒）。
  Reason	Number	云端播放器销毁的原因。 1：调用了 DeletePlayer 接口主动销毁。 2：处于空闲状态的时长超过了 MaxIdleTime。 3：媒体资源播放已结束。 4：推流失败。 5：进入房间失败、或被踢出房间。

• EventType 为 3 时 Detail 成员列表如下：

  参数	类型	描述
  Status	Number	云端播放器的状态。 1：创建中。 2：连接媒体资源中。 3：等待播放。 4：播放中。 5：暂停中。 6：连接媒体资源失败。 7：播放结束。 8：已销毁。

• EventType 为 4 时 Detail 成员列表如下：

  参数	类型	描述
  Code	Number	异常类型。 -1：资源加载超时。 -2：seek 超时。 -3：seek 失败。 -4：音频渲染帧率异常。 -5：解码数据出错。 -6：音画不同步。 -7：播放卡顿。 1：播放进度异常。 2：视频推流帧率异常（正常检测）。 正常检测，是指在非流控状态下，推流帧率连续两次小于基准帧率的 90%，ZEGO 会在连续触发两次时回调异常给您。 3：视频推流帧率异常（严格检测）。 严格检测，是指在正常检测的基础上新增一个检测规则，即当推流帧率连续 3 次低于配置帧率的 40%，或者出现一次推流帧率为 0，ZEGO 会立即回调异常给您。 严格检测默认关闭，如需开启，请联系 ZEGO 技术支持。 4：音频推流帧率异常。 5：流控状态持续时间超过 5 分钟。

  云端播放器检测到上述异常事件后，内部会自动进行重试。如果短时间内多次收到该类异常回调通知，开发者需要检查资源服务器访问是否正常、或做其它容错处理。

回调示例

以下是调用 CreatePlayer 接口创建云端播放器成功的回调示例。

{
    "AppId": 123456789,
    "RoomId": "room_12",
    "PlayerId": "XXXXXX",
    "PlayerName": "XXXXXX",
    "EventType": 1,
    "Nonce": "abcdd22113",
    "Timestamp": "1681221510",
    "Signature": "XXXXXXX",
    "EventTime": 1681221510034,
    "Detail": {
        "CreateTime": 1681221508,
        "PlayTime": 1681221508,
        "MaxIdleTime": 30,
        "StreamUrl": "https://your-bucket.oss-cn-shanghai.aliyuncs.com/video/test.mp4"
    }
}

返回响应

返回 HTTP status code 为 2XX （例如 200）表示成功，其他响应都表示失败。

回调重试策略

如果 ZEGO 服务器没有收到响应，会立刻尝试重试，最多进行 2 次重试。若第 2 次重试后仍然失败，将不再重试，该回调丢失。

回调来源校验说明

为提高数据安全性，开发者在收到 ZEGO 服务端发出的回调时，进行本地签名计算，并与 signature 进行对比，判断该请求是否合法。

请参考以下方式，校验回调请求的发起来源是否为 ZEGO 云端播放器。

校验方法

开发者需要将自行计算出的 signature 值，与回调结果中的 signature 值进行对比，判断两者是否一致，以此来验证请求的发起方是否为 ZEGO 云端播放器。

自行计算 signature 的流程如下图：

• nonce：回调请求中的随机数。
• timestamp：回调请求中的 Unix 时间戳。
• callbacksecret：服务端校验密钥。在 ZEGO 控制台 注册项目时生成，可在 “控制台 > 项目配置 > 项目信息 > 配置信息” 中查看。

示例代码

以下示例代码用于生成和检验 signature。

$signature = $_POST["signature"];
$timestamp = $_POST["timestamp"];
$nonce = $_POST["nonce"];

$secret = callbacksecret;//后台获取的callbacksecret
$tmpArr = array($secret, $timestamp, $nonce);
sort($tmpArr, SORT_STRING);
$tmpStr = implode( $tmpArr );
$tmpStr = sha1( $tmpStr );

if( $tmpStr == $signature ){
    return true;
} else {
    return false;
}

// 从请求参数中获取到 signature, timestamp, nonce
String signature = request.getParameter("signature");
long timestamp = request.getParameter("timestamp");
String nonce = request.getParameter("nonce");

// 后台获取的callbacksecret
String secret = callbacksecret;

String[] tempArr = {secret, ""+timestamp, nonce};
Arrays.sort(tempArr);

String tmpStr = "";
for (int i = 0; i < tempArr.length; i++) {
    tmpStr += tempArr[i];
}
tmpStr = org.apache.commons.codec.digest.DigestUtils.sha1Hex(tmpStr);

return tmpStr.equals(signature);

输出示例

$timestamp = 1470820198;
$nonce = 123412;
$secret = 'secret';

排序拼接后需要加密的原始串为:1234121470820198secret
加密的结果为:5bd59fd62953a8059fb7eaba95720f66d19e4517