直播 SDK

1 概述

1.1 文档目的

众多客户希望能拥有更多的播放器设计能力，特别是对于拥有UI, 开发人员资源的公司。为此，特提供web端播放器集成SDK，以便客户可以针对自己的业务场景设计最符合自己业务场景的播放器。

1.2 术语与缩写解释

编号	术语	解释
	SDK	Software Development Kit
	Widget	部件，能展现特定功能的html片段。目前仅提供视频部件和文档部件
	Webcast服务	Gensee提供的直播服务，在域名后以webcast作为二级目录名
	Training服务	Gensee提供的教育培训服务，在域名后以training作为二级目录名
	站点(Site)	Gensee的一个客户，拥有一个站点。通常站点的标示是域名，比如test.gensee.com

2 SDK使用介绍

2.1 需要引入的javascript

<script type="text/javascript" src="http://static.gensee.com/webcast/static/sdk/js/gssdk.js"></script>

注意：如果直接引用，在sdk内容更新时可能存在未下载最新sdk而使用浏览器中缓存的版本，在用户不清空缓存时会存在代码不一致导致异常的报错。建议对sdk添加时间戳，保证gssdk.js引入时是服务器最新版本。
例：
<script type="text/javascript">
(function(){
     var randomh=Math.random();
     var e = document.getElementsByTagName("script")[0];
     var d = document.createElement("script");
     d.src = "//site.com/js.js©x="+randomh+"";
     d.type = "text/javascript";
     d.async = true;
     d.defer = true;
     e.parentNode.insertBefore(d,e);
})();
document.write("<script type='text/javascript' src='//static.gensee.com/webcast/static/sdk/js/gssdk.js©v=" + Date.now() + "'><\/script>");
</script>

2.2 Html命名空间

2.3 Video Widget （必选）

注意：一场直播在一个页面上请保证只有一个VideoWidget！

网页html的body内，任意地方可以插入如下代码：

<gs:video-live id="videoComponent" site="192.168.0.168" ctx="webcast" ownerid="f8625298d18042fbbba7a8" uid="10000055831" uname="user5623" authcode="333333"/>

必填属性说明：

site: 站点域名（必填）Example:www.gensee.com
ownerid: webcast服务下，表示为直播ID；training服务下，表示为课堂ID （必填）
authcode: （可选）校验码。对应直播(课堂)的web端口令。若直播(课堂)要求输入口令，则此属性必填。否则不需要。

可选属性说明

id: html的元素ID。（可选）用户可自行指定。SDK将以此ID作为Widget ID。
ctx: 服务选项。可选值为webcast或training。无此属性说明默认使用webcast服务。
uid: 用户ID （数字型，可选）。若无此属性，系统会自动生成随机UID。为了避免uid跟Gensee系统的内部用户ID冲突，该uid要求必须大于1000000000 小于9007199254740992
uname: 用户名称（可选）。若无此属性，系统自动生成英文随机名称。若直播(课堂)要求登录，则用户名称必须是系统的登录账号。注：登录方式无论是账号密码或手机动态密码，接口只能使用账户登录。
encodetype: 指定authcode的编码方式。值若为md5，则authcode必须经过MD5的32位小写编码过。不写该属性或者值为空，则authcode为明文。
password: （可选）若直播(课堂)要求登录，此属性表示登录账号的密码。
group: 分组名称。（可选）适用于不同直播(课堂)的Widget放在同一个页面中的情况。Group用来标示哪些Video和Doc Widget属于同一个组。相同组内的Widget可以共享通讯信息。若不填，SDK会自动将Widget归属到默认组。
k: 若直播开启第三方认证功能，则需要k值验证。关于第三方认证，请参看Gensee_URL_API_SPEC。
lang: 指定语言。中文是zh_CN, 英文是 en，日文是ja。
bar: 指定是否显示控制栏，值为true或者false，注：ipad和android4.0及以上版本的移动播放不支持。
bgimg: 设置背景图案，图片URL地址。
completed: video widget创建之后调用的回调函数名称。若指定回调函数名称，则在widget生成后，会传递指定数据给该回调函数（说明见Part6 可扩展实时数据调用）
video：设置实时是否使用音频还是视频，值为：true或者false，true表示视频，false表示音频，默认情况true。注意：该值得设置只对移动端设备生效。
btnimg:设置播放按钮图案，图片url地址。注意：该值得设置只对移动端设备生效。
stream: 设置移动端初始化码流。值为：0 – 标清，1 – 原始。默认为1。
embednetsettings：设置内置优选网络是否开放，值为true或者false。默认开放。
fullscreen是否在flash视频界面上显示全屏操作按钮。可选值为true或者false。默认值为false。（可选）

2.4Doc Widget（可选）

网页html的body内，任意地方可以插入如下代码：

<gs:doc id="docComponent" site="192.168.0.168" ownerid=" f8625298d18042fbbba7a8" />

属性说明：

id: html的element id。（可选）
site: 站点域名（必填）
ownerid: 直播ID。（必填）
group: 分组名称。作用同Video Widget的Group属性。（可选）
ctx: 服务选项。可选值为webcast或training。无此属性说明默认使用webcast服务。（可选）
fullscreen:是否支持flash全屏。可选值为true或者false。默认值为false。（可选）
bgcolor: 背景色。参考值：#00ff00。默认为空。（可选）
bgimg: 设置背景图案，图片URL地址。

2.5Channel (可选)

Channel是SDK提供的基于组（group）的数据通讯通道。相同组（group）的Widget和Channel共享通讯方式和数据。

通讯分两种形式：

监听事件
提交数据

根据不同类型，把对应的API罗列在下文中。事件API，见第四章节；提交API，见第五章节。

所有事件的参数都是一个js对象，方便内部以JSON格式传递。

用户可以根据需求决定是否使用Channel。

通过如下js代码可以创建Channel:

GS.createChannel(groupName);

2.6样例代码

<!DOCTYPE html>
<html xmlns:gs="http://www.gensee.com/ec">
<head>
    <meta charset="utf-8"/>
    <title>Example Page</title>
    <script type="text/javascript" src="http://static.gensee.com/webcast/static/sdk/js/gssdk.js"></script>
    <link href="http://static.gensee.com/webcast/static/sdk/css/bootstrap.css" type="text/css" rel="stylesheet">
    <style type="text/css">
        .videoDiv {
            height: 400px;
        }
        .docDiv {
            height: 198px;
            padding: 1px;
        }
    </style>
    <script type="text/javascript">
        //1. 根据组获得通讯通道
        var channel = GS.createChannel();
        //2. 通过通道监听点名事件
        channel.bind("onRollcall", function (event) {
            alert(event.data.timeout);
        });
        //2. 通过通道监听问答事件
        channel.bind("onQA", function (event) {
            alert(event.data.question);
        });
        //3.通过通道提问，提问，私聊，公聊的提交可以设置回调函数，同时resultInfo的格式为//{result:true|false,data:data},data即为提交的数据
        channel.send("submitRollcall", {
            "id" : 23534677685687
        },function(resultInfo){
});
      // 4.通过通道提交点名信息
channel.send("submitQuestion", {
            "content" : "what's your name?"
        });
    </script>
</head>
<body>
<h2 align="center">Test Page</h2><br>
<div class="container">
    <div class="row-fluid">
        <div class="span6 videoDiv">
            <!-- Video Widget -->
            <gs:video-live site="www.gensee.com" ownerid="f8625298d18042fbbba7a8d4f75555ca"
                           authcode="333333" />
        </div>
        <div class="span6">
           <div class="docDiv">
                <!-- Doc Widget -->
                <gs:doc site="www.gensee.com" ownerid="f8625298d18042fbbba7a8d4f75555ca" />
            </div>
        </div>
    </div>
</div>
</body>
</html>

2.7 Widget加载错误提示

有时候，由于用户在使用widget时，填入了错误参数，会导致widget加载失败。以下罗列所有的失败提示：

param_error：必填参数未填写
login_fail：要求登录，登录失败
not_assign：直播未与该用户关联，该用户不能观看
auth_fail：口令错误或第三方认证失败
not_found：直播不存在
service_disabled：服务（直播，教育培训等）已禁止
required_client_join：要求使用客户端，web端不可用
ipad_not_support：当前不支持移动平台
api_disabled：SDK功能未开启

2.8 SDK调试工具

Gensee为每个客户(Site)均提供了独立的直播服务Web Player SDK调试页面，以辅助客户(Site)的开发人员调试直播服务SDK接口。

测试页面的URL规则如下：

http://{站点域名}/sdk/site/test/simple?ownerid={直播ID}&authcode={直播的普通参加者口令}

URL格式范例：

http://test.gensee.com/sdk/site/test/simple?ownerid=abcd&authcode=123456

工具截图

2.9 SDK演示效果

Gensee为每个客户(Site)均提供了独立的直播服务Web Player SDK演示页面入口：

http://{站点域名}/sdk/

如图：

页面下方有场景选择，如图：

点击演播厅场景，进入演示效果页面，如下图：

点击剧场场景，进入演示效果，如图：

2.10 手机iframe 嵌入原始链接测试工具

Gensee为每个客户(Site)均提供了独立的iframe嵌入原始链接调试页面，手机iframe下翻转会存在很多问题，尤其微信下，现提供解决方案，使用以下代码解决横竖屏问题

测试页面的URL规则如下：

http://{站点域名}/sdk/site/test/iframe? testUrl={原始访问链接 }

URL格式范例：

webcast： http://test.gensee.com/sdk/site/test/iframe?testUrl= http://test.gensee.com /webcast/site /entry/join-ea7825821b894a899ce509021cb3317d
training：http://test.gensee.com/sdk/site/test/iframe?testUrl= http://test.gensee.com /training /training/site/s/25100250

代码如下

<!doctype html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,minimum-scale=1.0,maximum-scale=1.0,user-scalable=no">
<script src=" jquery-2.1.4.min.js" type="text/javascript"></script>
<title>直播详情</title>
<style>
* {
         padding:0px;
         margin:0px;
}
html, body{
         width: 100%;
         height: 100%;
         border:0px;
         overflow:hidden;
}
</style>
</head>
<body>
<iframe name="ifm" id="ifm" src="http://192.168.1.106/webcast/site/entry/join-0e8d26fa83ec47fab0ace21e6bbc558d?nickName=oldold&token=111111" scrolling="yes" width="100%" height="100%" frameborder="0"></iframe>
<script type="text/javascript">
function f_load(){
         document.getElementById("ifm").height = window.innerHeight + "px";//高度(获取目标网页的高度自适应)
         document.getElementById("ifm").width = window.innerWidth + "px";//宽度(获取目标网页的宽度自适应)});
}
/*横竖屏*/
var gschi=0;//翻转屏hash数
function createOrientationChangeProxy(fn, scope) {  
    return function() { 
        clearTimeout(scope.orientationChangedTimeout); 
        var args = Array.prototype.slice.call(arguments, 0); 
        scope.orientationChangedTimeout = setTimeout($.proxy(function() { 
            var ori = window.orientation; 
            if (ori != scope.lastOrientation) { 
                fn.apply(scope, args); // 这里才是真正执行回调函数 
            } 
            scope.lastOrientation = ori; 
        }, scope), 200); 
    }; 
}
window.addEventListener("onorientationchange" in window ? "orientationchange" : "resize", createOrientationChangeProxy(function() { 
         setTimeout(function(){
                  //获取iframeurl
                   var src=$('#ifm').attr('src');
                   if(src.indexOf("#")){
                            var a=src.split("#"),
                            src=a[0];
                   }
                   //翻转数自增
                   gschi+=1;
                   //iframe加上hash重新传值src
                   $('#ifm').attr('src',src+'#gsorientationchange='+gschi);
                   f_load();
         },0);
}, window), false);
$(function(){
         f_load();
         setInterval(function(){
                   if($(window).scrollTop()!=0){
                            $(window).scrollTop(0);
                   }
         },100);
});
</script>
</body>
</html>

2.11 DEMO与源码

为了方便客户方开发人员快速实现页面播放器的开发，我们提供了完全基于SDK接口制作的网页DEMO播放器，并开放所有源码。

点击此处，下载DEMO播放器及源码

DEMO播放器包括4种：

PC端直播播放器
PC端点播播放器
移动端直播播放器
移动端点播播放器

DEMO源码的使用：

替换site="product.gensee.com"里的值为自己站点的域名
替换ownerid="qnYvtuDg1R"为当前直播的sdk id
如果设置密码请设置authcode=""的值为直播或点播密码

DEMO播放器功能：

DEMO播放器中包括大部分的直点播功能(并非全部)，如需DEMO未包括的功能，仍然需要开发人员阅读本文档中的接口说明自行开发。

以下为主要功能

直播播放器功能：

分类	功能说明
状态	直播标题直播状态
音视频	直播视频的显示桌面共享的显示插播视频的显示音量调节
文档	文档的显示标注的显示
聊天	支持公聊聊天的接收和发送支持表情
问答	显示发布的问答支持提问
投票	显示发布的投票显示发布的投票结果提交投票
点名	支持点名的响应支持签到
系统消息	显示广播消息
优选网络	支持切换CDN线路

点播播放器功能：

分类	功能说明
状态	标题
音视频	视频的显示桌面共享的显示插播视频的显示暂停/恢复音量调节
文档	文档的显示标注的显示
聊天	显示公聊记录
问答	显示问答记录
章节	显示序号、标题、时间支持快速定位
投票	显示发布的投票提交投票

3 监听事件API

注意：所有事件触发，将收到event对象。其中data属性即数据参数。本文档中均以json格式来表达数据参数

3.1 onUrlOpen -- 打开第三方投票地址

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone).

参数：

{
"url": "http://www.google.com"
}

参数	说明
url	第三方投票URL，同时支持协同浏览

3.2 onDocChange -- 文档翻页

参数：

{
"width": 800,
"height":600,
"ppt":[true|false],
"doc":"测试文档",
"title":"第一页"
}

参数	说明
width	页宽
height	页高
ppt	是否是ppt类型，移动平台上不支持（ipad,android 4.0以上,iphone）
doc	文档主题，移动平台上不支持（ipad,android 4.0以上,iphone）
title	页标题，移动平台上不支持（ipad,android 4.0以上,iphone）

3.3 onDataReady -- SDK加载完毕，所有API生效

参数：

{
“minInterval”:0
}

参数	说明
minInterval	聊天提问发言提交间隔，单位s，默认为0

3.4 onVideoConfig -- 视频配置更改通知

参数：

{
"hasVideo":[true|false],
"width":320,
"height":240,
"type":["video"|"share"]
}

参数	说明
hasVideo	是否有视频数据, true 或者 false
width	流宽度
height	流高度
type	video – 当前Video Widget显示视频流； share start – Video Widget显示共享流; share stop – Video Widget 停止显示共享流

3.5 onQA -- 收到问答消息

参数：

{
    "id": "abcd-efg-hi",
    "question": "how are you?",
    "submitor": "Tom",
    "answer": "fine, thank you.",
    "answerBy": "Jack",
    "submitTime": 9654123000,
"answerTime": 8795623000
"qaownerId": 8735466234
}

参数	说明
id	问答UUID
question	问题
submitor	提问者名称
answer	回复
answerBy	回复者名称
submitTime	提问时间，单位毫秒
answerTime	回复时间，单位毫秒
qaownerId	提问者ID

3.6 onQARemove -- 清除某条问答

参数：

{
    "id": "abcd-efg-hi",
}

参数	说明
id	问答UUID

3.7 onQAList -- 收到问答历史记录

参数：

{ 
"list": [
{
"id": "abcd-efg-hi",
"question": "how are you?",
"submitor": "Tom",
"answer": "fine, thank you.",
"answerBy": "Jack",
"submitTime": 9654123,
"answerTime": 8795623
"qaownerId": 8735466234
},
{
"id": "abcd-efg-hi",
"question": "how are you?",
"submitor": "Tom",
"answer": "fine, thank you.",
"answerBy": "Jack",
"submitTime": 9654123,
"answerTime": 8795623
"qaownerId": 8735462542
}
]
}

参数	说明
list	问答列表，列表中每个对象都是问答对象。问答对象参数说明见onQA

3.8 onSetting -- 功能配置更改通知

参数：

{
" enable":[true | false],
" target":["all" | "self"],
"option":["question" | "onlineuser" | "userlist" | "chat" | "multistream"]
}

参数	说明
enable	true说明启用 false 说明禁用
target	all – 对全体生效 self – 仅对自己生效
option	question 提问 onlineuser显示在线人数 userlist 用户列表 chat 聊天 multistream 移动端多码流

3.9 onMessage -- 收到系统消息

参数：

{
"content":"通知。。。。"
"time":"8795623000”
}

参数	说明
content	系统消息内容
time	系统消息发出的时间（秒）（该属性在移动端暂不支持）

3.10onKickOut -- 被踢出

参数：

{
"reason":[0|1]
}

参数	说明
reason	0-被会议组织者踢出；1-其他情况

3.11 onRollcall -- 收到点名通知

参数：

{
"timeout":15
"id":23534677685687
}

参数	说明
id	点名ID
timeout	超时时间，单位秒

3.12 onTextWebcast -- 文字直播

参数：

{
"time":123456,
"lang":"zh_CN",
“content”:”hi…”
}

参数	说明
time	文字提交的时间，单位毫秒
content	文字直播内容
lang	语言

3.13 onFile -- 文件下载

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

{
"name":"1.txt",
"url":"http://www.test.com/1.txt",
"action":["add"|"remove"]
}

参数	说明
name	文件名
url	文件下载URL
action	add新增文件下载点 remove 删除文件下载点

3.14onLottery -- 抽奖

参数：

{
"action":["start"|"stop"|"abort"],
"user":"Tom"
}

参数

说明

action

start 开始抽奖

stop 抽奖结束

abort 抽奖中途终止

user

当抽奖结束时候，告诉中奖用户名称

3.15 onUserList -- 用户列表

参数：

{
"list": [
{"id":1,"name":"Tom","chatid":1,"role":"1,2"},
{"id":2,"name":"Jason","chatid":2,"role":"4"}
]
}

参数	说明
list	用户列表
id	用户ID
name	用户名称
chatid	仅用于聊天列表的聊天ID
role	用户角色以组合的形式出现，可能是单个角色，可能是多个角色，多个角色用逗号分隔，角色对应含义如下：组织者 = 1 主讲 = 2 嘉宾 = 4 普通参加者 = 8 Web参加者 = 16

3.16onUserJoin -- 用户加入

参数：

{
"list": [
{"id":1,"name":"Tom","chatid":1,"role":"1"},
{"id":2,"name":"Jason","chatid":2,"role":"4"}
]
}

参数	说明
list	用户列表
id	用户ID
name	用户名称
chatid	仅用于聊天列表的聊天ID
role	用户角色以组合的形式出现，可能是单个角色，可能是多个角色，多个角色用逗号分隔，角色对应含义如下：组织者 = 1 主讲 = 2 嘉宾 = 4 普通参加者 = 8 Web参加者 = 16

3.17onUserLeave -- 用户离开

参数：

{
"list": [
{"id":1,"name":"Tom","chatid":1,"role":"1"},
{"id":2,"name":"Jason","chatid":2,"role":"4"}
]
}

参数	说明
list	用户列表
id	用户ID
name	用户名称
chatid	仅用于聊天列表的聊天ID
senderRole	用户角色以组合的形式出现，可能是单个角色，可能是多个角色，多个角色用逗号分隔，角色对应含义如下：组织者 = 1 主讲 = 2 嘉宾 = 4 普通参加者 = 8 Web参加者 = 16

3.18 onUserUpdate -- 用户信息更改

参数：

{
"list": [
{"id":1,"name":"Tom","chatid":1,"role":"1"},
{"id":2,"name":"Jason","chatid":2,"role":"4"}
]
}

参数	说明
list	用户列表
id	用户ID
name	用户名称
chatid	仅用于聊天列表的聊天ID
role	用户角色以组合的形式出现，可能是单个角色，可能是多个角色，多个角色用逗号分隔，角色对应含义如下：组织者 = 1 主讲 = 2 嘉宾 = 4 普通参加者 = 8 Web参加者 = 16

3.19 onUserOnline -- 用户在线人数

参数：

{
 "count":500
}

参数	说明
count	当前并发数（非实时数据）

3.20 onStart -- 直播开启通知

参数：

{

}

参数	说明

3.21 onPause -- 直播暂停通知

参数：

{

}

参数	说明

3.22 onPlay -- 直播恢复通知

参数：

{

}

参数	说明

3.23 onStop -- 直播停止通知

参数：

{

}

参数	说明

3.24 onVote -- 收到调查问卷

参数：

{
    "id": "abcd-efg-hi",
    "skip": [true|false],
    "subject": "test vote",
    "questions": [
        {
            "id": "uuid",
            "subject": "first question",
            "type": ["single"|"multi"|"text"],
            "answer": "1,3",
               "text":””,
               "score":"5",
            "items": [
                {
                    "id": "uuid",
                    "correct": [true|false],
                    "option": "answer1",
               "selected":false
                },
                {
                    "id": "uuid",
                    "correct": [true|false],
                    "option": "answer2",
                "selected”:false
                }
            ]
        }
}

参数	说明
id	投票ID; 问题ID；选项（答案）ID
skip	false表明是强制投票
subject	投票主题；问题
questions	问题列表
type	single 单选题 multi 多选题 text 文字题
answer	Single或者multi类型时候，表明哪些选项是正确答案。多选时候，用数组表达。
text	默认为空。预留给submitVote这个API使用
items	选项（答案）列表
option	选项（答案）
correct	是否为正确答案，与answer属性作用相同
selected	默认为false。表明用户没有选择该项。预留给submitVote这个API使用。
score	分数

3.25 onVoteResult -- 发布调查结果

参数：

{
    "id": "abcd-efg-hi",
    "total": 2,
    "subject": "test vote",
    "question": [
        {
            "id": "uuid",
            "subject": "first question",
            "type": "single",
            "total": 2,
            "items": [
                {
                    "id": "uuid",
                    "total": 1,
                    "option": "answer1",
                },
                {
                    "id": "uuid",
                    "total": 1,
                    "option": "answer2"
                }
            ]
        }
    ]
}

参数	说明
id	参考onVote接口
total	投票人数

3.26 onAnswerSheet - 收到答题卡

参数：

{
      "id": "abcd-efg-hi",
      "skip": ["true"|"false"],
      "questions": [{
                         "id": "uuid",
                         "type": ["single"|"multi"],
                         "items": [{
                                  "id": "uuid",
                                  "option": "answer1",
                                  "selected":"false"
                                  },
                                  {
                                  "id": "uuid",
                                  "option": "answer2",
                                  "selected":"false"
                                  }]
               }]
}

参数	说明
id	答题卡ID; 问题ID；选项（答案）ID
skip	false表明是强制操作
questions	问题列表
type	single 单选题 multi 多选题
items	选项（答案）列表
option	选项（答案）
selected	选项是否选中

3.27 onAnswerSheetAnswer - 发布答题卡答案

参数：

{
      "id": "abcd-efg-hi",
      "questions": [{
                         "id": "uuid",
                         "type": ["single"|"multi"],
                         "total":"100",
                         "items": [{
                                  "id": "uuid",
                                  "total":"20",
                                  "correct":["true"|"false"],
                                  "option": "answer1",
                                  },
                                  {
                                  "id": "uuid",
                                  "total":"20",
                                  "correct":["true"|"false"],
                                  "option": "answer2",
                                  }]
               }]
}

参数	说明
id	答题卡答案ID; 问题ID；选项（答案）ID
questions	问题列表
type	single 单选题 multi 多选题
total	100 该题目分数；该选项分数
items	选项（答案）列表
option	选项（答案）
correct	是否为正确答案

3.28 onModuleFocus -- web端布局改变通知

参数：

{
"focus":[0 | 1 | 2 | 3]
}

参数

说明

focus

0 -- 文档为主 ;

1 -- 视频最大化;

2 -- 文档最大化;

3 -- 视频为主

3.29 onUpgradeRequired – 收到邀请：web端升级到客户端

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

3.30 onSubmitUpgrade -- 同意升级

事件说明：当用户同意升级（调用submitUpgrade，且值为agree之后），SDK通知用户web端升级到客户端的URL地址。

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

{
      url: “http://www.gensee.com/webcast/site/event/client?upgrade=true”
}

参数	说明
url	升级到学生客户端的URL

3.31 onStatus -- SDK状态通知

参数：

{
"type":[1 | 2 | 3 | 4 | 5] ,
"explain":”license not enough”
}

参数

说明

type

类型

1 - License不足；

2 - 直播未开始；

3 – 缓冲状态

4 – 服务器拒绝，加入失败

5 – 连接服务器中

6 – 加入失败，该用户已用客户端形式登陆

7 – 直播上锁，拒绝加入

8 – 该用户已被封，加入失败

9 - 视频第一次缓冲播放开始（只支持移动端）

explain

说明

3.32 onAPIError -- API错误通知

参数：

{
"api":"submitQuestion",
"param":{……},
“explain”:”format error”,
“type”:1
}

参数	说明
api	API名称
param	API所提交的原始参数
explain	说明
type	错误类型 0 – API名称错误 1 – 参数校验错误； 2 – 必填项缺失；

3.33 onPublicChat – 收到公聊消息

参数：

{
"sender":"vincent",
"senderId":2,
"senderUid":3467734,
“content”:”hi, how are you”,
“richtext”:”…..”,
"sendRole":"1,2"
“utctime”:”1595838886”
}

参数	说明
sender	发送者名称
senderId	发送者聊天ID
senderUid	发送者用户ID
content	聊天内容
richtext	聊天内容带有富文本内容（满足HTML格式）
senderRole	用户角色以组合的形式出现，可能是单个角色，可能是多个角色，多个角色用逗号分隔，角色对应含义如下：组织者 = 1 主讲 = 2 嘉宾 = 4 普通参加者 = 8 Web参加者 = 为空
utctime	聊天的服务器时间戳（秒）

3.34 onPriChat – 收到私聊消息

参数：

{
"sender":"vincent",
"senderId":2,
"senderUid":3467734,
“content”:”hi, how are you”,
“richtext”:”…..,
"sendRole":"4"
“utctime”:”1595838886”
}

参数	说明
sender	发送者名称
senderId	发送者聊天ID
senderUid	发送者用户ID
content	聊天内容
richtext	聊天内容带有富文本内容（满足HTML格式）
senderRole	用户角色以组合的形式出现，可能是单个角色，可能是多个角色，多个角色用逗号分隔，角色对应含义如下：组织者 = 1 主讲 = 2 嘉宾 = 4 普通参加者 = 8 Web参加者 = 为空
utctime	聊天的服务器时间戳（秒）

3.35 onWebAudioInvite -- （仅邀请对象）收到Web语音邀请

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

{
"inviter ":" vincent "
}

参数	说明
inviter	邀请人的用户名

3.36 onWebAudioClose –（仅邀请对象）收到Web语音结束通知

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

3.37 onWebVoiceInfo – （所有人）收到Web语音状态通知

事件说明：web语音状态

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

{
"uid":"xxxxx",
"uname":"xxxxxx ",
"status":"[invite|start|stop]
}

参数	说明
uid	进行web语音的web端用户id
uname	进行web语音的web端用户名字
status	当前web语言的状态

3.38 onNetStatus -- 收到网络状态信息

参数：

{
      "level ":[0|1|2|3]
}

参数	说明
level	0良好 1预警 2异常 3数据堆积

3.39 onNetSettings -- 获取优选网络信息

事件说明：优选网络信息, 是requireNetSettings请求的回调事件

参数：

{
      "list":[
{
  "label":"浙江电信",
"selected":"[true|false]",
}]
}

参数	说明
label	可选网络内容
selected	当前已选中网络

3.40 onQAHighlight -- 当前正在被语音回复的某问题

参数：

{
"id":"354-475685-23543",
}

参数	说明
id	当前正在被语音回复的问题ID

3.41 onCancelHighlight -- 该问题已经语音回复结束

参数：

{
"id":"354-475685-23543",
}

参数	说明
id	已经语音回复结束的问题ID

3.42 onTagAudio -- 该问题已经进入语音回复列表

参数：

{
"id":"354-475685-23543",
}

参数	说明
id	已经进入语音回复列表的问题ID

3.43 onMute -- 在web语音开启或关闭时自动改变直播静音状态

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

{
"mute":"[true|false]",
}

参数	说明
mute	该属性主要用于外部自定义控制条状态的同步

3.44 onVideoShow -- 直播视频是否开启的状态通知

参数：

{
"show":"[true|false]",
}

参数	说明
show	当前是否开启视频

3.45 onThirdPartChat – 收到第三方聊天消息

参数：

{
"sender":"vincent",
“content”:”hi, how are you”,
“richtext”:”…..”,
}

参数	说明
sender	发送者名称
content	聊天内容
richtext	聊天内容带有富文本内容（满足HTML格式）

3.46 onLiveDemandStart– 收到插播状态

事件说明：插播是否开启的状态

参数：

{
"show":"[true|false]"
}

参数	说明
show	当前是否开启插播

3.47 onRoleStatus– 收到用户角色变化通知

事件说明：用户角色变化通知

参数：

{
"hostid":"xxxx",
"hostname":"xxxx",
"presid":"xxxx",
"presname":"xxxx",
}

参数	说明
hostid	组织者id
hostname	组织者用户名
presid	主讲人id
presname	主讲人用户名

3.48 onDoubleClick – 收到用户双击组件事件

事件说明：用户双击特定组件

参数：

{
"widgetId":" _GS_WIDGET_2_1449813529475"
"widgetType":"vp|pd"
}

参数	说明
widgetId	双击组件的widgetId
widgetType	双击组件的类型vp:播放器 pd:文档

3.49 onHongbaoInfo - 收到红包信息

事件说明：红包消息通知

参数：

{
      "hbid ": "string",
      "username": "string",
      "sum":100
      "type":[0|1|2]
     "comment": "string",
 }

参数	说明
hbid	红包ID
username	红包发起者昵称
sum	红包总金额
type	红包类型 0.随机红包 1.定额红包 2定向红包（需要抢） 3定向红包（自动抢）
comment	红包留言

3.50 onGetHongbaoGrabInfo – 红包争抢情况列表

事件说明：抢得红包的用户和金额列表与getHongbaoGrabInfo 接口搭配使用

参数：

{
      "status":[0|-1|-2],
      "username":"string",
      "comment":"string",
      "list": [{
             "amount": 0,
             "time": 0,
             "best": true,
             "username": "string"
     }]
}

参数	说明
status	状态 0:接口正常 -1:红包功能未开启 -2:网络异常
username	发红包用户昵称
comment	红包留言
list	红包争抢情况列表
amount	抢得红包金额
time	抢得红包时间
best	是否手气最佳
username	抢得红包用户的用户昵称

3.51 onGetUserGrabInfo – 用户在直播中抢得红包列表

事件说明：用户在直播中抢得的红包列表与 getUserGrabInfo 接口搭配使用

参数：

{
      "status":[0|-1|-2]
      "sum":58,
      "count":5,
      "bests":2,
      "list":[ {
                         "amount": 0,
                         "time": 0,
                         "susername": "string",
               }]
}

参数	说明
status	状态 0:接口正常 -1:红包功能未开启 -2:网络异常
sum	红包总金额
count	红包个数
bests	手气最佳次数
list	红包数据列表
amount	抢得红包金额
time	抢得红包时间
susername	红包发起者昵称

3.52 onGrabHongbao – 争抢红包结果

事件说明：争抢红包结果与 grabHongbao 接口搭配使用

成功参数：

{
      "hbid":"string"
      "status":[0|-1|-2|-3]
      "amount":100
      "code":"10104"
      "msg":"重复争抢"
}

参数	说明
hbid	红包ID
status	状态 0:接口正常 -1:红包功能未启用 -2:网络异常 -3:红包争抢失败
amount	抢得的红包金额
code	异常代码
msg	争抢失败消息 10104：重复争抢，10105：红包已空，10106：红包超时，10107：定向红包，不允许争抢

3.53 onCloseHongbao – 关闭红包争抢页面

事件说明：发生异常情况时关闭红包争抢页面，避免导致数据异常

参数：

{
      "code":"10100"
      "msg":"用户离开直播室"
}

3.54 onGrabHongbaoMsg – 争抢红包消息

事件说明：争抢红包消息推送

成功参数：

{
      "hbid":"string",
      "amount":100
      "username":"string"
      "type":"[0|1]"
}

参数	说明
hbid	红包ID
amount	抢得的红包金额
username	抢得红包用户的用户昵称
type	0非定向红包 1定向红包

3.55 onRewardResponse – 打赏订单响应

事件说明：打赏订单响应与 submitReward 接口搭配使用

成功参数：

{
      " returnCode": [0|-1|-2|-3],
      " returnMsg":"live not start."
      " codeUrl":"weixin://wxpay/bizpayurl?pr=8oWfCsK"
      " userId":9960407372
      " amount":1
      " payType":0
}

参数	说明
returnCode	0 订单生成成功 -1 网络异常，数据提交失败 -2 直播未开始，无法打赏 -3 打赏金额异常应为正整数 -4 未开通服务其他非0 数值都是不同错误
returnMsg	状态描述
codeUrl	PC web：微信订单链接地址使用qrcode处理生成二维码支付宝支付二维码地址移动web：会自动跳转
userId	用户id 参数回传
amount	打赏金额参数回传
payType	支付类型 0 微信 1支付宝

3.56 onRewardMessage – 打赏通知

事件说明：打赏消息推送

成功参数：

{
      " id":"1025122"
      " userid":"9960407372"
      " username":"userName"
      " amount":0.01
}

参数	说明
id	打赏操作id
userid	打赏用户id
username	打赏用户昵称
amount	打赏金额

3.57 onDownloadSpeed - 下行速率通知

事件说明：网络下行速率信息，与submitSpeedReport接口搭配使用，本接口不支持移动端

成功参数：

{
      " speed":"218.15"
}

参数	说明
speed	单位kbps，精确到小数点后2位.

3.58 onChatRemove - 聊天移除

事件说明：删除特定聊天数据

成功参数：

{

"censorList":[{

"type":"user|chat",

"id":"123456",

}，{

"type":"user|chat",

"id":"123456",

}]

}

参数	说明
censorList	审核删除的聊天数据列表
type	删除聊天类型 user该用户的聊天消息 chat单条聊天消息
id	删除消息id 根据type类型来确定用户id 或者聊天消息id

3.59 onPraiseMessage- 收到点赞消息

事件说明：点赞消息通知

参数：

{

"rc": 0,

"response": {

"remain": 99710

}

参数	说明
rc	该参数等于0时为成功，否则失败

3.60 onUpdatePraiseTotalSuccess- 收到点赞剩余可点赞数量

事件说明：点赞消息通知

参数：

{

"rc": 0,

"response": {

"remain": 99710

}

参数	说明
remain	当前用户剩余点赞数量
rc	该参数等于0时为成功，否则失败

3.61 onMobileStatus- 收到登陆用户手机绑定状态

事件说明：需用户登陆状态下，手机的绑定状态（在截止日期后必须绑定手机，否则无法登陆）

参数：

{

"code": “mobile_not_bind”,

}

参数	说明
code	值为mobile_not_bind 当前未绑定手机

4 提交数据API

4.1 submitQuestion -- 提问

注意：如果两个问题的提交有设置间隔时间，那么在间隔内提交问题不会成功的。同时如果提交问题有设置回调函数那么会调用回调函数。

参数：

{
"content":"what's your name?"
}

参数	说明
content	问题内容

4.2 submitVote -- 提交调查问卷结果

参数：

提交对象格式同onVote接口，请参看onVote接口的参数说明

{
    "id": "abcd-efg-hi",
    "skip": [true|false],
    "subject": "test vote",
    "questions": [
        {
            "id": "uuid",
            "subject": "first question",
            "type": ["single"|"multi"|"text"],
            "answer": "1,3",
               "text":””
            "items": [
                {
                    "id": "uuid",
                    "correct": "[true|false]",
                    "option": "answer1",
                          "selected" : "[true|false]"
                },
                {
                    "id": "uuid",
                    "correct":"[true|false]",
                    "option": "answer2",
                                      "selected" : "[true|false]"
                }
            ]
        }
    ]
}

4.3 submitAnswerSheet - 提交答题卡测试结果

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

提交对象格式同onAnswerSheet接口，请参看onAnswerSheet接口的参数说明

{
      "id": "abcd-efg-hi",
      "skip": ["true"|"false"],
      "questions": [{
                         "id": "uuid",
                         "type": ["single"|"multi"],
                         "items": [{
                                  "id": "uuid",
                                  "option": "answer1",
                                  "selected":["false"|"true"]
                                  },
                                  {
                                  "id": "uuid",
                                  "option": "answer2",
                                  "selected":["false"|"true"]
                                  }]
               }]
}

4.4 applyUpgrade -- 对客户端发起web端升级申请

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

{
"apply" : [true | false]
}

参数

说明

apply

true – 申请升级

false – 取消升级

4.5 submitUpgrade -- 对客户端邀请web端升级的反馈

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

{
"agree" : [true | false]
}

参数

说明

agree

true - 同意

false – 不同意

4.6 submitHandup -- 提交举手数据

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

{
"handup" : [true | false]
}

参数	说明
handup	Web发起举手功能。

4.7 submitRollcall -- 提交点名，说明该用户出席。

参数：

{
"id":23534677685687
}

参数	说明
id	点名ID。

4.8 submitChat -- 提交公聊信息

注意：content与richtext至少提交其中之一，若同时提交content和richtext时，以richtext为准。

如果两个公聊信息的提交有设置间隔时间，那么在间隔内提交公聊信息不会成功的，同时如果提交公聊信息有设置回调函数那么会调用回调函数。

（提议：以input、textarea作为聊天信息输入的，使用content属性提交信息，以div[contenteditable] 作为聊天信息输入的，使用richtext属性提交信息）

参数：

{
"content":"hello",
"richtext":"……",
"security":"[default|high]"
}

参数	说明
content	聊天内容
richtext	聊天内容允许带有表情图标。表情图标参考6.3
security	设置聊天内容的安全等级权限，default是原有的较低的安全等级模式，high为新增较高安全等级模式，缺省该属性默认为default安全等级

4.9 submitChatTo -- 提交私聊信息

注意：content与richtext至少提交其中之一，若同时提交content和richtext时，以richtext为准。

如果两个私聊信息的提交有设置间隔时间，那么在间隔内提交私聊信息不会成功的，同时如果提交私聊信息有设置回调函数那么会调用回调函数。

（提议：以input、textarea作为聊天信息输入的，使用content属性提交信息，以div[contenteditable] 作为聊天信息输入的，使用richtext属性提交信息）

参数：

{
"content":"hello",
"richtext":"hello",
"receiverId":2,
"receiver":"tom wang",
"security":"[default|high]"
}

参数	说明
content	聊天内容
richtext	聊天内容允许带有表情图标。表情图标参考6.3
receiver	接收者名称，可选参数
receiverId	接收者聊天ID，必填参数
security	设置聊天内容的安全等级权限，default是原有的较低的安全等级模式，high为新增较高安全等级模式。缺省该属性默认为default安全等级

4.10 submitMute -- 提交静音信息

注意：该api只在不采用默认控制条的前提下生效

在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

{
"mute": [true | false]
}

参数	说明
mute	是否设置为静音。

4.11 submitVolume -- 提交音量信息

注意：该api只在不采用默认控制条的前提下生效

在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

{
"value": 0.75
}

参数	说明
value	该值在0~1范围内有效

4.12 submitOpenVideo -- 提交是否打开画面信息

事件说明：只在RTMP流中支持。

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

参数：

{
"openvideo": [true|false]
}

参数	说明
openvideo	是否设置为打开视频（默认打开）

4.13 requireNetSettings -- 请求优选网络信息

参数：

{

}

参数	说明

4.14 submitNetChoice -- 提交优选网络选择信息

参数：

{

"label": "广州电信"

}

参数	说明
label	内容参考onNetSettings参数

4.15 submitNetChoice -- 提交优选网络选择信息

参数：

{
"label": "广州电信"
}

参数	说明
label	内容参考onNetSettings参数

4.16 submitStop -- 通过接口直接结束现有直播的观看

备注：在移动平台上不支持该接口(ipad,android 4.0以上,iphone)

4.17 submitUsername -- 通过接口修改用户显示的名称

参数：

{
  "name": "vincent"
}

注意：name是不允许输入<,>,,/,”,’这些字符的，如果有会自动过滤。

参数	说明
name	输入要修改的用户名。如为空字符会修改失败，保持原有的用户名

4.18 submitShowVideoCover -- 通过接口修改是否显示视频遮盖图片。

参数：

{
"show": "[true|false]"
}

参数	说明
show	true-显示视频遮盖图片，false-隐藏视频遮盖图片

4.19 getHongbaoGrabInfo – 查询红包的争抢情况

参数：

{
"hbid": "1234567890"
}

参数	说明
hbid	红包ID

4.20 grabHongbao -- 争抢红包

参数：

{
"hbid": "1234567890"
}

参数	说明
hbid	红包ID

4.21 submitReward - 提交打赏订单

事件说明：

参数：

{
"amount": 1,
"payType": 0
}

参数	说明
amount	打赏金额精确到1分，单位分
payType	支付类型微信支付 0 支付宝1
refer(移动端使用)	移动端支付成功后跳转地址

4.22 submitSpeedReport - 开启下行速率通知接口

事件说明：该接口不支持移动端

参数：

{
"open":"true"|"false",
}

参数	说明
open	true 开启，false 关闭

4.23 submitFaultReport -提交故障报告

事件说明：用户主动提交故障报告

参数：

{

}

参数	说明

5 移动端专用API

5.1 submitPlay -- 通过接口播放视频

备注：移动设备上的第一次播放不支持该功能

原因详见：https://developer.apple.com/library/safari/documentation/AudioVideo/Conceptual/Using_HTML5_Audio_Video/Device-SpecificConsiderations/Device-SpecificConsiderations.html#//apple_ref/doc/uid/TP40009523-CH5-SW4

5.2 submitPause -- 通过接口暂停视频

备注：

参数：

{

}

5.3 submitStream – 选择码流

备注：在多码流间切换。仅当移动端开启多码流功能情况下该接口生效。是否支持多码流参见 4.8 onSetting 接口说明。

参数：

{
"level": [0 | 1]
}

参数	说明
level	码流。0 – 标清，1 – 原始

6 可扩展实时数据调用

以下所有事件触发，必须要在video widget初始化时定义参数completed，并写上回调函数名称，那么在实时数据被触发时，并且直播不开始不会触发liveDuration这个功能，函数会收到相应数据。现有的实时数据如下所示：

6.1 LiveDuration – 进入直播时，直播已持续的时间

参数：

{
"type": "LiveDuration",
"starttime": "20"
}

参数	说明
type	该参数的属性
starttime	进入直播时，直播已持续的时间

7 补充说明

7.1 由于SDK本身技术的局限性，当前有些功能，该SDK不提供

双流
当video widget不显示控制栏时候，全屏功能不提供

7.2 中文编码问题

考虑到网页中文乱码问题，基于目前国际标准，建议客户的网页以UTF-8编码

如果网页不是UTF-8编码，调用API传中文时候，请使用encodeURIComponent()函数对中文进行预处理。

参考：

http://www.w3schools.com/jsref/jsref_encodeURIComponent.asp

7.3 关于聊天功能的表情图标

http://static.gensee.com/webcast/static/emotion/icon.json

在聊天功能中，提供富文本内容支持。

其中表情图标的URL见以上json格式中数据。

URL规则：prefix + url

Type说明：1 – 心情, 2 – 反馈, 3 – 礼物