直播 JavaScript SDK 使用文档

概述

该SDK是用于web端接入POLYV直播服务,包括云课堂和直播助手发起的直播的web端观看,POLYV聊天室服务,兼容PC以及移动端观看。

快速开始

第一步:引入直播SDK

<script src="https://player.polyv.net/livesdk/polyv-live.min.js"></script>

第二步:创建初始化ppt与讲师画面元素

<div id="ppt" style="width:500px;height:300px;"></div>
<div id="player" style="width:500px;height:300px;"></div>

第三步:创建SDK实例

var liveSdk = new PolyvLiveSdk({
  channelId: channelId,
  sign: sign, // 频道验证签名
  timestamp: timestamp, // 毫秒级时间戳
  appId: appId, // polyv 后台的appId
  user: {
    userId: userId,
    userName: 'polyv-test',
    pic: '//livestatic.videocc.net/assets/wimages/missing_face.png'
  }
});

第四步:监听频道信息读取完成事件,初始化播放器

// 监听频道信息并初始化播放器
liveSdk.on(PolyvLiveSdk.EVENTS.CHANNEL_DATA_INIT, (event, data) => {
  liveSdk.setupPlayer({
    pptEl: '#ppt',
    el: '#player',
    type: 'auto'
  });
});  

API

PolyvLiveSdk 是用于创建SDK实例的类

类方法

PolyvLiveSdk.getChannelInfo(channelId: string, appId: string, sign: string, timestamp: number): Promise

获取频道信息

PolyvLiveSdk.previewPPT(config: previewConfig): PreviewPPT

预览指定的ppt
参数说明

interface previewConfig {
  el: DOMSeletor;  // 需要显示预览ppt的dom选择器
  autoId: number|string;  // pptId
  type: string;  // ppt类型
  width?: number|string;  // ppt宽,默认100%
  height?: number|string; // ppt高,默认100%
  pptNav?: boolean; //是否显示ppt控制控件,默认`true`  
  pptNavBottom?: string`; //ppt控制栏距离底部距离,例:`pptNavBottom: '50px'` 
}

实例方法
PreviewPPT.nextPPTPage(): void 使ppt切换到下一页,跟随模式下不能切到讲师未讲解的ppt
PreviewPPT.prevPPTPage(): void 使ppt切换到上一页

实例事件
success: 实例创建成功
error: 预览失败
pptStatusChange: 当前页改变,与liveSdk.player 上的事件一致

返回值 PreviewPPT
示例代码

var previewPPT = PolyvLiveSdk.previewPPT({
  el: '#previewPPT',
  autoId: 123,
  isAnimate: true,
  type: 'new',
});

previewPPT.on('success', function() {
  console.log('预览成功');
});

previewPPT.on('error', function(err) {
  console.log('预览失败', err);
});

// 销毁ppt预览实例
//previewPPT.destroy()
  • 当前频道的ppt列表可通过接口获取 -> 接口文档
  • 接口请求中的参数 status 建议设置 normal,请求成功处理的ppt

类属性

PolyvLiveSdk.emotionLists: { url: string; title: string: position: string }[]

polyv 表情数据列表
全部表情 sprites 图片地址: https://livestatic.polyv.net/assets/images/em/default.png

// 返回数据
[
  {
    url: '//livestatic.polyv.net/assets/images/em/2.png',
    title: '撇嘴',
    position: '-48px 0px' // sprites图位置
  }
]

PolyvLiveSdk.emotionSearch: object

键值对为 [表情title]: 表情url 的对象

实例设置

channelId: string

频道id, 支持云课堂/直播助手/大班课发起的直播

sign: string

POLYV 频道信息获取接口用到的签名 签名规则
请用channelId、timestamp、appId 三个字段拼接sign

timestamp: number

POLYV 频道信息获取接口用到的时间戳
- 注意:该时间戳需要与服务器端获取的签名一样

appId: string

POLYV账号 appId,从 POLYV 后台获取

user: { userId: string; userName: string; pic: string; }

用户信息设置
* user.userId: string : 用户id
* user.userName: string : 用户昵称
* user.pic: string : 用户头像,必须为是http/https/ // 开头链接

{
    userId: '自定义id', // 用户id
    userName: 'polyv-test', // 用户昵称
    pic: '//livestatic.videocc.net/assets/wimages/missing_face.png' // 用户头像
}

chat: boolean

是否连接聊天室,默认为true,在云课堂模式下如果调用直播播放器必须连接聊天室,所以即使设置为false,在初始化直播播放器时会自动连接聊天室,回放模式下可以不连接

param4?: stringparam5?: stringkey1?: stringkey2?: stringkey3?: stringcode?: string

播放器统计参数,param1、param2,param3被预设为userId和userName以及直播状态,所以设置无效

socket: SocketIOClient.Socket

SDK 支持传入外部传入 polyv 聊天室 socket ,传入后SDK不在连接socket,请在外部socket实例创建后就初始化SDK实例并把socket传入
示例代码(以polyv聊天室SDK为例)

var chatroom = new PolyvChatRoom({
  roomId: channelId,
  userId: userId,
  nick: userName,
  pic: pic,
  userType: 'slice'
});

var liveSDK = new PolyvLiveSdk({
  channelId: channelId,
  appId: appId,
  sign: sign,
  timestamp: timestamp,
  socket: chatroom.chat.socket,
  user: {
    userId: userId,
    userName: userName,
    pic: pic
  }
});

实例方法

setupPlayer(config: object)

初始化播放器,必须在频道信息事件触发时调用
参数:config 播放器配置对象

示例代码:

var config = {
    pptEl: '#ppt',
    el: '#player',
    type: 'auto',
    autoplay: false,
    audioMode: false,
    width: '100%',
    height: '100%',
    pptWidth: '100%',
    pptHeight: '100%',
    controllerPosition: 'ppt',
    controller: true,
    pptNav: true,
    // 回放模式需要fileId、url、sessionId
    fileId: undefined,
    url: undefined,
    sessionId: undefined
}
// 监听频道信息并初始化播放器
liveSdk.on(PolyvLiveSdk.EVENTS.CHANNEL_DATA_INIT, (event, data) => {
  liveSdk.setupPlayer(config);
});  

参数说明:
pptEl?: DOMSelectors:ppt文档元素选择器,非云课堂可不填
el: DOMSelectors:讲师区域元素
width?: string|number:讲师区域宽,默认'100%'
height?: string|number:讲师区域高,默认'100%'
pptWidth?: string|number:ppt区域宽,默认'100%'
pptHeight?: string|number:ppt区域高,默认'100%'
type?: string: 播放器播放类型,'auto'(根据频道实际设置自动选择播放类型)、'live'(直播)、'vod'(回放)、'record'(暂存), 默认'auto',选择'auto'后,播放器会以直播->回放列表视频->第一个暂存视频(优先级由大到小)的优先级播放
autoplay?: boolean:是否自动播放,默认false
audioMode?: boolean:讲师画面以音频模式播放, 默认false
controller?: boolean:是否显示控制栏, 默认true
controllerPosition?: string:控制栏现在在哪个区域 'ppt'(ppt区域)、'player'(讲师区域), 默认ppt
pptNav?: boolean:是否显示ppt控制控件,默认true
pptNavBottom?: string:ppt控制栏距离底部距离,例:pptNavBottom: '50px'
pptPlaceholder?: boolean:是否在直播模式并且当前暂无直播时在ppt区域显示占位图,默认false
fileId: string: ppt数据id,回放模式必填
url: string: 回放视频链接,回放模式必填
sessionId: string:回放场次id,回放模式必填
vid: string: 回放id,回放模式下传入该参数可不传fileIdurlsessionId

liveSdk.reloadPlayer(): void

重新加载播放器,目前支持播放器播放类型为live场景的使用,比如当前客户端没有推流,用户打开了页面,过一段时间后客户端开始推流可以调用该方法刷新播放器

liveSdk.setupPlayer({
  // ... 
  type: 'live'
  // ...
});

// 监听流状态变化刷新播放器
liveSdk.on(PolyvLiveSdk.EVENTS.STREAM_UPDATE, function() {
  liveSdk.reloadPlayer();
});

liveSdk.switchVod(sessionData: object)

换回放场次,用于切换具体播放场次视频
参数:sessionData 需要播放场次的场次数据
示例代码

// data数据是该场次数据,可通过liveSdk.getPlaybackLists(...) 获取
liveSdk.switchVod({
  fileId: data.videoId,
  url: data.url,
  sessionId: data.channelSessionId
});
//or 
liveSdk.switchVod({
  vid: data.videoPoolId
});

liveSdk.getPlaybackLists(page: number, pageSize: number): Promise

获取回放列表
示例代码:

liveSdk.getPlaybackLists(1, 5)
.then(function(data) {
    console.log(data);
});

参数:
page: number: 页数
pageSize: number: 每页条数

liveSdk.getChapterLists(fileId: string, type: string): Promise

获取章节列表
参数:
fileId: string: ppt数据id
type: string:章节类型, playback(回放)、record(暂存)
- @return Promise

liveSdk.send(message: string): void

发送聊天消息
参数:
message: string:聊天内容

liveSdk.sendQuestion(message: string): void

向讲师发送问答私聊信息
参数:
message: string: 私聊信息

liveSdk.sendAnswer(option: string, questionId: string, callback: Function): void

发送答题卡回答内容
参数:
option: string: 答题卡答案A/ABC
questionId: string: 答题卡题目id
callback: Function: 发送成功回调

liveSdk.sendCustomMessage(messsage: object): void

发送自定义消息,聊天室会广播这些信息,由用户自行定义数据结构
示例代码

liveSdk.sendCustomMessage({
  EVENT: 'customA',
  data: '自定义信息'
});

liveSdk.getHistoryMessage(): Promise

获取历史聊天记录,默认10条

liveSdk.destroy(disconnectSocket: boolean = true): void

销毁播放器示例
参数:
disconnectSocket: bolean: 是否断开socket

liveSdk.toSign(checkinId: string, callback: Function): void

发送签到
参数:
checkinId: string: 签到id
callback: Function: 发送签到回调

liveSdk.sendQuestionnaireAnswer(questionnaireId: string, answer: [], callback: Function): void

发送问卷答案
参数:
questionnaireId: string: 问卷Id
answer: []:答案列表, 与文档 ANSWER_QUESTIONNAIRE中的result一致
callback: Function: 发送回调
示例代码:

liveSdk.sendQuestionnaireAnswer('fdp9u1x022', [
  // ...
  {
  questionId: '48e5afd460', answer: 'B'
  },
  // ...
])

liveSdk.getCloudClassRoomStatus(): Promise

仅在开启直播录制时有效(详情可咨询技术支持)
查询当前频道直播状态
示例代码:

liveSdk.getCloudClassRoomStatus()
.then(function(resp) {
  if (resp.status === 'success') {
    // liveStart(开始上课)、liveRecovery(恢复)、liveSuspend(暂停)、liveFinish(结束)
    console.log('当前直播状态为:' + resp.data.status);
  }
});

实例 player 对象

liveSdk.player: 调用 setupPlayer 后创建的播放器实例,可用于控制播放器播放相关交互

对象属性

liveSdk.player.currentTime: number: 当前播放的进度
liveSdk.player.duration: number: 视频时长
liveSdk.player.playbackRate: number: 当前倍速
liveSdk.player.volume: number: 当前音量
liveSdk.player.cameraStatus: boolean: 当前讲师摄像头是否被关闭
liveSdk.player.paused: boolean: 当前是否是暂停播放状态
liveSdk.player.supportFullScreen:boolean: 是否支持全屏
liveSdk.player.fullScreen:FullScreen:播放器全屏实例,里面封装了进入全屏以及退出全屏的方法,可对于页面任意DOM操作
liveSdk.player.lines: number:当前频道有多少条线路,需要在loadedmetadata时间后访问
liveSdk.player.line: number:当前播放的线路 0/1
liveSdk.player.currentPPTPage:当前展示的ppt页码,若当前显示PDF或者白板则返回1
liveSdk.player.totalPPTPages: 当前使用的ppt总页数,若当前使用PDF或者白板则返回1
#####全屏示例说明
liveSdk.player.fullScreen.request($dom: HTMLElement): void:将指定元素进入全屏状态
liveSdk.player.fullScreen.exit(): void:退出全屏状态

对象方法

liveSdk.player.setVolume(volume: number): void: 设置播放器音量,范围[0, 1]
liveSdk.player.play(): void:恢复播放视频
liveSdk.player.pause(): void:暂停播放视频
liveSdk.player.togglePlay(): void:交替恢复暂停播放视频
liveSdk.player.resize(): void:刷新ppt尺寸,播放期间如果对ppt容器尺寸有改变ppt尺寸可能异常,再改变尺寸后调用该方法恢复正常尺寸
liveSdk.player.seek(time:number): void:请求到指定播放位置
liveSdk.player.setRate(rate: number): void:切换倍速,可选0.5、1、1.25、1.5、2
liveSdk.player.switchCamera(hide: boolean): void:关闭或显示讲师摄像头
liveSdk.player.switchLine(line: number): void:切换当前线路,line由number 0递增,代表线路1、线路2...
liveSdk.player.switchPPTDocMode(control: boolean): boolean:直播时切换ppt模式,设置true ppt可由用户自己控制ppt内容,不跟随客户端控制(自由模式),反之。调用返回是否切换成功(跟随模式)
liveSdk.player.nextPPTPage(): void 使ppt切换到下一页,跟随模式下不能切到讲师未讲解的ppt
liveSdk.player.prevPPTPage(): void 使ppt切换到上一页

对象事件

playing: 恢复播放
pause: 暂停播放
timeupdate: 播放进度更新
loadedmetadata: 视频加载成功可以准备播放,可对播放器进行play()、pause()等操作
ended:播放结束
ratechange:倍速改变
volumechange:音量改变
lineChanged:线路改变

liveSdk.player.on(lineChanged, function(line) {
  console.log(line); // 0/1...
});

error:视频播放错误
示例代码

liveSdk.player.on('playing', function() {
  console.log('恢复播放');
});
liveSdk.player.on('pause', function() {
  console.log('暂停播放');
});
PPT操作相关事件

whiteboardOpened: 讲师打开白板
whiteboardClosed: 讲师关闭白板,恢复为PPT
pptStatusChange: ppt状态改变,包括当前页数改变(ppt更换、ppt与白板切换 ),翻页,注意白板状态时不能翻页
示例代码

liveSdk.player.on('pptStatusChange', function(data) {
  /*
  {
    page: 3,  // 当前是第几页
    total: 30, // 当前ppt总页数
    type: 'ppt' // ('ppt'|'whiteboard') 当前显示类型,ppt或白板
  }
  */ 
  console.log(data);
});

实例事件

事件方法

liveSdk.on(event: string, func: Function)

事件监听方法
event: string: 绑定事件名称
func: (event: string, data: object): void:事件回调函数

liveSdk.once(event: string, func: Function)

绑定事件,只触发一次
event: string: 绑定事件名称
func: (event: string, data: object): void:事件回调函数

liveSdk.off(event: string, func: Function)

解除事件绑定
event: string: 绑定事件名称
func: Function: void:事件回调函数

liveSdk.on(PolyvLiveSdk.EVENTS.CHANNEL_DATA_INIT, function(event, data){});

事件列表

PolyvLiveSdk.EVENTS.CHANNEL_DATA_INIT

  • 频道信息获取完成
  • data为频道信息

PolyvLiveSdk.EVENTS.PLAYBACK_INIT

  • 回放章节初始化完成
  • data: 场次数据
    javascipt
    {
    sessionId: '123',
    fileId: '123'
    }

PolyvLiveSdk.EVENTS.STREAM_UPDATE(event, status)

  • 流状态更新,可用来判断当前有无直播在推流
  • status (live|end)

PolyvLiveSdk.EVENTS.SPEAK

  • 非本人的用户发言
  • data:聊天信息
    javascript
    {
    EVENT: 'speak',
    content: 'test', // 聊天具体内容
    currentUser: false, // 是否为当前用户
    custom: false, // 是否是自定义消息
    formatTime: '2019-07-02 14:12',
    id: '65975130-9c90-11e9-94b0-fd61e3983999', // 消息id
    reward: false,
    time: 1562047960506,
    user: { // 用户信息
    banned: false,
    channelId: '275682',
    clientIp: '61.144.146.199',
    nick: 'polyv',
    pic: '//livestatic.videocc.net/v_314/assets/wimages/missing_face.png',
    roomId: '275682',
    sessionId: 'f8qnsda4zq',
    uid: 'Ph4UtYfnxQo7pZK6AkbP',
    userId: '1562047951865',
    userType: 'slice',
    }
    }

PolyvLiveSdk.EVENTS.SEND_MESSAGE

  • 本人的发言
  • data: 与PolyvLiveSdk.EVENTS.SPEAK一致

PolyvLiveSdk.EVENTS.S_QUESTION

  • 发送提问消息回调
  • data:提问数据
{
  EVENT: 'S_QUESTION',
  content: '1+1=多少',
  currentUser: true,
  custom: false,
  reward: false,
  roomId: '275682',
  user: {
    // ... 用户信息
  }
}

PolyvLiveSdk.EVENTS.T_ANSWER

  • 管理员或讲师回答提问
  • data:回答的数据
{
  EVENT: 'T_ANSWER'
  content: '等于2'
  roomId: '275682'
  s_userId: '1559030433536', // 被回答用户id
  user: {
    // ... 用户信息
  }
}

PolyvLiveSdk.EVENTS.CUSTOM_MESSAGE

  • 收到自定义消息
  • data:具体数据结构由用户自行定义

PolyvLiveSdk.EVENTS.REMOVE_HISTORY

  • 清除聊天记录,页面可收到该消息后清除页面聊天内容

PolyvLiveSdk.EVENTS.REMOVE_CONTENT

  • 清除某一条聊天信息,页面可收到该消息后清除相应聊天内容
  • data:被删除消息内容
{
  EVENT: 'removeContent',
  id: '65975130-9c90-11e9-94b0-fd61e3983999', // 被删除消息的id
  roomId: '275682'
}

PolyvLiveSdk.EVENTS.HISTORY_MESSAGE

  • 获取历史聊天信息完成
  • data:历史聊天信息,内容为speak事件内容组成的数组

PolyvLiveSdk.EVENTS.PROHIBIT_TO_SPEAK

  • 发言失败,可能由于聊天室为连接但发送聊天消息等发送错误触发

PolyvLiveSdk.EVENTS.ADD_SHIELD

  • 当前用户被禁止发言

PolyvLiveSdk.EVENTS.REMOVE_SHIELD

  • 当前用户被恢复发言

PolyvLiveSdk.EVENTS.LOGIN(event, data)

  • 频道内用户登录事件
  • data: 用户信息
// 用户加入信息
{
  EVENT: 'login',
  onlineUserNumber: 3,
  timeStamp: 1562051459569,
  user: {
    // 用户信息
  }
}

PolyvLiveSdk.EVENTS.LOGOUT(event, data)

  • 频道内用户退出事件
  • data: 用户信息
{
  EVENT: 'loginOut',
  channelId: '275682',
  onlineUserNumber: 2,  //当前在线人数
  roomId: '275682',
  timeStamp: 1562051345281,
  uid: 'LVexVHpKvK0KOU_0Ak4L',
}

PolyvLiveSdk.EVENTS.LOGIN_REFUSE

  • 频道内有用户被踢出房间,包含用户以及本身
  • data: 被踢用户数据
{
  EVENT: 'LOGIN_REFUSE',
  data: {referField: '1559030433537', type: 'userId'}
}

PolyvLiveSdk.EVENTS.BAN_USER_ROOM

  • 当前用户被踢出房间,这时候会自动断开聊天室连接

PolyvLiveSdk.EVENTS.LOGIN_KICK

  • 用户登录聊天室时如果已经被提出房间会收到该事件

PolyvLiveSdk.EVENTS.SIGN_IN

  • 收到讲师发起签到消息
  • 可调用 liveSdk.toSign 方法发送签到
  • 签到数据
{
  EVENT: 'SIGN_IN',
  data: {
    checkinId: '07ff9330-9c99-11e9-8aa1-37da87', // 签到id
    createTime: 1562051668963,
    limitTime: '30', // 签到时间,页面需要根据这个时间显示倒计时,结束后不允许再签到
    message: '各位同学开始签到了' // 签到提示文案
  }
  roomId: '275682'
}

PolyvLiveSdk.EVENTS.STOP_SIGN_IN

  • 收到讲师停止签到消息,收到后不允许发送签到

PolyvLiveSdk.EVENTS.BULLETIN

  • 收到公告消息
  • data:公告消息
{
  EVENT: 'bulletin',
  content: '公告内容'
}

PolyvLiveSdk.EVENTS.REMOVE_BULLETIN

  • 删除公告消息

PolyvLiveSdk.EVENTS.START_QUESTIONNAIRE

  • 收到问卷消息, 回答后可使用liveSdk.sendQuestionnaireAnswer 方法发送答案
  • data: 问卷内容
  • 问卷消息内容,与polyv 聊天室 START_QUESTIONNAIRE 事件数据一致 查看

PolyvLiveSdk.EVENTS.STOP_QUESTIONNAIRE

  • 讲师停止问卷
  • data: 消息内容

PolyvLiveSdk.EVENTS.GET_TEST_QUESTION_CONTENT

  • 答题卡: 获取问题内容
  • data: 答题卡消息,可查阅 文档 答题卡部分

PolyvLiveSdk.EVENTS.GET_TEST_QUESTION_RESULT

  • 答题卡: 获取答题结果

PolyvLiveSdk.EVENTS.STOP_TEST_QUESTION

  • 答题卡: 停止答题

PolyvLiveSdk.EVENTS.ON_PAUSE_RECORD

  • 直播录制暂停(课间休息)

PolyvLiveSdk.EVENTS.ON_START_RECORD

  • 恢复录制(休息结束,恢复直播)

PolyvLiveSdk.EVENTS.ON_EXIT_RECORD

  • 退出录制(下课)
以上内容是否对您有帮助?根本没有帮助文档较差文档一般文档不错文档很好
Loading...