JS SDK接入指南

• 获取直播功能信息
• 获取点播功能信息

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

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

目前支持的功能如下：

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

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

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

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

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

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

支持https

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

请使用以下的方法和参数进行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这些参数：

示例如下

<?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初始化时服务端返回的错误码

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

• appkey和app_key均表示添加应用后所得到的AppKey列对应的值

• secret_key表示添加应用后所得到的SecretKey（注意与AppSecretKey区分）列对应的值

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

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

主要调用API

响应事件API

VHALL_SDK客户端错误代码

主要代码示例

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地址：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 错误返回的状态码信息'
                **/
            }
        })

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

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及以上版本）