用户工具

站点工具


open:js_sdk接入指南20161130

JS SDK接入指南

一、更新记录

日期 版本号 更新内容 其他
2016-11-10 1.0.0 初稿,支持观看端聊天 下载旧版文档
2016-12-02 2.0.0 新增观看端问答&对1.0.0版本优化

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

二、简介

本文档为了指导开发者更快使用微吼直播的“自助式网络直播服务SDK”通过引用JS的方式开发自己的PC网页以及H5来对接微吼直播平台,默认读者了解前端开发同时拥有JavaScript基础。

目前支持的功能如下:

分类 功能 描述
聊天 观看端聊天 支持在直播时聊天和观看回放时聊天
问答 观看端问答 支持观看直播时提问和收取问答

注:视频、文档模块目前仍只能使用网页嵌入的方式。

三、向微吼申请开通权限

请点击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/static/js/webSDK/2.0.0/vhallSDK.js"></script>

目前暂不支持https

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

3.初始化及权限验证

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

VHALL_SDK.init({
   account : '',//必填,唯一用户id,与使用第三方创建用户接口中的account所传的值需保持一致
   email : '',//参数必填,值可为空,用于与嵌入视频区用户同步
   username : '',//必填,用户昵称用以在各模块中显示
   roomid :'',//必填,当前聊天所在活动id,可支持子账号创建的活动
   app_key :'',//必填,启用服务唯一验证,API/SDK权限申请后生成,此参数名在1.0.0版本中为appkey,使用当前版本时请更新
   signedat :'',//必填,启用服务唯一验证,unix时间戳
   sign :'',//必填,启用服务唯一验证,有效期一小时,见下面的生成规则
   facedom :'',//可选,当使用微吼表情时必填,呼出表情弹窗dom属性 如('#id','.class'等)
   textdom : '',//可选,当使用微吼表情时必填,插入表情文本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 = "user_secret_key";
$params = [
    "roomid"=> "123456789",
    "account"=> "accountid",
    "email"=> "user_email",
    "username"=> "username",
    "app_key"=> "user_app_key",
    "signedat"=> "timestamp_now"
];
// 按参数名升序排列
ksort($params);
// 将键值组合
array_walk($params,function(&$value,$key){
	$value = $key . $value;
});
// 拼接,在首尾各加上$secret_key,计算MD5值
$sign = md5($secret_key . implode('',$params) . $secret_key);
// 结果形如
// $sign=md5("user_secret_keyaccountaccountidapp_keyuser_app_keyemailuser_emailroomid123456789signedattimestamp_nowusernameusernameuser_secret_key");
// 计算结果
// $sign = 'c641af5046aa0599ab58c57a52a24f83'; //签名有效期只有一个小时 

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区分)列对应的值

五、详细功能说明

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

主要调用API

API 说明 返回内容
getRoominfo() 获取当前活动状态 活动相关的状态信息
getUserinfo() 获取当前用户参会信息 用户参会的信息
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调用错误事件消息
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);
    });

用户上线

    /**
     * [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/static/demo/jssdk2.0.html

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

open/js_sdk接入指南20161130.txt · 最后更改: 2017/01/13 02:03 由 rui.jiang