帮助中心

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 内部小优化,不影响以前版本的使用

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

二、简介

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

目前支持的功能如下:

分类 功能 描述
聊天 观看端聊天 支持在直播时聊天和观看回放时聊天
问答 观看端问答 支持观看直播时提问和收取问答
视频 观看端视频 支持移动端观看直播视频和回放视频
文档 观看端文档 支持移动端观看文档演示(不支持文档笔触信息)

注:视频、文档模块目前仅支持H5,如使用flash仍只能使用网页嵌入的方式。

三、向微吼申请开通权限

请点击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.0/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下所属活动

对上述内容中所提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条

响应事件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 问答消息发送事件
question 收到问答消息,只包含用户能接收的问答消息
getQuestionList 拉取直播问答消息后触发事件

VHALL_SDK客户端错误代码

错误码 说明
10000 消息体格式不对
10001 消息体为空
10002 当前用户被禁言
10003 聊天输入不能超过140个字符
10004 当前已开启全员禁言
10005 当前活动不是直播状态
10006 当前活动未开启问答
20000 接口请求成功
20005 没有数据

主要代码示例

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('question', function(msg) {
        console.log(userid);
    });

拉取问答消息后触发事件

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

附录:demo

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

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