帮助中心

JS SDK接入指南

目录

一、更新记录

日期 版本号 更新内容 备注
2016-11-10 1.0.0 初稿,支持观看端聊天 下载旧版文档
2016-12-02 2.0.0 新增观看端问答&对1.0.0版本优化
2017-01-08 2.1.0 新增观看端视频与文档模块(仅只支持移动端)
2017-02-13 2.3.0 内部小优化,不影响以前版本的使用
2017-03-13 2.3.1 支持https
2017-03-15 2.3.2 修复2.3.1拉取回放历史聊天数据bug
2017-08-11 2.3.3 新增PC端观看视频和文档
2017-08-14 2.3.3 新增点播上传模块
2017-09-28 2.3.3 新增公告和签到功能
2017-10-12 2.3.3 新增自定义消息类型功能
2017-10-20 2.3.3 新增子账号点播上传功能
2017-10-312.3.3修复2.3.3上传纯音频文件无法播放

注:2.0.0及以上版本对1.0.0版本进行了优化,在已使用1.0.0版本的情况下如需使用2.0.0及以上版本的新增功能,需按照本版本更新相应代码

二、简介

本文档为了指导开发者更快使用微吼直播的“自助式网络直播服务SDK”通过引用JS的方式开发自己的PC网页以及H5来对接微吼直播平台,默认读者了解前端开发并拥有JavaScript基础,如需在移动端使用视频模块同时要求开发者了解HTML5 Video标签与Media标签的使用。

目前支持的功能如下:

分类 功能 描述
聊天 观看端聊天 支持在直播时聊天和观看回放时聊天
问答 观看端问答 支持观看直播时提问和收取问答
视频 观看端视频 支持移动端和PC端观看直播视频和回放视频
文档 观看端文档 支持移动端和PC端观看文档演示(移动端不支持文档笔触信息)
点播 视频文件上传 支持单视频上传、显示文件名称、断点续传功能、上传进度条和百分比、视频不同格式上传和准备、上传中、成功及错误反馈状态 、子账号点播上传
签到观看端签到支持用户观看直播时签到的功能
公告观看端公告支持观看端显示公告消息以及查看历史公告
消息自定义消息类型支持针对不同的消息类型进行了区分设计,观众在提交消息时会带上指定的消息类型,其他观众在接收到消息时会根据消息类型展示不同的效果。

三、向微吼申请开通权限

请点击API&SDK权限申请 立即沟通申请,申请后客户经理会在线上与您直接联系。

审核通过后,可以生成开发应用所需的App_Key 立即查看

四、SDK引入、初始化并注入权限验证

1.依赖库

本SDK依赖于JQuery库,请在需要引入JQuery的页面按以下代码示例进行引入,对JQuery版本没有要求

<script src="http://cnstatic01.e.vhall.com/3rdlibs/jquery/1.11.2/jquery.min.js" type="text/javascript"></script>

2.引入JS文件

在需要调用SDK的页面插入以下代码以引入JS文件:

<script type="text/javascript" src="http://cnstatic01.e.vhall.com/jssdk/dist/2.3.3/vhallSDK.js"></script>

支持https

注:支持使用AMD/CMD标准模块加载规范加载

3.初始化及权限验证

请使用以下的方法和参数进行SDK的初始化以及权限的验证

VHALL_SDK.init({
   account : '',//必填,唯一用户id,与使用第三方创建用户接口所传的third_user_id需一致)
   email : '',//参数必填,值可为空,用于与嵌入视频区用户同步
   username : '',//必填,用户昵称用以在各模块中显示
   roomid :'',//必填,当前聊天所在活动id
   app_key :'',//必填,启用服务唯一验证,API/SDK权限申请后生成,此参数名在1.0.0版本中为appkey,使用当前版本时请更新
   signedat :'',//必填,启用服务唯一验证,unix时间戳
   sign :'',//必填,启用服务唯一验证,有效期一小时,见下面的生成规则
   facedom :'',//可选,当使用微吼表情时必填,呼出表情弹窗dom属性 如('#id','.class'等)
   textdom : '',//可选,当使用微吼表情时必填,插入表情文本dom属性 如('#id','.class'等)
   videoContent : '',//【新】可选,当需要使用视频模块时,插入视频dom属性 如('#id','.class'等)
   docContent: '',//【新】可选,当需要使用文档模块时,插入视频dom属性 如('#id','.class'等)
});

注:如使用了网页嵌入,为确保嵌入页面的用户与SDK各模块中的用户是同一个用户,请尽量传入与视频区嵌入相同的email参数,否则会被统计成两个不同的用户

以上参数sign由PHP生成,其生成规则如下:

将account、email、username、roomid、app_key以及signedat这些参数:

1按参数名升序排列
2然后按参数名1+参数值+参数名2+参数值拼接
3在首尾各加上secret_key
4计算md5作为sign

示例如下

<?php
$secret_key = "f145b675f441cc00dd3e55746a0f4780";
$params = [
    "roomid"=> "123456789",
    "account"=> "12345",
    "email"=> "zhangsan@vhall.com",
    "username"=> "zhangsan",
    "app_key"=> "3eb72619af748d73f7fda1e6b0c692a9",
    "signedat"=> "1484620708"
];
// 按参数名升序排列
ksort($params);
// 将键值组合
array_walk($params,function(&$value,$key){
	$value = $key . $value;
});
// 拼接,在首尾各加上$secret_key,计算MD5值
$sign = md5($secret_key . implode('',$params) . $secret_key);
// 结果形如
// $sign=md5("f145b675f441cc00dd3e55746a0f4780account12345app_key3eb72619af748d73f7fda1e6b0c692a9emailzhangsan@vhall.comroomid123456789signedat1484620708usernamezhangsanf145b675f441cc00dd3e55746a0f4780");
// 计算结果
// $sign = '92eec52c58b9bddc0ba663c75a3c1f7f'; //签名有效期只有一个小时 

VHALL_SDK初始化时服务端返回的错误码

错误码 说明
1001 活动不存在
1002 用户昵称不能空
1003 用户id不能空
1004 appkey不存在
1005 签名验证超时
1006 签名错误
1007 当前活动不是该appkey下所属活动
1008超出套餐使用量
1009该视频正在转码中
1010 该视频转码失败
1011该视频正在审核中
1012该视频已下线,有疑问请联系客服

对上述内容中所提appkey、app_key以及secret_key三个参数的说明:

  • appkey和app_key均表示添加应用后所得到的AppKey列对应的值
  • secret_key表示添加应用后所得到的SecretKey(注意与AppSecretKey区分)列对应的值

五、详细功能说明

获取直播功能信息

聊天和问答需要获取用户标识与头像,需提前使用第三方创建用户接口创建用户,如传入的第三方用户信息未匹配到用户标识,将自动进行创建,并默认为游客以及使用微吼的默认头像。目前聊天和问答模块只支持观看端,如需要进行管理操作(禁言、踢出、过滤以及回答等功能),请前往微吼平台上进行操作

视频模块目前只支持移动端,需在页面上自行添加HTML5的video标签,样式自行定义,播放相关事件使用的是HTML5中 video标签 media标签的原生事件

主要调用API

API 说明 返回内容
getRoominfo() 获取当前活动状态 活动相关的状态信息
getUserinfo() 获取当前用户参会信息 用户参会的信息
player.setPlayerDefinition(name) 设置播放清晰度,值来自于canPlayDefinitions事件中的msg的键 切换播放清晰度
player.setPlayerLine(name) 设置播放线路,值来自于canPlayLines事件中的msg的键 切换播放线路
sendChat({text:' '}) 聊天消息发送,text:消息文本,长度限制为140个字符 组装好的聊天数据
sendQuestion({text:' '}) 提问问题发送,text:问题文本,长度限制为140个字符 组装好的提问数据
vhall_get_live_history_chat_msg() 获取直播聊天历史记录 请求后触发事件vhall_live_history_chat_msg
getQuestionlist() 获取问答记录 请求后触发事件getQuestionList
vhall_get_record_history_chat_msg(curr_page) 回放拉取历史聊天,curr_page:需拉取数据的页数,每页20条
vhall_get_history_notice(curr_page)获取历史直播公告记录,curr_page:需拉取数据的页数,默认值为1,每页20条
sendSign(签到ID)发送签到请求,值来自于startSign事件中的msg的消息体sign_id
sendCustomEvent(data)发送用户自定义广播消息,data类型为object,可自定义,如{type:'xxx_event',data:{id:1,name:'test'}},data大小限制为JSON字符串长度不能大于200

响应事件API

API 说明
ready SDK准备就绪后触发事件,全局事件
error SDK调用错误事件消息,全局事件
playerReady 播放器准备就绪后触发事件,全局事件
streamOver 直播活动结束,全局事件
publishStart 活动开始推流,全局事件
canPlayLines 获取视频可播放线路,播放器事件
canPlayDefinitions 获取视频可播放清晰度,播放器事件
userOnline 用户上线事件消息
userOffline 用户下线事件消息
chatMsg 收到直播聊天消息事件
sendChat 发送聊天消息后触发事件
disadbleChat 直播禁言消息
permitChat 直播恢复禁言消息
forbidchat 直播全员禁言消息,1为全员禁言,0为恢复全员禁言
kickout 直播踢出消息
kickoutrestore 直播恢复踢出消息
vhall_live_history_chat_msg 拉取直播历史消息后触发事件
vhall_record_history_chat_msg 拉取回放历史消息后触发事件
questionSwitch 问答开关消息
sendQuestion 问答消息发送事件
questionMsg 收到问答消息,只包含用户能接收的问答消息
getQuestionList 拉取直播问答消息后触发事件
sendSign发送签到请求后触发事件
startSign接收到签到消息后触发事件
vhall_history_notice拉取历史直播公告消息后触发事件
announcement收到公告消息时候触发
sendCustomEvent发送用户自定义广播消息请求后触发
customEvent接收到用户自定义广播消息后触发事件

VHALL_SDK客户端错误代码

错误码 说明
10000 消息体格式不对
10001 消息体为空
10002 当前用户被禁言
10003 聊天输入不能超过140个字符
10004 当前已开启全员禁言
10005 当前活动不是直播状态
10006 当前活动未开启问答
20000 接口请求成功
20005 接口请求失败
10007当前用户被踢出
50400用户身份认证错误
50401用户发送消息频次超过限制
50402活动xxx发送消息频次超过限制
50403自定义广播消息内容长度超过限制

主要代码示例

SDK准备就绪后触发事件

     /**
     * [ready sdk准备就绪]
     */
    VHALL_SDK.on('ready', function() {
        VHALL_SDK.getUserinfo();
        /**
         * {
         *     avatar:"//cnstatic01.e.vhall.com/static/images/watch/head50.png" //头像
         *     forbidchat:"" //0:未开启全员禁言,1:已开启全员禁言
         *     is_gag:0 //0:未禁言,1:禁言
         *     is_kickout:0 //0:未踢出,1:踢出
         *     role:"user"//用户角色
         *     userid:"用户参会id"
         *     username:"昵称"
         * }
         */
        VHALL_SDK.getRoominfo();
        /**
         *  {
         *     type: 1 // 1:活动直播中,2:预约中,3:活动结束
         *     openQuestion : 1 //1: 开启,0 || '':关闭
         * }
         */
    });

SDK调用错误事件

    /**
     * [error sdk调用错误事件]
     * @param  {[type]} msg [description]
     */
    VHALL_SDK.on('error', function(msg) {
        console.log(msg);
    });

播放器就绪后触发事件

    VHALL_SDK.on("playerReady", function(){
    /**
     * 可播线路消息
     */
    VHALL_SDK.player.on('canPlayLines', function(msg) {
        var _src = '';
        //  i 的值为之后调用方法VHALL_SDK.player.setPlayerLine的传参
        for (var i in msg) {
            _src += '<li>' + i + '</li>';
        }
        $("#lines").html(_src).find("li").eq(0).addClass('active');
    });
    /**
     * 可播清晰度消息
     */
    VHALL_SDK.player.on('canPlayDefinitions', function(msg) {
        var _src = '';
         //  i 的值为之后调用方法VHALL_SDK.player.setPlayerDefinition的传参
        for (var i in msg) {
            _src += '<li>' + i + '</li>';
        }
        $("#definitions").html(_src).find("li").eq(0).addClass('active');
    });
});

活动开始推流

 
  VHALL_SDK.on('publishStart', function(msg) {
            alert('活动开始推流');            
        });

直播结束

  VHALL_SDK.on('streamOver', function(msg) {
            alert('活动已结束');            
        });

用户上线

    /**
     * [userOnline 用户上线]
     * @param  {[type]} msg [description]
     */
    VHALL_SDK.on('userOnline', function(msg) {
        console.log(msg);
    });

用户下线

    /**
     * [userOffline 用户下线]
     * @param  {[type]} msg [description]
     */
    VHALL_SDK.on('userOffline', function(msg) {
        console.log(msg);
    });

收到直播聊天消息

    /**
     * [chatMsg 直播收到聊天消息]
     * @param  {[type]} msg [object]
     */
    VHALL_SDK.on('chatMsg', function(msg) {
        console.log(msg);
    });

直播消息发送后触发事件

    /**
     * [sendChat 直播消息发送后事件]
     */
    VHALL_SDK.on('sendChat, function(msg) {
        console.log(msg);
    });

问答消息发送后触发事件

    /**
     * [sendQuestion 直播问答消息发送事件]
     */
    VHALL_SDK.on('sendQuestion, function(msg) {
        console.log(msg);
    });

直播禁言消息

    /**
     * [disadbleChat 直播禁言消息]
     * @param  {[type]} [禁言用户id]
     */
    VHALL_SDK.on('disadbleChat', function(userid) {
        console.log(userid);
    });

直播恢复禁言消息

    /**
     * [forbidchat 直播全员禁言消息]
     * @param  {[type]} status [1:开启,0:关闭]
     */
    VHALL_SDK.on('forbidchat', function(status) {
        console.log(status);
    });

直播踢出消息

    /**
     * [kickout 直播踢出消息]
     * @param  {[type]} userid [被踢出用户id]
     */
    VHALL_SDK.on('kickout', function(userid) {
        console.log(userid);
    });

直播恢复踢出消息

    /**
     * [kickoutRestore 直播恢复踢出消息]
     * @param  {[type]} userid [恢复踢出用户id]
     */
    VHALL_SDK.on('kickoutRestore', function(userid) {
        console.log(userid);
    });

获取直播历史消息成功回调

    /**
     * [vhall_live_history_chat_msg 获取直播历史消息成功回调]
     * @param  {[arraylist]} msg [数据数组]
     */
    VHALL_SDK.on('vhall_live_history_chat_msg', function(msg) {
        console.log(msg);
    });

获取回放历史消息成功回调

    /**
     * [vhall__record_history_chat_msg 获取回放历史消息成功回调]
     * @param  {[arraylist]} msg [数据数组,回放中有curr_page,total,total_page有数据]
     */
    VHALL_SDK.on('vhall_record_history_chat_msg', function(msg) {
        console.log(msg);
    });

问答开关消息

    /**
     * [questionSwitch 直播问答开关消息]
     * @param  {[type]} msg [msg.status 1:开启,0:关闭]
     */
    VHALL_SDK.on('questionSwitch', function(msg) {
        console.log(userid);
    });

发送问答消息后触发事件

    /**
     * [sendQuestion 直播问答消息发送事件]
     */
    VHALL_SDK.on('sendQuestion, function(msg) {
        console.log(msg);
    });

收到问答消息

    /**
     * [question 直播问答消息]
     * @param  {[type]} msg [消息体]
     */
    VHALL_SDK.on('questionMsg', function(msg) {
        console.log(userid);
    });

拉取问答消息后触发事件

    /**
     * [getQuestionList 获取直播问答历史消息]
     * @type {[type]}
     */
    VHALL_SDK.getQuestionList();

附录:demo

demo地址:http://cnstatic01.e.vhall.com/jssdk/dist/2.3.3/

demo提供了基本的样式,开发者可在demo样式的基础上修改成自定义的样式

获取点播功能信息

点播上传

1.依赖库

本SDK依赖于JQuery库,请在需要引入JQuery的页面按以下代码示例进行引入,对JQuery版本没有要求

<script src="http://cnstatic01.e.vhall.com/3rdlibs/jquery/1.11.2/jquery.min.js" type="text/javascript"></script> 

2.引入JS文件

在需要调用SDK的页面插入以下代码以引入JS文件:

<script type="text/javascript" src="http://cnstatic01.e.vhall.com/demand-upload-jssdk/dist/1.0.0/vhallDemandSDK.js"></script>

3.方法指引:

    /** 
     * 1、初始化dom
     */
    <input type="file" id="upload"/> 
    /**
     * 2、根据appKey和secretKey生成sign 生成sign的具体规则如下:
     *   (1) 按参数名升序排列
     *   (2) 然后按参数名1+参数值+参数名2+参数值拼接
     *   (3) 在首尾各加上secret_key
     *   (4) 计算md5作为sign
     */
	// 该代码为客户端DEMO代码 仅供参考(生产环境请参考代码下面的服务端代码) 
        function sign(appKey, secretKey) {
            var param = {};
            return {
                doSign :function(){
                    param.auth_type = 2;
                    param.app_key = appKey;
                    param.signed_at = new Date().getTime().toString().substr(0, 10);
                    var paramArray = getArray(param);
                    var signStr = secretKey;
 
                    for(var i =0; i < paramArray.length; i ++) {
                        signStr += paramArray[i];
                    }
 
                    signStr += secretKey;
 
                    return {
                        str : hex_md5(signStr), /* 用MD5加密得到最终sign */
                        time : param.signed_at /* 获取到sign的时间戳 */
                    }
                }
            }
 
            function getArray(paramObj) {
                var paramArray = [];
                var length = 0;
                for (var i in paramObj) {
                    paramArray[length] = i + paramObj[i];
                    length += 1;
                }
                paramArray.length = length;
                return paramArray.sort();
            }
        }

appKey和secretKey获取方法获取请参见http://e.vhall.com/home/vhallapi/instructions
服务签名端代码请参考 http://e.vhall.com/home/vhallapi/instructions

    /** 
     * 3、调用 vhallDemandSDK 方法
     */
         vhallDemandSDK('#upload',{
            params: {
                sign:sign,  /**sign**/
	        signed_at:time, /**获取sign的时间戳**/
	        app_key:appKey,
	        sdkChildID:sdkChildID  /**子账号ID不传默认为主账号**/
            },
            ready: function() {
                /**
                  * 初始化完成的回调函数
                **/
            },
            beforeUpload:function() {
                /**
                  * 准备中...(文件进行MD5转换过程)
                **/
            },
            progress:function(percent, file){
               /**
                 * 上传中...'
                 * 'percent 上传进度百分比'
                 * 'file 上传文档具体信息
               **/
            },
            uploadSuccess: function(res){
               /**
                 * 上传成功!'
                 * 'res 成功返回的回放ID records_id 和 活动ID webinar_id
               **/
            },
            error: function(msg,file,e){
                /**
                  * 上传出错'
                  * 'msg 错误返回的状态码信息'
                **/
            }
        })

错误状态码对应信息参见消息体

错误码 说明
10000 当前浏览器不支持断点上传
10001 请传入类似于”#id”选择器
10003 当前传入的dom不是input file
10004 不支持该文件格式
10005 上传文件大于10GB
10006 获取上传临时授权失败
10008 没有上传权限
10009 回放标题不能为空
11010 活动标题不能为空
11011 视频路径不能为空
10104 子账号信息不存在

4.上传的文件所支持的格式:

'rmvb', 'mp4', 'avi', 'wmv', 'mkv', 'flv', 'mp3', 'wav', 'mov'

5.DEMO:

地址:http://cnstatic01.e.vhall.com/demand-upload-jssdk/dist/1.0.0/index.html?appKey=appKey&secretKey=secretKey&sdkChildID=sdkChildID

需要将获取到的 appKey 和 secretKey 以URL传参的方式拼接到URL中即可使用

6.其他:

为保证本SDK能够正常使用请尽量在高版本浏览器下使用本SDK产品(Chrome58及以上版本)