用户工具

站点工具


open:js_sdk接入指南老版文档

JS SDK接入指南

一、简介

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

目前支持的功能如下:

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

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

二、向微吼申请开通权限

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

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

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

1.依赖库

本SDK依赖于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/1.0.0/vhallSDK.js"></script>

目前暂不支持https

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

3.初始化及权限验证

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

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

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

参数sign的生成规则如下:

将account、email、username、roomid、app_key(注意此处参数名为app_key而不是init方法中的appkey)以及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'; //签名有效期只有一个小时 

初始化主要错误码

错误码 说明
1001 活动不存在
1002 用户昵称不能空
1003 用户id不能空
1004 appkey不存在
1005 签名验证超时
1006 签名错误
1007 当前活动不是该appkey下所属活动

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

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

4.获取用户参会状态

初始化完成后可通过VHALL_SDK.onReady获取当前参会用户状态,在VHALL_SDK.userinfo对象下会有用户踢出状态,禁言状态,头像等信息。

VHALL_SDK.onReady = function() {
    console.log(VHALL_SDK.userinfo);
    console.log(VHALL_SDK.room);
 };

VHALL_SDK.userinfo和VHALL_SDK.room在consolelog中返回的内容如下:

   
   /**
    * VHALL_SDK.userinfo = {
    *     avatar:"//cnstatic01.e.vhall.com/static/images/watch/head50.png" //头像
    *     forbidchat:"" //"":未开启全员禁言,1:已开启全员禁言
    *     is_gag:0 //0:未禁言,1:禁言
    *     is_kickout:0 //0:未踢出,1:踢出
    *     role:"user"//用户角色
    *     userid:"用户参会id"
    *     username:"昵称"
    * }
    * VHALL_SDK.room = {
    *     type: 1 // 1:活动直播中,2:预约中,3:活动结束
    * }
    */

四、各功能模块说明

聊天

因聊天需要获取用户标识与头像,需提前使用第三方创建用户接口创建用户,如传入的第三方用户信息未匹配到用户标识,将自动进行创建,并默认为游客以及使用微吼的默认的头像。

注:目前聊天模块只支持观看端,如需要对聊天进行管理操作(禁言、踢出等功能),请前往微吼平台上进行操作.

主要调用API

API 说明 返回内容
sendChat({text:''}) 聊天消息发送,text:消息文本,长度限制为140个字符 组装好的聊天数据
vhall_get_live_history_chat_msg() 请求成功回调函数,data消息体数组
vhall_get_record_history_chat_msg(curr_page) 回放拉取历史聊天,curr_page:需拉取数据的页数,每页20条

响应事件API

API 说明
onUserOnline 用户上线事件消息
onUserOffline 用户下线事件消息
onChatMessage 直播新消息事件
onSendChatSuccess 发送聊天消息成功
onSendChatError 发送聊天消息失败
onDisadbleChat 直播禁言消息
onPermitChat 直播恢复禁言消息
onForbidchat 直播全员禁言消息,1为全员禁言,0为恢复全员禁言
onKickout 直播踢出消息
onKickoutrestore 直播恢复踢出消息
on_vhall_live_history_chat_msg 拉取直播历史消息,拉取50条
on_vhall_record_history_chat_msg 拉取回放历史消息,分页拉取,每页20条

主要错误状态码

VHALL_SDK.sendChat

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

主要代码示例

onUserOnline

     /**
     * [onUserOnline 用户上线]
     * @param  {[type]} msg [description]
     * @return {[type]}     [description]
     */
    VHALL_SDK.onUserOnline = function(msg) {
        console.log(msg);
    };

onUserOffline

    /**
     * [onUserOffline 用户下线]
     * @param  {[type]} msg [description]
     * @return {[type]}     [description]
     */
    VHALL_SDK.onUserOffline = function(msg) {
        console.log(msg);
    };

onChatMessage

    /**
     * [onChatMessage 直播收到聊天消息]
     * @param  {[type]} msg [object]
     * @return {[type]}     [description]
     */
    VHALL_SDK.onChatMessage = function(msg) {
        console.log(msg);
    };

onSendChatSuccess

    /**
     * [onSendChatSuccess 直播消息发送成功]
     * @return {[type]} [description]
     */
    VHALL_SDK.onSendChatSuccess = function(msg) {
        console.log(msg);
    };

onSendChatError

    /**
     * [onSendChatError 直播消息发送失败]
     * @return {[type]} [description]
     */
    VHALL_SDK.onSendChatError = function(msg) {
        console.log(msg);
    };

onDisadbleChat

    /**
     * [onDisadbleChat 直播禁言消息]
     * @param  {[type]} [禁言用户id]
     * @return {[type]} [description]
     */
    VHALL_SDK.onDisadbleChat = function(userid) {
        console.log(userid);
    };

onPermitChat

    /**
     * [onPermitChat 直播恢复禁言消息]
     * @param  {[type]} userid [恢复禁言用户id]
     * @return {[type]}     [description]
     */
    VHALL_SDK.onPermitChat = function(userid) {
        console.log(userid);
    };

onForbidchat

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

onKickout

    /**
     * [onKickout 直播踢出消息]
     * @param  {[type]} userid [被踢出用户id]
     * @return {[type]}     [description]
     */
    VHALL_SDK.onKickout = function(userid) {
        console.log(userid);
    };

onKickoutRestore

    /**
     * [onKickoutRestore 直播恢复踢出消息]
     * @param  {[type]} userid [恢复踢出用户id]
     * @return {[type]}     [description]
     */
    VHALL_SDK.onKickoutRestore = function(userid) {
        console.log(userid);
    };

on_vhall_live_history_chat_msg

    /**
     * [on_vhall_record_chat_msg 获取直播历史消息成功回调]
     * @param  {[arraylist]} msg [数据数组]
     * @return {[type]}     [description]
     */
    VHALL_SDK.on_vhall_live_record_chat_msg = function(msg) {
        console.log(msg);
    };

on_vhall_record_history_chat_msg

    /**
     * [on_vhall_record_chat_msg 获取回放历史消息成功回调]
     * @param  {[arraylist]} msg [数据数组,回放中有curr_page,total,total_page有数据]
     * @return {[type]}     [description]
     */
    VHALL_SDK.on_vhall_record_history_chat_msg = function(msg) {
        console.log(msg);
    };

vhall_get_live_history_chat_msg

    /**
     * [vhall_get_live_history_chat_msg 获取直播历史消息]
     * @type {[type]}
     */
    VHALL_SDK.vhall_get_live_history_chat_msg=function(data){
        console.log(data);
    });

vhall_get_record_history_chat_msg <code>

  /**
   * [vhall_get_record_history_chat_msg 获取第一页回放历史消息]
   * @type {[type]}
   */
  VHALL_SDK.vhall_get_record_history_chat_msg(1);
  

附录:demo

demo地址:http://cnstatic01.e.vhall.com/static/demo/jssdk.html

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

open/js_sdk接入指南老版文档.txt · 最后更改: 2016/12/02 15:07 由 rui.jiang