一、功能介绍
当需要观众登录机构的用户系统,验证通过后才能进入直播观看页时,可使用外部授权。验证观众是否可观看由机构实现,验证通过后打开的观看页面由保利威实现。
机构后台针对通过验证的观众,打开直播观看页时URL需带上指定的参数,经过直播系统验证请求合法后,直播系统会调用客户在后台设置的自定义授权验证接口,进行接口授权验证,两次验证通过,才能进入直播观看页,并且接口返回的观众账号具有唯一性,即同一个账号不能在两个地方同时登录,较早登录的账号会被踢出。
- Secretkey:用于校验签名的生成。
- 自定义URL:用于外部授权验证的API接口。
- 跳转地址:观众直接访问Polyv观看页,会跳转到该地址;若跳转地址为空,则显示默认提示页。
二、展示效果
http://demo.polyv.net/chenwb/open.php
三、外部授权流程详解
- 在自定义URL处填写用户的授权验证API接口,需要完整的不带参数的url地址(不能是localhost等本地服务器地址,且不能带 ? 号),如:http://myWebsite.com/auth。
- 在请求保利威视直播观看页时需带上userid(用户ID,仅支持英文大小写、数字和下划线)、ts(当前时间的毫秒级时间戳)和sign(用于校验的签名,生成规则是secretkey + userid + secretkey + ts进行MD5加密),如https://live.polyv.cn/watch/125527?userid=6b3a43&ts=1498547407000&sign=dd9dc9e42ad7c0204398e925a4ee0f46
- 直播系统会对字符串secretkey+userid+secretkey+ts进行MD5加密后与用户提交的sign参数的值做比较判断是否合法。一次成功请求后,该链接将失效(sign只能成功使用一次)。如果合法,直播系统将调用用户的api接口,并把userid(用户ID)、ts(当前时间的毫秒级时间戳)和token(用于校验的签名)三个参数传给用户。如果不合法,则给出错误提示。
- 用户API接口获取userid、ts和token参数后,进行签名验证。如果验证通过,则将学员相关信息(详参“用户系统返回观众信息json说明”)返回给直播系统。
- 直播系统接收用户API接口返回的数据,如果验证成功,则进入到保利威视直播观看页,聊天区将显示学员的昵称和头像。如果验证失败,则给出错误提示。
交互图如下
四、参数说明
请求观看页所带参数
用户将以下的参数提交给直播的观看页,(例如:https://live.polyv.cn/watch/125527?userid=test&ts=1565948760108&sign=b0b6eb22b6fa5e5684873052c27a6cef)
直播系统会对sign 进行验证,判断是否合法,一次成功请求后,该链接将失效(sign只能成功使用一次)
参数名称 | 必填 | 参数说明 |
---|---|---|
userid | 是 | 观众id,非中文字符串(长度最大64位字符串) |
ts | 是 | 13位毫秒级时间戳 |
sign | 是 | 用户校验的签名,加密规则:secretkey + userid + secretkey + ts |
观看页请求观众信息接口参数
观看页请求用户在后台设置的自定义URL获取观众信息,以下为请求所带的参数
参数名 | 必填 | 参数说明 |
---|---|---|
userid | 是 | 观众id,非中文字字符串(请求观看页时所带的userid)(长度最大64位字符串) |
channelId | 是 | 频道号 |
ts | 是 | 当前时间的13位毫秒级时间戳 |
token | 是 | 用于校验的签名,生成的规则:对字符串secretkey + userid + secretkey + ts进行MD5加密生成的字符串 |
用户系统返回观众信息json说明
用户的接口接收到请求后,进行相关检验判断通过后,将学员信息以json格式的信息返回
字段 | 类型 | 必填 | 字段说明 |
---|---|---|---|
status | int | 是 | 请求结果,1表示成功,0表示失败 |
userid | string | 是 | 观众ID(长度最大64位字符串) |
nickname | string | 是 | 观众昵称 |
marqueeName | string | 否 | 自定义跑马灯字段 |
avatar | string | 是 | 观众头像地址,头像尺寸200*200,体积不超过30KB。 |
actor | string | 否 | 观众头衔地址 |
actorFColor | string | 否 | 观众头衔字体颜色,非必须,请使用CSS Hex值并且带# 号 |
actorBgColor | string | 否 | 观众头衔背景颜色,非必须,请使用CSS Hex值带# 号 |
param4 | string | 否 | 统计观众观看日志的自定义参数 |
param5 | string | 否 | 统计观众观看日志的自定义参数 |
errorUrl | string | 否 | 请求失败时观看页跳转的地址(会带上channelId和userid) |
成功返回:
{"status":1,"userid":"2qwerty","nickname":"testNick","actor":"paul","actorFColor":"#123123","actorBgColor":"#FFFFFF","param4":"param4test","avatar":"http:\/\/live.polyv.net\/assets\/images\/avatars\/9avatar.jpg"}
失败返回:
{"status":0,"errorUrl":"http://test.com"}
注意事项:同时传入了nickname和marqueeName,在观看日志中,marqueeName将作为用户昵称的统计字段
五、代码示例(PHP)
<?php
header("Content-type:application/json;charset=UTF-8"); //媒体格式类型为JSON数据格式
$secretkey = "aDrOt0Cpy8";
$userid = isset($_GET["userid"]) ? $_GET["userid"] : "";
$ts = isset($_GET["ts"]) ? $_GET["ts"] : "";
$channelId = isset($_GET["channelId"]) ? $_GET["channelId"] : "";
$token = isset($_GET["token"]) ? $_GET["token"] : "";
$sign = md5($secretkey . $userid . $secretkey . $ts);
//用户进行授权验证,返回对应的数据(json格式)
if ($sign == $token) {
//验证正确
$array1 = array(
"status" => 1, //返回状态
"userid" => $userid, //学员唯一标识
"nickname" => "保利威", //学员昵称
"marqueeName" => "polyv", //自定义跑马灯字段
"avatar" => "http://live.polyv.net/assets/images/avatars/9avatar.jpg", //学员头像
"actor" => "VIP", // 学员头衔,可以不传递
"actorFColor" => "#5C96E5", // 学员头衔字体颜色,可以不传递
"actorBgColor" => "#FFFFFF" // 学员头衔背景颜色,可以不传递
);
$json1 = json_encode($array1);
echo $json1;
} else {
//验证错误
$array0 = array(
"status" => 0,
"errorUrl" => "http://xxx.xx.xxxx/error.html", //验证错误跳转的自定义页面
);
$json0 = json_encode($array0);
echo $json0;
}
六、注意事项
-
.要保证自定义验证接口返回的userid的唯一性,当多个观众使用同一个userid进入观看页时,较早登录的观众会被后面登录的观众踢出,观看页会提示 "帐号在另外的地方登录,您将被退出观看。"如下图:
-
自定义验证接口需要填写完整的URL地址,且不能是localhost等本地服务器地址。
- 自定义验证接口返回给直播系统的数据格式是json格式。
七、错误提示
- user not found:请求自定义验证接口错误,或者接口返回的格式不对。
- invalid sign:签名错误,sign的生成规则是secretkey+userid+secretkey+ts进行MD5加密。
- sign expired:签名过期,每一个sign只能使用一次,使用后需重新生成。