移动端点播SDK

1文档介绍

1.1文档目的

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

1.2术语与缩写解释

编号	术语	解释
	SDK	Software Development Kit
	Widget	部件，能展现特定功能的html片段。目前仅提供视频部件和文档部件
	Webcast服务	Gensee提供的直播服务，见http://www.gensee.com/live.html
	Training服务	Gensee提供的教育培训服务，见http://www.gensee.com/education-training.html

2SDK使用介绍

2.1需要引入的javascript

注意：如果直接引用，在sdk内容更新时可能存在未下载最新sdk而使用浏览器中缓存的版本，在用户不清空缓存时会存在代码不一致导致异常的报错。建议对sdk添加时间戳，保证gssdk-1.3.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-1.3.js©v=" + Date.now() + "'><\/script>");
</script>

2.2Html命名空间

2.3Vod Video Widget （必选）

注意：一场点播在一个页面上请保证只有一个Vod Video Widget！

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

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

属性说明：

Id: html的元素ID。（可选）用户可自行指定。SDK将以此ID作为Widget ID。
ctx: 服务选项。可选值为webcast或training。无此属性说明默认使用webcast服务。
site: 站点域名 （必填）Example:www.gensee.com
ownerid: webcast服务下，表示点播ID ；training服务下，表示课件ID（必填）
uid: 用户ID （可选）。若无此属性，系统会自动生成随机UID。为了避免uid跟Gensee系统的内部用户ID冲突，该uid要求必须大于1000000000 小于9007199254740992
uname: 用户名称（可选）。若无此属性，系统自动生成英文随机名称。若点播（课件）要求登录，则用户名称必须是系统的登录账号。注：登录方式无论是账号密码或手机动态密码，接口只能使用账户登录。
authcode: （可选）校验码。对应点播（课件）的web端口令。若点播（课件）要求输入口令，则此属性必填。否则不需要。
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。
bgimg: 设置背景图案，图片URL地址。
py: 设置点播是否自动播放，值为1或者0。1表示自动播放，0则表示手动播放（移动端该参数是否生效取决于终端浏览器是否兼容）
video:设置点播是否使用音频还是视频，值为：true或者false，true表示视频，false表示音频，默认情况true。
btnimg:设置播放按钮图案，图片url地址。
fullscreen:是否在flash视频界面上显示全屏操作按钮。可选值为true或者false。默认值为false。（可选）
gsver：采用何种技术的播放器（H5 Flash）。可选值为2或者其他。默认值为空
post k值认证方式，get请求或post请求。可选值为true或者false。默认值为true。（可选）

2.4Doc Widget（可选）

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

<gs:doc id="docComponent" ctx="webcast" 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地址。
gsver：采用何种技术的文档模块（SDK1.0/SDK2.0）。可选值为2或者其他。默认值为空

2.5Channel (可选)

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

通讯分两种形式：

监听事件
提交数据

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

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

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

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

GS.createChannel(groupName);

2.6样例代码

<!DOCTYPE html>

<head>

<title>Example Page</title>

.videoDiv {

height: 400px;

}

.docDiv {

height: 198px;

padding: 1px;

}

</style>

//1. 根据组获得通讯通道

var channel = GS.createChannel("testgroup");

//2. 通过通道监听互动调查事件

channel.bind("onVote", function (event) {

alert(event.data);

});

//2. 通过通道监听问答事件

channel.bind("onQA", function (event) {

alert(event.data.question);

});

//3.通过通道留言

channel.send("submitLeaveMessage", {

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

});

</script>

</head>

<body>

<gs:video-vod site="www.gensee.com" ownerid="f8625298d18042fbbba7a8d4f75555ca"

uid="55831" uname="user5623" authcode="333333" group="testgroup"/>

</div>

<gs:doc site="www.gensee.com" ownerid="f8625298d18042fbbba7a8d4f75555ca" group="testgroup"/>

</div>

</body>

</html>

2.7Widget加载错误提示

有时候，由于用户在使用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调试工具

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

测试页面的URL规则如下：

http://{站点域名}/sdk/site/test/vod?ownerid={点播ID}&authcode={观看口令}&ctx={可选值为webcast或training。无此属性说明默认使用webcast服务}&gsver={可选值为2或者其他。无此属性说明默认使用SDK1.0版本}

URL格式范例：

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

工具截图

2.9手机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/vod/play-676cba5152f64bb29ebc8908e72f64c1
training：http://test.gensee.com/sdk/site/test/iframe?testUrl=http://test.gensee.com/training /training/site/v/25100250

代码如下注意红色字体

<!doctype html>

<html>

<head>

<style>

* {

padding:0px;

margin:0px;

}

html, body{

width: 100%;

height: 100%;

border:0px;

overflow:hidden;

}

</style>

</head>

<body>

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>

3监听事件API

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

3.1onDocChange

事件说明：文档翻页

参数：

{

"width" : 800,

"height" : 600,

"ppt" : [true|false],

"doc" : "测试文档",

"title" : "第一页",

"timestamp" : 200

}

参数	说明
width	页宽
height	页高
ppt	是否是ppt类型
doc	文档主题
title	页标题
timestamp	事件触发时间（毫秒）该属性移动平台暂时没有

3.2onChapter

事件说明：章节信息

参数：

{list:[{

“titile” : ”第一页”,

“doc” : ”测试文档”,

“starttimestamp” : 20242,

“stoptimestamp” : 100215,

"img" : "http://static.gensee.com/webcast/sdk/.......png"

}

]}

参数	说明
doc	文档主题
title	页标题
starttimestamp	开始播放时间单位为毫秒
stoptimestamp	结束播放时间单位为毫秒
img	文档图片地址

3.3onDataReady

事件说明：SDK加载完毕，所有API生效。同时通知第三方开发人员某些功能模块的配置项初始值。

参数：

{

"supportChatSync" : [ true | false ]

}

参数	说明
supportChatSync	该点播是否支持公聊数据的同步播放功能。 true – 支持 false – 不支持

3.4onQAList

事件说明：监听事件，初始化后并不会马上返回任何数据。只有当提交submitQAList后，监听事件才会收到聊天数据，默认200条。如果需要加载更多记录，请参考more参数用法。

参数：

{

"more" : true,

"list" : [

{

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

"question" : "how are you?",

"submitor" : "Tom",

"answer" : "fine, thank you.",

"answerBy" : "Jack",

"submitTime" : 9654123,

"answerTime" : 8795623,

"submitorId" : "111111",

"answererId" : "22222"

{

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

"question" : "how are you?",

"submitor" : "Tom",

"answer" : "fine, thank you.",

"answerBy" : "Jack",

"submitTime" : 9654123,

"answerTime" : 8795623,

"submitorId" : "111111",

"answererId" : "22222"

}

]

}

参数	说明
list	问答列表，列表中每个对象都是问答对象。
id	问答UUID
question	问题
submitor	提问者名称
answer	回复
answerBy	回复者名称
submitTime	提问时间，单位毫秒
answerTime	回复时间，单位毫秒
submitorId	提问者用户ID
answererId	回答者用户ID
more	false – 说明后续没有Q&A数据 true – 说明后续还有Q&A数据，可以再次调用submitQAList以获取下一批200条聊天数据。

3.5onTextWebcast

事件说明：文字直播历史记录

参数：

{

list : [

{

time : 126152,

content : "content",

lang : "zh_cn"

}

]

}

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

3.6onLottery

事件说明：抽奖

参数：

{

"action" : ["start"|"stop"|"abort"],

"user" : "Tom"

}

参数

说明

action

start 开始抽奖

stop 抽奖结束

abort 抽奖中途终止

user

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

3.7onModuleFocus

事件说明：web端布局控制

参数：

{

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

}

参数

说明

focus

0 -- 文档为主 ;

1 -- 视频最大化;

2 -- 文档最大化;

3 -- 视频为主

3.8loadStart

事件说明：初始化点播，点播开始

参数：

{

}

参数	说明

3.9onPause

事件说明：提交pause请求后的异步回调事件

参数：

{

"timestamp" : 200

}

参数	说明
timestamp	暂停时候的时间点，单位毫秒

3.10onPlay

事件说明：视频进入播放状态触发该事件

参数：

{

"timestamp" : 200

}

参数	说明
timestamp	点播恢复时候的时间点，单位毫秒。

3.11onStop

事件说明：播放结束

参数：

{

}

参数	说明

3.12onSeekCompleted

事件说明：跳转结束

参数：

{

"timestamp" : 200

"moreChat" : [true|false]

}

参数	说明
timestamp	最终跳转到的时间点。由于关键帧的原因，最终的跳转时间点不一定跟指定的跳转时间点相同。关键帧的原理请百度或者google。
moreChat	是否有更多聊天

3.13onPlayheadTime

事件说明：提交playheadTime请求后的异步回调事件

参数：

{

"playheadTime" : 200，

}

参数	说明
playheadTime	点播当前播放的时间点，单位毫秒。

3.14onFileDuration

事件说明：收到点播文件的总时长

参数：

{

"duration" : 23400

}

参数	说明
duration	点播当前文件总时长，单位毫秒

3.15onVote

事件说明：收到调查问卷

参数：

{

"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"]

}

]

}

]

}

参数	说明
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使用。

3.16onStatus

事件说明：SDK状态通知

参数：

{

"type" : [1 | 2 | 3] ,

"explain" : "license not enough"

}

参数

说明

type

类型

1 - License不足；

2 - 点播未开始，等待点击开始按钮；

3 - 缓冲状态

4 - 不能在ipad中播放

5 - 正在执行seek命令

6 - 表示有人登陆

7 - 人数已经满了

8 – 数据还没有准备好

9 - 视频第一次缓冲播放开始

explain

说明

3.17onAPIError

事件说明：API错误通知

参数：

{

"api" : "submitQuestion",

"param" : {……},

"explain" : "format error",

"type" : 1

}

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

3.18onChatSegmentList

事件说明：收到分段聊天记录

默认200条。如果需要加载更多记录，请参考more参数用法。

{

"more" : true,

"list" : [

{

"sender" : "Tom",

"content" : "fine, thank you.",

"submitTime" : 9654123,

"senderId" : "111111",

"senderRole" : "1,2,4"

{

"sender" : "Jacky",

"content" : "Hi.",

"submitTime" : 9654123,

"senderId" : "111111",

"senderRole" : "1,2,4"

}

]

}

参数	说明
sender	发送者名称
content	聊天内容
submitTime	发送时间
senderId	发送者用户ID
senderRole	(需支持公聊数据的同步播放功能，才会输出) 用户角色以组合的形式出现，可能是单个角色，可能是多个角色，多个角色用逗号分隔，角色对应含义如下：组织者 = 1 主讲 = 2 嘉宾 = 4 普通参加者 = 8 Web参加者 = 为空
more	false – 说明没有更早的聊天数据 true – 说明还有更早的聊天数据，可以再次调用submitChatSegment以获取下一批200条聊天数据。

3.19onLeaveMessageList

事件说明：收到用户留言信息

参数：

{

"list" : [

{

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

"question" : "how are you?",

"submitor" : "Tom",

"answer" : "fine, thank you.",

"answerBy" : "Jack",

"submitTime" : 9654123,

"answerTime" : 8795623

{

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

"question" : "how are you?",

"submitor" : "Tom",

"answer" : "fine, thank you.",

"answerBy" : "Jack",

"submitTime" : 9654123,

"answerTime" : 8795623

}

]

}

参数	说明
list	问答列表，列表中每个对象都是留言信息。可以参考onQA的字段说明

3.20onMessage

事件说明：收到系统消息（广播消息）

参数：

{

"content":"通知。。。。"

"time":"1543458908000”

}

参数	说明
content	系统消息内容
time	系统消息发出的时间（毫秒）

3.21onChatHistory

事件说明：监听事件，初始化后并不会马上返回任何数据。只有当提交submitChatHistory后，监听事件才会收到聊天数据，默认200条。如果需要加载更多记录，请参考more参数用法。

参数：

{

"more" : true,

"list" : [

{

"sender" : "Tom",

"content" : "fine, thank you.",

"submitTime" : 9654123,

"senderId" : "111111",

"senderRole" : "1,2,4"

{

"sender" : "Jacky",

"content" : "Hi.",

"submitTime" : 9654123,

"senderId" :111111,

"senderRole" : "1,2,4"

}

]

}

参数	说明
sender	发送者名称
content	聊天内容
submitTime	发送时间
senderId	发送者用户ID
senderRole	(需支持公聊数据的同步播放功能，才会输出) 用户角色以组合的形式出现，可能是单个角色，可能是多个角色，多个角色用逗号分隔，角色对应含义如下：组织者 = 1 主讲 = 2 嘉宾 = 4 普通参加者 = 8 Web参加者 = 为空
more	false – 说明后续没有聊天数据 true – 说明后续还有聊天数据，可以再次调用submitChatHistory以获取下一批200条聊天数据。

3.22onChat

事件说明：当点播支持聊天同步功能时，开启聊天数据同步播放功能并监听该事件，则可以在点播播放过程中根据播放进度收到对应的聊天数据。

参数：

{

"list" : [

{

"sender" : "Tom",

"content" : "fine, thank you.",

"submitTime" : 9654123,

"senderId" : "111111",

"senderRole" : "1,2,4"

{

"sender" : "Jacky",

"content" : "Hi.",

"submitTime" : 9654123,

"senderId" : "111111",

"senderRole" : "1,2,4"

}

]

}

参数	说明
sender	发送者名称
content	聊天内容
submitTime	发送时间单位为秒(GMT 1970.1.1)
senderId	发送者用户ID
senderRole	(需支持公聊数据的同步播放功能，才会输出) 用户角色以组合的形式出现，可能是单个角色，可能是多个角色，多个角色用逗号分隔，角色对应含义如下：组织者 = 1 主讲 = 2 嘉宾 = 4 普通参加者 = 8 Web参加者 = 为空

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

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

参数：

{

"code": “mobile_not_bind”,

}

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

4提交命令或数据API

4.1seek

说明：跳转到指定时间点

参数：

{

"timestamp" : 100

}

参数	说明
timestamp	指定时间点，单位毫秒。

4.2pause

说明：暂停播放

参数：

{

}

参数	说明

4.3play

说明：开始播放/暂停后恢复播放

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

原因详见：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

参数：

{

}

参数	说明

4.4playheadTime

说明：获取当前播放时间点，下载进度，文件总时长

参数：

{

}

参数	说明

4.5submitVote

事件说明：提交调查问卷结果

参数：

提交对象格式同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.6 leaveMessage

说明：留言

参数：

{

"content" : "what's your name?",

"email" : "dsfdsf@126.com"

}

参数	说明
content	问题内容
email	邮件（非必选）

4.7submitQAList

事件说明：通过接口申请获取生成该点播的直播Q&A历史记录。

这是个异步申请接口，Q&A数据将通过onQAList事件返回给第三方。因此，请在调用此方法前，预先监听onQAList事件。

参数：

{

}

4.8submitChatHistory

事件说明：通过接口申请获取生成该点播的直播公共聊天历史记录。

这是个异步申请接口，公共聊天历史数据将通过onChatHistory事件返回给第三方。因此，请在调用此方法前，预先监听onChatHistory事件。

参数：

{

}

4.9submitChatSegment

事件说明：通过接口申请获取该点播的直播公共聊天更多历史记录。开启聊天数据同步功能后可用。

这是个异步申请接口，聊天分段历史数据将通过onChatSegmentList事件返回给第三方。因此，请在调用此方法前，预先监听onChatSegmentList事件。

参数：

{

}

4.10submitLeaveMessageList

事件说明：通过接口申请获取该点播的留言历史记录。

这是个异步申请接口，留言历史数据将通过onLeaveMessageList事件返回给第三方。因此，请在调用此方法前，预先监听onLeaveMessageList事件。

参数：

{

}

4.11setupChatSync

说明：开启或关闭聊天数据同步功能。

当点播支持聊天同步功能时，开启同步功能则可以通过onChat事件收到聊天数据；关闭同步功能则不会发送onChat事件。

参数：

{

"open" : [ true | false]

}

open	是否开启聊天同步播放功能。默认是不开启。 true – 开启 false – 关闭

4.12submitPlaybackRate

事件说明：通过接口控制音视频倍速播放

注意：该api 目前仅支持ios设备，安卓设备兼容的不完善，请测试后使用。

参数：

{

" playbackRate" : [0.5-4]

}

参数	说明
playbackRate	倍数可配置范围：0.5-4，微调精度：0.25

5补充说明

5.1H5播放器兼容性问题

5.1.1 站点需要开启“移动端转码”，否则不支持移动端SDK2.0。

5.2编码问题

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