最近更新时间:2024.04.28 14:59:39
首次发布时间:2022.02.24 19:18:57
观播 SDK 提供看直播、发评论、参与抽奖等功能。本文介绍 Web 观播 SDK 的集成方法以及相关参数、事件、API 等。
Web 观播 SDK 支持的功能情况,详见 SaaS 与 aPaaS 功能差异。
完成以下步骤,将观播 SDK 集成到您的 Web 应用中。
通过 link
和 script
标签分别引入 CSS 和 JS 资源。
直接修改 URL 中的版本号即可更新版本,同一终端的 CSS 和 JS 版本应保持一致。
说明
// PC 端(仅支持模块化接入) <link rel="stylesheet" href="https://lf-cdn-tos.bytescm.com/obj/static/livesaas-client/pc/css/index.1.5.0.css"> <script src="https://lf-cdn-tos.bytescm.com/obj/static/livesaas-client/pc/js/index.1.5.0.js"></script> // PC 端(单独接入播放器模块,仅支持点播、直播、清晰度、倍速以及多线路等播放器相关功能。性能优于 PC 端模块化接入方式) <link rel="stylesheet" href="https://lf-cdn-tos.bytescm.com/obj/static/livesaas-client/player-pc/css/index.1.5.0.css"> <script src="https://lf-cdn-tos.bytescm.com/obj/static/livesaas-client/player-pc/js/index.1.5.0.js"></script> // 移动端(支持模块化接入或整页接入) <link rel="stylesheet" href="https://lf-cdn-tos.bytescm.com/obj/static/livesaas-client/mobile/css/index.1.5.0.css"> <script src="https://lf-cdn-tos.bytescm.com/obj/static/livesaas-client/mobile/js/index.1.5.0.js"></script> // 移动端(仅支持整页接入,性能优于其他移动端整页接入方式) <link rel="stylesheet" href="https://lf-cdn-tos.bytescm.com/obj/static/livesaas-client/mobile-all/css/index.1.5.0.css"> <script src="https://lf-cdn-tos.bytescm.com/obj/static/livesaas-client/mobile-all/js/index.1.5.0.js"></script> // 移动端(单独接入播放器模块,仅支持点播、直播、清晰度、倍速以及多线路等播放器相关功能。性能优于其他移动端模块化接入方式) <link rel="stylesheet" href="https://lf-cdn-tos.bytescm.com/obj/static/livesaas-client/player-mobile/css/index.1.5.0.css"> <script src="https://lf-cdn-tos.bytescm.com/obj/static/livesaas-client/player-mobile/js/index.1.5.0.js"></script>
国内域名:https://lf-cdn-tos.bytescm.com/obj/static
最新版本:1.5.0
资源引入后, ByteLiveWebSDK 挂载在 window
下。您可以通过以下方式,将观播 SDK 集成到您的 Web 应用中,从而在观看页展示直播间或点播播放器。
直播间
var webSDK = new window.ByteLiveWebSDK({ activityId: 169410856822****, token: 'JC****', service: '', mode: 1, modules: [ { id: "player", mode: "player", }, { id: "menu", mode: "menu", menu: ["comment"], } ], options: {} }) webSDK.emit('player.pause'); // 触发事件 webSDK.on('player.pause', () => {}); // 监听事件
点播播放器
var webSDK = new window.ByteLiveWebSDK({ vodPlayerToken: 'ceed74dcb2ceaba3c92a91fc2ebd****', vid: 'v03a49g10000cojk12bc77ua72bm****', service: '', modules: [ { id: "player", mode: "player", } ], options: {} }) webSDK.emit('player.pause'); // 触发事件 webSDK.on('player.pause', () => {}); // 监听事件
(可选)覆盖样式。SDK 元素的 class
属性值不可更改。您可以通过变更 class
属性的样式属性及其属性值,覆盖组件或组件元素的样式。
调试效果。您可以选择以下任一调试方法:
localhost:8080
端口进行调试,但此种调试方法无法播放预告和回放。有关本地调试方法,详见 Demo 体验集成示例。名称 | 类型 | 是否必选 | 默认值 | 描述 | |
---|---|---|---|---|---|
vodPlayerToken | String | 是 | 不适用 | 播放器 Token。调用 GetVodPlayerToken 获取 Token。您也可以在企业直播控制台的媒资库 > 播放器设置页面获取 Token。 | |
vid | String | 是 | 不适用 | 视频 ID。调用 ListActivityMediaAPI 获取视频 ID。您也可以在企业直播控制台的媒资库 > 视频管理 > 视频库页面获取视频 ID。 | |
service | String | 是 | 不适用 | 服务名称,仅用于标记。 | |
modules | id | String | 是 | 不适用 | 页面元素 ID,指定模块需要渲染的位置和大小。 |
mode | String | 是 | 不适用 | 模块名称。取值固定为 |
名称 | 类型 | 是否必选 | 默认值 | 描述 | |
---|---|---|---|---|---|
activityId | Number | 是 | 不适用 | 直播间的活动 ID。调用 CreateActivityAPIV2 获取活动 ID。您也可以在企业直播控制台的直播间左上角获取活动 ID。一个直播间对应一个 activityId。 | |
service | String | 是 | 不适用 | 服务名称,仅用于标记。 | |
mode | Number | 是 | 不适用 | 鉴权模式。
| |
token | String | 是 | 不适用 | 用户 token。
| |
modules | id | String | 是 | 不适用 | 页面元素 ID,指定模块需要渲染的位置和大小。 |
mode | String | 是 | 不适用 | 模块名称。
说明 参数值设置为 | |
menu | String[] | 否 | 无 | 仅在
| |
options | origin | String | 否 | "https://live.byteoc.com" | 业务请求域名。如无特殊需求,无需设置。 |
saveUserInfo | Boolean | 否 | true |
| |
mobileBackgroundTransparent | Boolean | 否 | false | 设置移动端模块背景是否透明。
| |
mobileGetUserId | Boolean | 否 | true | 设置是否开启快速获取移动端用户 ID 的入口。开启后在页面左上角快速点击 5 次即可获取用户 ID。
| |
basicPolling | Boolean | 否 | true | 设置是否开启轮询 API 实时更新直播间信息。
| |
pcPlayerHeader | Boolean | 否 | false | 设置 PC 端播放器上方是否展示直播名称、描述等信息。
| |
disabledLogin | Boolean | 否 | false | 设置是否禁用企业直播自带的登录体系。通常配合
| |
disableCardRedirect | Boolean | 否 | false | 设置是否禁用商品卡片点击跳转能力。通常配合
| |
disableAdFloatingRedirect | Boolean | 否 | false | 设置是否禁用浮标广告点击跳转能力。通常配合
| |
disableAdMiddleRedirect | Boolean | 否 | false | 设置是否禁用页中广告点击跳转能力。通常配合
| |
disableAdAccountRedirect | Boolean | 否 | false | 设置是否禁用主播账号点击跳转能力。通常配合
| |
disableReservationCell | Boolean | 否 | false | 设置是否禁用预约弹窗。通常配合
| |
isReserved | Boolean | 否 | 无 | 设置用户是否已预约。
| |
lotteryIcon | 否 | 无 | 抽奖图标。支持的图片格式与 | ||
emojiIcon | String | 否 | 无 | PC 端表情面板入口的图标。参数值为图标的图片链接。支持的图片格式与 | |
moreActionExpandPc | Boolean | 否 | false | 设置是否在 PC 端聊天互动菜单下将更多图标内的选项作为图标展示。
| |
riskWarning | Boolean | 否 | true | 设置是否开启风险提示。
| |
disableLotteryTicketRedirect | Boolean | 否 | false | 设置是否禁用抽奖的奖券奖品点击跳转能力。通常配合
| |
extra | String | 否 | 不适用 | 同步至企业直播控制台的额外参数,可用于关联用户。例如设置参数值为 | |
loginInToThumbUp | Boolean | 否 | false | 设置是否必须登录才能点赞直播间。
| |
disableFeatureProcess | Boolean | String[] | 否 | false | 设置在观众点击互动功能按钮后,是否阻止功能的后续执行。
支持阻止以下互动功能的后续执行:
| |
useUserConnect | Boolean | 否 | false | 设置是否强制展示移动端连麦入口。
说明
| |
hideUserConnect | Boolean | 否 | false | 设置是否强制隐藏移动端连麦入口。
说明 连麦功能使用了 WebRTC 技术,由于该技术的兼容性限制,仅在观众使用以下操作系统和浏览器时,默认展示移动端连麦入口。如需强制隐藏移动端连麦入口,可将参数值设置为
|
名称 | 类型 | 是否必选 | 默认值 | 描述 |
---|---|---|---|---|
attendIcon | String | 否 | 无 | 未开奖时的抽奖图标。设置参数值为 |
openIcon | String | 否 | 无 | 已开奖时的抽奖图标。设置参数值为 |
名称 | 类型 | 是否必选 | 默认值 | 描述 | |
---|---|---|---|---|---|
options | playerRetryTimes | Number | 否 | 1 | 播放器遇到网络异常后的重试次数。主备流切换并降级后,如果仍然无法播放,即当前重试失败。设置为 0 表示无数次重试。 |
purePlayer | Boolean | 否 | false | 设置是否展示纯净播放器。纯净播放器指播放器内无进度条等互动按钮。
| |
videoFillMode | String | 否 | 'auto' | 设置播放器内视频的填充方式。
该参数仅对 PC 端和移动端横屏模式生效。 | |
softSolution | Boolean | 否 | 无 | 设置是否在移动端强制开启或关闭播放器软解解码直播视频。开启软解后可解决移动端部分浏览器或 App 下播放器被劫持的问题。
| |
playerBackgroundTransparent | Boolean | 否 | false | 设置播放器内未被画面填充部分的颜色是否为透明。
| |
disablePlayerCover | Boolean | 否 | false | 设置是否显示直播封面。
| |
mobilePlayerIconIgnoreList | String[] | 否 | 无 | 设置在移动端观看页的播放器上隐藏哪些功能的入口。
| |
portraitMenuExtends | 否 | 无 | 设置移动端竖屏直播间的菜单。 | ||
mobileGesture | 否 | 无 | 移动端播放器手势相关配置。 说明 由于 PC 端默认关闭手势,且不支持配置,平板在接入 PC 端 Web SDK 后,不支持通过手势操作。 | ||
showLikeInPlayer | Boolean | 否 | false | 设置是否将直播间点赞图标显示在播放器内。
| |
disableRotateFullscreen | Boolean | 否 | false | 设置是否禁用移动端旋转至横屏时会自动进入全屏模式。
| |
disableLivePauseButton | Boolean | 否 | false | 设置是否在直播期间隐藏播放器上的暂停按钮。
| |
rotateFullscreen | Boolean | 否 | false | 移动端 iOS 进入全屏模式后,视频是否自动切换为横屏播放。
| |
liveLineChangeIcon | String | HTMLElement | 否 | 无 | 通过传入 DOM 字符串或 DOM 元素,自定义播放器内多线路切换的按钮文案或图标。例如,设置参数值为 | |
defaultLiveLine | Number | 否 | 无 | 设置默认直播频道,即观众进入直播间时,观看页默认播放的直播频道。如未设置,则默认直播频道为频道语言与观众 PC 端浏览器语言或移动端系统语言相同的直播频道。 | |
autoPlay | Number | 否 | 1 | 设置视频的自动播放模式。
如果您的直播或点播视频无法按照参数设置自动播放或者只能静音自动播放,详见为什么直播或点播视频无法自动播放或者只能静音自动播放?。 | |
playerConf | 否 | 无 | 播放器交互相关配置。 |
名称 | 类型 | 是否必选 | 默认值 | 描述 |
---|---|---|---|---|
closeVideoDblclick | Boolean | 否 | false | 设置是否禁用在移动端双击播放器时,暂停或播放直播或点播内容。
|
名称 | 类型 | 是否必选 | 默认值 | 描述 |
---|---|---|---|---|
icon | String | 否 | 无 | 菜单内显示的图标。
|
render | String | 否 | 无 | 菜单内显示的图标或按钮。例如: 说明 优先级比 |
name | String | 否 | 无 | 图标或按钮的名称。该名称仅在图标或按钮收纳在更多图标中时显示在图标或按钮下方。 |
key | String | 是 | 无 | 菜单的唯一标识。 |
onClick | Function | 否 | 无 | 点击事件回调。返回值即 |
index | Number | 否 | 0 | 菜单内图标或按钮的显示顺序。数值越大,越靠左显示。值大于 70 会收纳在更多图标内。如果菜单内的图标和按钮总数超过 5 个(包括直播间内的默认图标),超过部分的图标或按钮会收纳在更多图标内。 |
名称 | 类型 | 是否必选 | 默认值 | 描述 |
---|---|---|---|---|
disableGesture | Boolean | 否 | false | 设置是否禁用移动端手势。禁用后,观众无法通过左右滑动预告或回放画面来拖动进度条。
|
webSDK.on('player.ratechange', playerRate => { console.log(playerRate); });
事件 key | 返回参数 | 描述 |
---|---|---|
player.play | 无 | 播放事件。 |
player.playing | 无 | (暂停、卡顿后)恢复播放事件。 |
player.pause | 无 | 暂停播放事件。 |
player.ended | 无 | 结束播放事件。 |
player.destroy | 无 | 销毁播放器事件。 |
player.ratechange | Number | 播放速率变化事件。
|
player.fullscreen_change | Boolean | 全屏模式变化事件。
|
player.pip_change | Boolean | PC 端小窗模式变化事件。
|
player.waiting | 无 | 等待加载数据事件。 |
player.status | String | 直播状态变更事件。 |
player.vodConfigChange |
| 点播视频(预告和回放)断点续播事件。
触发该事件后,返回以下参数:
|
lines.number | Number | 多线路数量变化事件。
|
说明
本章节仅适用于在观看页展示直播间的场景。
事件 key | 返回参数 | 描述 |
---|---|---|
activity.status | Number | 直播状态变更事件。
|
comment.focus | 无 | 聊天互动输入框点击事件。 |
comment.send | String | 发送评论事件。 |
comment.nickNameClick |
| 评论区昵称点击事件。
|
permission.need | 无 | 通过该事件判断是否需要弹出自定义登录框。 |
reservation.click | 无 | 立即预约按钮点击事件。 |
reservation.attend | String | 成功预约事件。 |
card.click |
| 菜单内的商品卡片点击事件。该事件仅在企业直播控制台配置跳转链接后才会触发。
|
floatingCard.click |
| 浮窗商品卡片点击事件。该事件仅在企业直播控制台配置跳转链接后才会触发。
|
lottery.click |
| 抽奖入口点击事件。 |
lottery.attend |
| 参与抽奖事件。 |
lottery.result |
| 抽奖开奖事件。仅当抽奖开奖时用户在线,才会触发该事件。
|
lottery.winInfo |
| 提交中奖信息事件。
说明 是否返回手机号和收货地址取决于您在控制台的配置。 |
lotteryTicket.click |
| 领取奖券奖品点击事件。
|
taskAwardPanel.pop |
| 抽奖面板弹出事件。
|
taskAwardBox.click |
| 累计观看抽奖中奖结果点击事件。
|
share.click | 无 | 分享点击事件。在PC 端单击分享,移动端点击复制链接或保存二维码时会触发该事件。 |
poster.click | 无 | 邀请海报点击事件。 |
adFloating.click |
| 浮标广告点击事件。该事件仅在企业直播控制台配置跳转链接后才会触发。 |
adMiddle.click |
| 页中广告点击事件。该事件仅在企业直播控制台配置跳转链接后才会触发。 |
adAccount.click |
| 主播账号点击事件。该事件仅在企业直播控制台配置跳转链接后才会触发。 |
ready | 无 | SDK 初始化完成事件,但并不代表播放器已经开始播放视频。 |
menu.click |
| 菜单栏点击事件。
|
thumbs.click |
| 直播间点赞事件。 |
permissionMode2.need | 无 | 通过该事件判断是否需要将 |
feature.click |
| 互动功能按钮点击事件。您可以通过设置
|
webSDK.on('error', (code, message, data) => {});
code
指错误码,message
指错误信息,data
指错误数据。
错误码 | 错误信息 | 错误数据 | 排查方法 |
---|---|---|---|
101 | 初始化失败,缺少必要参数 | 初始化配置 | 确保 |
102 | token 校验失败 | API 报错信息 | 确保 |
103 | 未找到对应的渲染父节点 | 父节点 ID | 确保 |
104 | 模块渲染失败 | 模块名称、报错 stack、报错信息 | 无 |
105 | 未找到对应的组件 | 父节点 ID | 确保 |
106 |
| 无 | 确保 |
201 | 直播间信息获取失败 | 请求数据 | 无 |
203 | 直播间暂未通过审核 | 无 | 确保直播间在企业直播控制台通过直播审核 |
204 | 直播间重复登录 | 无 | 无 |
webSDK.emit('comment.send', '企业直播');
事件 key | 请求参数 | 描述 |
---|---|---|
player.play | 无 | 播放事件。 |
player.pause | 无 | 暂停播放事件。 |
player.pip |
| PC 端小窗模式变化事件。
|
说明
本章节仅适用于在观看页展示直播间的场景。
事件 key | 请求参数 | 描述 |
---|---|---|
comment.send | String | 发送评论事件。 |
webSDK.destroy();
API | 请求参数 | 描述 |
---|---|---|
getPlayerInstance | 无 | 获取播放器实例。 |
sendDanmu |
| 发送弹幕。
|
seekVideo |
| 跳转到预告或回放的某个时间点。单位:秒。 说明 从未播放过的视频在 iOS 微信端无法通过该 API 跳转播放。 |
getVodPlayInfo | 无 | 获取点播视频(预告和回放)的播放信息。
|
switchLanguage |
| 切换至指定观看页语言。
|
switchChannel |
| 当直播状态为直播中时,切换至指定直播频道。当直播状态为回放时,切换至指定回放视频。 |
getPageLanguage | 无 | 获取观看页支持的语言以及当前的观看页语言。
|
requestPip | Boolean | 开启或关闭 PC 端的画中画模式。
|
说明
本章节仅适用于在观看页展示直播间的场景。
API | 请求参数 | 描述 |
---|---|---|
destroy | 无 | 销毁 SDK。 说明 如果当前观看页不再需要使用 SDK,可调用该方法销毁 SDK 释放资源,但不建议在销毁 SDK 后再对 SDK 进行重建。如果需要再次使用 SDK,建议在新的观看页集成 SDK 而不是销毁并重建 SDK。 |
updateModulesConf |
| 动态更新 SDK 部分配置。 |
updateMode2Token | String | 更新公开权限 Token( |
getActivityInfos | String | 获取页头图、页头广告以及移动端背景图、背景色的控制台配置信息。
|