配置参数--企业直播-火山引擎

文档中心

企业直播

SDK API 参考

配置参数

SDKConf

SDK 初始化参数，用于在观看页展示直播间。

说明

SDK 的配置优先级高于企业直播控制台和服务端 OpenAPI 的配置。

配置项	类型	是否必选	默认值	说明
service	string	是	`不适用`	服务名称，仅用于标记。企业直播技术支持会在配置白名单后，向您同步该参数值。
activityId	number	是	`不适用`	直播间的活动 ID。您可通过调用 CreateActivityAPIV2 或 ListActivityAPI 接口获取活动 ID，也可以在企业直播控制台的直播间左上角获取活动 ID。一个直播间对应一个 activityId。
videoRoomId	number	否	`不适用`	点播间 ID。
token	string	是	`不适用`	用户进入直播间时的授权 Token。`token` 与 `signToken` 至少需传入其中一个参数；当两者同时传入时，以 `signToken` 为准。不同鉴权模式（`mode`）下，`token` 的获取方式不同： `mode` 取值为 `1` 时，您可通过调用 GetSDKTokenAPI 接口获取用户 Token，也可以在企业直播控制台直播间内的观看页管理 > 页面嵌入 > Web SDK嵌入中获取用户 Token。 `mode` 取值为 `2` 时，您可通过调用 GetSDKTokenAPI 接口获取用户 Token。
signToken	string	是	`不适用`	用户进入直播间或点播间的授权 Token。`token` 与 `signToken` 至少需传入其中一个参数；当两者同时传入时，以 `signToken` 为准。不同鉴权模式（`mode`）下，`signToken` 的获取方式不同。详情参考获取直播间登录秘钥中使用说明一节。
mode	1 \| 2	否	`1`	鉴权模式。取值如下： `1`：公开模式。观众以游客身份进入直播间，在点击评论输入框或参与抽奖等需要用户信息的场景下，需要先完成游客注册（即输入昵称或通过手机号登录直播间）。 `2`：自定义模式。观众在进入直播间时使用的是在您 Web 应用内的用户信息，因此可以直接发送评论、参与抽奖等。
modules	Module[]	否	`[{mode: 'player', id: 'bytelive-default-player'}]`	模块配置。不配置，则默认创建一个页面元素 ID 为 `bytelive-default-player` 的播放器模块。
options	Partial<baseOptions> \| Partial<playerOptions>	否	-	可选配置项。说明此处 `baseOptions` 和 `playerOptions` 仅用于分类，实际配置时请使用 `options`。

Module

模块配置相关参数。

配置项类型是否必选默认值说明

配置项	类型	是否必选	默认值	说明
mode	string	是	`不适用`	模块名称。取值如下： `player`：播放器模块。PC 端建议最小宽度为 640 px。 `menu` ：菜单模块。支持聊天互动、图文介绍、商品卡片、互动工具、互动问答、内嵌链接、邀请榜单菜单。支持渲染多个菜单类型。PC 端建议最小宽度为 320 px。说明支持根据控制台的开关状态，判断是否在观看页展示商品卡片或互动工具菜单。 `lines`：多线路模块。高度自适应，您无需指定高度。 `mobile`：移动端横屏模式整页模块。已组装播放器、多线路和菜单模块。仅支持移动端，不支持与其他模块共用。查看 Demo 效果。 `mobile-portrait`：移动端竖屏模式整页模块。已组装播放器、多线路和菜单模块。仅支持移动端，类似于抖音直播的竖屏直播场景，不支持与其他模块共用。查看 Demo 效果。说明参数值设置为 `player`、`menu` 或 `lines` 时，仅可接入对应模块的功能。移动端如需接入直播预约、主播账号、页头图等非特定模块所属的功能，可将参数值设置为 `mobile` 或 `mobile-portrait` 接入整页模块。
menu	string[]	否	无	显示的菜单类型。例如设置参数值为 `["comment", "imagetext"]`，显示聊天互动和互动工具菜单。默认显示所有菜单类型。仅在 `modules.mode`=`menu` 或移动端横屏整页 `modules.mode`=`mobile` 时生效。取值如下： `comment`：聊天互动菜单。 `imagetext`：互动工具菜单。 `cardlist`：商品卡片菜单。 `bandcontent`：图文介绍菜单。 `session`：互动问答菜单。 `embeddedurl`：内嵌链接菜单。 `invitelist`：邀请榜单菜单。
id	string	是	`不适用`	页面元素 ID，指定模块需要渲染的位置和大小。

mode

string

是

不适用

模块名称。取值如下：

player：播放器模块。PC 端建议最小宽度为 640 px。
menu ：菜单模块。支持聊天互动、图文介绍、商品卡片、互动工具、互动问答、内嵌链接、邀请榜单菜单。支持渲染多个菜单类型。PC 端建议最小宽度为 320 px。

说明

支持根据控制台的开关状态，判断是否在观看页展示商品卡片或互动工具菜单。

lines：多线路模块。高度自适应，您无需指定高度。
mobile：移动端横屏模式整页模块。已组装播放器、多线路和菜单模块。仅支持移动端，不支持与其他模块共用。查看 Demo 效果。
mobile-portrait：移动端竖屏模式整页模块。已组装播放器、多线路和菜单模块。仅支持移动端，类似于抖音直播的竖屏直播场景，不支持与其他模块共用。查看 Demo 效果。

说明

参数值设置为 player、menu 或 lines 时，仅可接入对应模块的功能。移动端如需接入直播预约、主播账号、页头图等非特定模块所属的功能，可将参数值设置为 mobile 或 mobile-portrait 接入整页模块。

string[]

否

无

显示的菜单类型。例如设置参数值为 ["comment", "imagetext"]，显示聊天互动和互动工具菜单。默认显示所有菜单类型。仅在 modules.mode=menu 或移动端横屏整页 modules.mode=mobile 时生效。取值如下：

comment：聊天互动菜单。
imagetext：互动工具菜单。
cardlist：商品卡片菜单。
bandcontent：图文介绍菜单。
session：互动问答菜单。
embeddedurl：内嵌链接菜单。
invitelist：邀请榜单菜单。

id string 是 不适用 页面元素 ID，指定模块需要渲染的位置和大小。

baseOptions

非播放器相关参数。

说明

此处 baseOptions 仅用于分类，实际配置时请使用 options。

配置项	类型	是否必选	默认值	说明
pcPlayerHeader	boolean	是	`false`	PC 端播放器上方是否展示直播名称、描述等信息。取值如下： `true`：展示。 `false`：不展示。
disabledLogin	boolean	否	`false`	是否禁用企业直播自带的登录体系。通常配合 permission.need 事件使用，禁用后您需自行处理用户登录流程。取值如下： `true`：禁用。 `false`：不禁用。
disableModifyNickname	boolean	否	`false`	是否禁用企业直播自带的昵称修改功能。通常配合 nickname.modify 事件使用，禁用后您需自定义昵称修改弹窗。取值如下： `true`：禁用。 `false`：不禁用。
origin	string	是	`"https://live.byteoc.com"`	业务请求域名。如无特殊需求，无需设置。
saveUserInfo	boolean	是	`true`	`mode` 取值为 `1` 时，是否缓存用户信息。取值如下： `true`：缓存。 `false`：不缓存。
mobileBackgroundTransparent	boolean	否	`false`	移动端背景是否透明。取值如下： `true`：透明，展示自有页面的背景图或背景色。 `false`：不透明。
enableMobileBackgroundImage	boolean	否	`false`	移动端是否展示背景图。只在整页模式下生效。取值如下： `true`：展示背景图。 `false`：不展示背景图。
mobileGetUserId	boolean	是	`true`	是否开启快速获取移动端用户 ID 的入口。开启后在页面左上角快速点击 5 次即可获取用户 ID。取值如下： `true`：开启。 `false`：不开启。
basicPolling	boolean	是	`true`	是否开启轮询 API 实时更新直播间信息。取值如下： `true`：开启。 `false`：不开启。
disableCardRedirect	boolean	否	`false`	是否禁用商品卡片点击跳转能力。通常配合 card.click 或 floatingcard.click 事件使用，禁用后您需自行处理跳转功能。取值如下： `true`：禁用。 `false`：不禁用。
disableAdFloatingRedirect	boolean	否	`false`	是否禁用浮标广告点击跳转能力。通常配合 adFloating.click 事件使用，禁用后您需自行处理跳转功能。取值如下： `true`：禁用。 `false`：不禁用。
disableAdMiddleRedirect	boolean	否	`false`	是否禁用页中广告点击跳转能力。通常配合 adMiddle.click 事件使用，禁用后您需自行处理跳转功能。取值如下： `true`：禁用。 `false`：不禁用。
disableAdHeaderRedirect	boolean	否	`false`	是否禁用页头广告点击跳转能力。通常配合 adHeader.click 事件使用，禁用后您需自行处理跳转功能。取值如下： `true`：禁用。 `false`：不禁用。
disableCoupon	boolean	否	`false`	是否禁用卡券领取弹窗。通常配合 coupon.click 事件使用，禁用后您需自行处理卡券弹窗及领取功能。取值如下： `true`：禁用。 `false`：不禁用。
disableAdAccountRedirect	boolean	否	`false`	是否禁用主播账号点击跳转能力。通常配合 adAccount.click 事件使用，禁用后您需自行处理跳转功能。取值如下： `true`：禁用。 `false`：不禁用。
lotteryIcon	LotteryIcon	否	-	抽奖图标。支持的图片格式与 `img` 标签支持的图片格式相同。
emojiIcon	string	否	无	PC 端表情面板入口的图标。参数值为图标的图片链接。支持的图片格式与 `img` 标签支持的图片格式相同。
moreActionExpandPc	boolean	否	`false`	是否在 PC 端聊天互动菜单下将更多图标内的选项作为图标展示。取值如下： `true`：作为图标展示。 `false`：不作为图标展示。
disableReservationCell	boolean	否	`false`	是否禁用预约弹窗。通常配合 reservation.click 事件使用。禁用后您需自行处理用户预约功能，即通过 `isReserved` 参数设置用户是否已预约并调用 updateModulesConf 方法更新预约状态。取值如下： `true`：禁用。 `false`：不禁用。
isReserved	boolean	否	无	用户是否已预约。取值如下： `true`：已预约。 `false`：未预约。
riskWarning	boolean	是	`true`	是否开启风险提示。取值如下： `true`：开启。 `false`：不开启。
disableLotteryTicketRedirect	boolean	否	`false`	是否禁用抽奖的奖券奖品点击跳转能力。通常配合 lotteryTicket.click 事件使用，禁用后您需自行处理跳转功能。取值如下： `true`：禁用。 `false`：不禁用。
extra	string	否	`不适用`	同步至企业直播控制台的额外参数，可用于关联用户。例如设置参数值为`销售部`，将用户部门同步至企业直播控制台。
loginInToThumbUp	boolean	否	`false`	是否必须登录才能点赞直播间。取值如下： `true`：必须登录。如观众在未登录状态点赞直播间，会触发 permission.need 事件。 `false`：无需登录。
disableFeatureProcess	boolean \| string[]	否	`false`	在观众点击互动功能按钮后，是否阻止功能的后续执行。取值如下： `true`：阻止所有互动功能的后续执行。 `false`：不阻止任何互动功能的后续执行。 `String[]`：阻止指定互动功能的后续执行。例如设置参数值为 `['Comment','Gift']`，阻止评论功能和礼物打赏功能的后续执行。支持阻止以下互动功能的后续执行： `Comment`：评论功能。 `Gift`：礼物打赏功能。 `Lottery`：实时抽奖功能。 `Thumb`：评论点赞功能。 `Luckymoney`：红包功能。 `Reservation`：直播预约功能。 `Question`：互动问答功能。 `CheckIn`：签到功能。 `Vote`：投票功能。 `Questionnaire`：问卷功能。 `TaskAward`：累计观看抽奖功能。 `Coupon`：卡券功能。 `LiveBonus`：福利任务功能。 `Share`：直播分享功能。
disableFeature	Feature[]	否	-	禁用的功能。
useUserConnect	boolean	否	`false`	是否强制展示移动端连麦入口。取值如下： `true`：强制展示。 `false`：不强制展示。说明连麦功能使用了 WebRTC 技术，由于该技术的兼容性限制，仅在观众使用以下操作系统和浏览器时，默认展示移动端连麦入口。如需强制展示移动端连麦入口，可将参数值设置为 `true`。操作系统：Android 10 以上或 iOS 14.3 以上。浏览器：Google Chrome（Android 版本 78.0 以上、iOS 版本 86.0.4240 以上）、Safari 14 以上或微信内嵌浏览器。为保证连麦质量，如果观众使用的操作系统和浏览器不符合以上要求，推荐您在强制展示移动端连麦入口前，测试连麦功能在不同操作系统和浏览器下的表现。
hideUserConnect	boolean	否	`false`	是否强制隐藏移动端连麦入口。取值如下： `true`：强制隐藏。 `false`：不强制隐藏。说明连麦功能使用了 WebRTC 技术，由于该技术的兼容性限制，仅在观众使用以下操作系统和浏览器时，默认展示移动端连麦入口。如需强制隐藏移动端连麦入口，可将参数值设置为 `true`。操作系统：Android 10 以上或 iOS 14.3 以上。浏览器：Google Chrome（Android 版本 78.0 以上、iOS 版本 86.0.4240 以上）、Safari 14 以上或微信内嵌浏览器。
userConnectConfig	UserConnectConfig	否	无	连麦图标和背景配置。
customInteractionIcons	CustomInteractionIcons[]	否	-	在移动端横屏直播间，右下方互动工具浮窗图标的配置。
floatingInteractionIcons	FloatingInteractionIconConf[]	否	-	在移动端竖屏直播间，上方互动工具浮窗图标的配置。
preloadQuestionnaireAttended	boolean	否	无	是否禁止弹出发送时机为进入直播时的问卷。取值如下： `true`：禁止。 `false`：不禁止。
disableOfflineModal	boolean	否	无	是否禁止弹出多端登录踢出弹窗。取值如下： `true`：禁止。 `false`：不禁止。多端登录踢出弹窗如下所示：
disabledCommentConfig	{ disabled: boolean; placeholder?: string; }	否	无	设置是否禁用评论输入框，以及禁用后的评论输入框提示文字。 `disabled`：是否禁用评论输入框。取值如下： `true`：禁用。禁用后，观众点击评论输入框，无法输入内容。 `false`：不禁用。 `placeholder`：禁用后的评论输入框提示文字。
alwaysShowFloatingIcons	boolean	否	`false`	当移动端横屏直播间内无聊天互动菜单时，是否展示浮窗商品卡片以及互动工具浮窗。取值如下： `true`：在左侧第一个菜单下展示。 `false`：不展示。说明如果开启了聊天互动菜单，则在聊天互动菜单下展示浮窗商品卡片以及互动工具浮窗。
disableCommentPopup	boolean	否	`false`	是否禁用聊天互动菜单下的聊天回复弹窗。取值如下: `true`：禁用。PC端观众右键单击聊天或移动端观众点击昵称时,不再弹出聊天回复弹窗。观众无法回复、举报聊天等。 `false`：不禁用。
shopCartIcon	string	否	无	购物车图标配置。支持传入 Gif 或 PNG 格式图片，实现自定义购物车图标。
disabledShopCartClick	boolean	否	`false`	设置是否禁用购物车点击。取值如下： `true`：禁用购物车点击。禁用后，观众单击购物车图标时，不再弹出商品列表。 `false`：不禁用。
disabledShowExplainCard	boolean	否	`false`	设置是否禁止标记了商品讲解的商品卡片以浮窗形式展示在观看页。取值如下： `true`：禁止。禁止后，即使商品卡片标记了商品讲解，也不会展示在观看页。 `false`：不禁止。
disabledShowOrderMsg	boolean	否	`false`	设置是否禁用默认展示的下单消息，包括查看商品消息和下单购买消息。取值如下： `true`：禁用。禁用后，观看页将不再展示直播间的下单消息。 `false`：不禁用。
disableOrderMessageClick	boolean	否	`false`	设置是否禁用默认下单消息（包括查看商品消息和下单购买消息）的点击跳转行为。取值如下： `true`：禁用。禁用后，用户点击下单消息（包括查看商品消息和下单购买消息）不会触发默认跳转逻辑，而是会触发 `orderMsg.click` 事件。您需配合 orderMsg.click 事件自定义跳转链接。 `false`：不禁用。
disableCheckInUI	boolean	否	`false`	是否禁用签到弹窗。取值如下： `true`：禁用。禁用后将不会弹出签到弹窗。 `false`：不禁用。
disableLotteryUI	boolean	否	`false`	是否禁用抽奖弹窗。取值如下： `true`：禁用。禁用后观看页将不会弹出抽奖弹窗、抽奖结果弹窗以及开奖动画，您需配合award.receive事件自定义抽奖相关弹窗和动画。 `false`：不禁用。
independentConnectRenderDomId	string	否	无	独立挂载连麦功能的 DOM 标识符。若您在进行模块配置时，仅引入了播放器模块，您可使用该参数引入连麦功能。说明该参数仅在引入播放器模块后生效。要使用该参数，您需要在 HTML 中指定承载连麦功能的 DOM 容器，如：`<div id="connect"></div>`。然后将该 DOM 容器的 ID 传入该参数。

LotteryIcon

抽奖图标相关参数。

配置项	类型	是否必选	默认值	说明
attendIcon	string	否	无	未开奖时的抽奖图标。设置参数值为`0: '简体中文图片地址'`。如果您需要设置英文、日文、繁体中文的图标，将`0`分别替换为`1`、`2`、`3`，并替换相应语言的图片地址。
openIcon	string	否	无	已开奖时的抽奖图标。设置参数值为 `0: '简体中文图片地址'`。如果您需要设置英文、日文、繁体中文的图标，将 `0` 分别替换为 `1`、`2`、`3`，并替换相应语言的图片地址。

UserConnectConfig

连麦图标和背景配置参数。

配置项类型是否必选默认值说明

buttonIcon string 否无连麦图标的图片链接。支持的图片格式与 img 标签支持的图片格式相同。目前仅移动端 Web SDK 支持该参数。

配置项	类型	是否必选	默认值	说明
buttonIcon	string	否	无	连麦图标的图片链接。支持的图片格式与 `img` 标签支持的图片格式相同。目前仅移动端 Web SDK 支持该参数。
mainWindowContainerClassName	string	否	无	连麦主画面容器附加的 `className`。用于通过 CSS 自定义背景等样式覆盖。使用示例：（可选）若您在初始化进行模块配置时，仅引入了播放器模块，您需在 HTML 中指定承载连麦功能的 DOM 容器： `<div id="player"></div> <div id="connect"></div>` 初始化 SDK： `const webSDK = new window.ByteLiveWebSDK({ token: 'YOUR_TOKEN', activityId: 123456, mode: 1, modules: [ { id: "player", mode: "player", }, ], options: { // （可选）若您仅引入了播放器模块，您需使用该参数引入连麦功能 independentConnectRenderDomId: 'connect', userConnectConfig: { // 自定义连麦图标 buttonIcon: 'https://example.com/connect-icon.svg', // 自定义连麦主画面样式类名 mainWindowContainerClassName: 'custom-connect-container', }, }, });` 自定义 CSS 样式，样式类名与 `mainWindowContainerClassName` 参数值保持一致： `.custom-connect-container { background-image: url('https://example.com/connect-bg.png'); }`

mainWindowContainerClassName

string

否

无

连麦主画面容器附加的 className。用于通过 CSS 自定义背景等样式覆盖。

使用示例：

（可选）若您在初始化进行模块配置时，仅引入了播放器模块，您需在 HTML 中指定承载连麦功能的 DOM 容器：

<div id="player"></div>
<div id="connect"></div>

初始化 SDK：

const webSDK = new window.ByteLiveWebSDK({
token: 'YOUR_TOKEN',
activityId: 123456,
mode: 1,
modules: [
{
id: "player",
mode: "player",
},
],
options: {
// （可选）若您仅引入了播放器模块，您需使用该参数引入连麦功能
independentConnectRenderDomId: 'connect',
userConnectConfig: {
// 自定义连麦图标
buttonIcon: 'https://example.com/connect-icon.svg',
// 自定义连麦主画面样式类名
mainWindowContainerClassName: 'custom-connect-container',
},
},
});

自定义 CSS 样式，样式类名与 mainWindowContainerClassName 参数值保持一致：

.custom-connect-container {
background-image: url('https://example.com/connect-bg.png');
}

CustomInteractionIcons

互动工具浮窗相关参数。

配置项	类型	是否必选	默认值	说明
key	string	是	无	在移动端横屏直播间，右下方的互动工具浮窗的唯一标识。不带 `SYS:` 前缀时，表示新增一个外部自定义图标；使用 `SYS:` 前缀时，表示控制系统预设的内置图标。支持以下两类取值： 'SYS:LOTTERY'：系统抽奖图标。 'SYS:LUCKMONEY'：系统红包图标。 'SYS:QUESTION'：系统问答图标。 'SYS:IMAGE'：系统互动图片图标。 'SYS:VOTE'：系统投票图标。 'SYS:DOCUMENT'：系统文档图标。 'SYS:QUESTIONNAIRE'：系统问卷图标。 'SYS:CHECKIN'：系统签到图标。 'SYS:ANNOUNCEMENT'：系统公告图标。 'SYS:COUPON'：系统卡券图标。 'SYS:LIVEBONUS'：系统福利任务图标。
img	string	否	无	外部自定义互动工具浮窗的图片链接。支持的图片格式与 `img` 标签支持的图片格式相同。
text	string	否	无	外部自定义互动工具浮窗底部的文字。
index	number	否	无	互动工具浮窗的顺序。未设置时沿用默认展示顺序。
visible	boolean	否	`true`	互动工具浮窗是否展示。取值如下： `true`：展示互动工具浮窗。 `false`：隐藏互动工具浮窗，且不占据 HTML 空间。说明对于预设系统互动工具图标，只有在启用对应功能后，visible: true 才会生效；若未启用，即使设置为 true，图标也不会显示。

FloatingInteractionIconConf

互动工具浮窗图标的显示配置。

配置项类型是否必选默认值说明

配置项	类型	是否必选	默认值	说明
key	string	是	无	在移动端竖屏直播间上方，互动工具浮窗图标的唯一标识。当前支持对以下浮窗图标设置显示或隐藏： `SYS:COUPON`：系统卡券图标。 `SYS:LIVEBONUS`：系统福利任务图标。说明该参数仅在引入播放器模块后生效。
visible	boolean	否	`true`	是否显示该图标。取值如下： `true`：显示。 `false`：隐藏，不占据 HTML 空间。说明对于预设系统图标，只有在启用对应功能后，visible: true 才会生效；若未启用，即使设置为 true，图标也不会显示。

key

string

是

无

在移动端竖屏直播间上方，互动工具浮窗图标的唯一标识。当前支持对以下浮窗图标设置显示或隐藏：

SYS:COUPON：系统卡券图标。
SYS:LIVEBONUS：系统福利任务图标。

说明

该参数仅在引入播放器模块后生效。

visible

boolean

否

true

是否显示该图标。取值如下：

true：显示。
false：隐藏，不占据 HTML 空间。

说明

对于预设系统图标，只有在启用对应功能后，visible: true 才会生效；若未启用，即使设置为 true，图标也不会显示。

playerOptions

播放器相关参数。

说明

此处 playerOptions 仅用于分类，实际配置时请使用 options。

配置项	类型	是否必选	默认值	说明
disableProgressSeek	boolean	否	`false`	是否禁用用户通过进度条调整点播播放位置。取值如下： `true`：禁用。仅保留进度条展示，禁止用户在 PC 或移动端点击、拖拽进度条。 `false`：不禁用。用户可以点击或拖拽进度条进行跳转播放。说明该参数仅影响用户在播放器 UI 上对进度条的操作，不影响您侧过播放器实例主动调用 `seekVideo()` 方法实现跳转播放。
disablePlaybackRate	boolean	否	`false`	是否禁用用户调整点播播放倍速。取值如下： `true`：禁用。隐藏调整倍速的入口，用户无法通过播放器 UI 调整播放倍速。 `false`：不禁用。用户可以通过播放器 UI 调整播放倍速。说明该参数仅影响用户在播放器 UI 上的倍速操作，不影响您过播放器实例 `playbackRate` 属性主动设置倍速。
playerRetryTimes	number	否	`1`	播放器遇到网络异常后的重试次数。主备流切换并降级后，如果仍然无法播放，即当前重试失败。设置为 `0` 表示无数次重试。
videoFillMode	string	否	`auto`	播放器内视频的填充方式。取值如下： `cover`：保持视频原有宽高比例填充播放器，视频的宽高会填满播放器的宽高。如果视频宽高比与播放器宽高比不同，会有部分视频内容被裁剪掉。 `auto`：保持视频原有宽高比例填充播放器，视频的宽高会填满播放器的宽高。如果视频宽高比与播放器宽高比不同，视频会缩放显示。 `fill`：视频内容完全填充播放器，但视频宽高比可能发生变化。 `fillWidth`：拉伸视频宽度填满播放器宽度，视频高度不变。 `fillHeight`：拉伸视频高度填满播放器高度，视频宽度不变。该参数仅对 PC 端和移动端横屏模式生效。移动端竖屏模式视频的填充方式根据源流画面宽高比的不同而有所不同。效果详见竖屏直播间。
purePlayer	boolean	否	`false`	是否展示纯净播放器。纯净播放器指播放器内无进度条等互动按钮。取值如下： `true`：展示纯净播放器（播放器内无进度条等互动按钮）。 `false`：展示常规播放器。
playerBackgroundTransparent	boolean	是	`false`	播放器内未被画面填充部分的颜色是否为透明。取值如下： `true`：透明，显示为直播封面。 `false`：不透明，显示为黑色。
disablePlayerCover	boolean	是	`false`	是否禁用直播封面。取值如下： `true`：禁用直播封面，即显示为观看页面的背景图或背景色。 `false`：不禁用直播封面。
mobilePlayerIconIgnoreList	string[]	是	无	在移动端观看页的播放器上隐藏的功能入口。例如设置参数值为 `["language", "share"]`，隐藏切换语言和分享功能的入口。取值如下： `editNickname`：修改昵称。 `notification`：开启或关闭互动特效。 `language`：切换语言。 `share`：分享。
portraitMenuExtends	PortraitMenuConf[]	是	-	移动端竖屏直播间的图标或按钮。
landscapeMenuExtends	LandscapeMenuConf[]	是	-	移动端横屏直播间中，动态插入的自定义菜单页签。
landscapeInputBarIcons	LandscapeInputBarIconConf[]	是	-	移动端横屏直播间右下方的图标。
showChatInputCloseButton	boolean	否	`false`	在移动端横屏直播间中，是否在聊天互动输入框的输入状态下，展示关闭按钮。取值如下： `true`：展示关闭按钮，用户可点击按钮退出输入态。 `false`：不展示关闭按钮。
mobileGesture	MobileGesture	是	-	移动端播放器手势相关配置。说明由于 PC 端默认关闭手势，且不支持配置，平板在接入 PC 端 Web SDK 后，不支持通过手势操作。
mobileTopOffset	string	否	`0px`	设置移动端顶部避让距离，用于调整主播头像、公告等顶部区域的位置。支持传入纯数字字符串（按 px 处理）、百分比字符串（按 vh 处理）或带单位的 CSS 长度值。
showLikeInPlayer	boolean	否	`false`	是否将直播间点赞图标显示在播放器内。取值如下： `true`：显示在播放器内。默认显示在播放器右下角，您可以通过覆盖 `class` 属性 `bytelive-player-like-button` 的样式调整图标位置。 `false`：显示在评论区输入框右侧。
disableRotateFullscreen	boolean	否	`false`	是否禁用移动端旋转至横屏时会自动进入全屏模式。取值如下： `true`：禁用，旋转至横屏时不会自动进入全屏模式且不会有提示。 `false`：不禁用。
disableLivePauseButton	boolean	否	`false`	是否在直播期间隐藏播放器上的暂停按钮。取值如下： `true`：隐藏。 `false`：不隐藏。
rotateFullscreen	boolean	否	`false`	移动端 iOS 进入全屏模式后，视频是否自动切换为横屏播放。取值如下： `true`：视频自动切换为横屏播放。 `false`：视频根据设备朝向横屏或竖屏播放。
rotateFullscreenForAndroid	boolean	否	`false`	移动端 Android 进入全屏模式后，视频是否自动切换为横屏播放。取值如下： `true`：视频自动切换为横屏播放。 `false`：视频根据设备朝向横屏或竖屏播放。
fullscreenTarget	HTMLElement \| "video"	否	无	播放器全屏模式的容器元素。默认不传时，使用播放器 root 元素。取值如下：自定义 `HTMLElement`：传入一个自定义的 DOM 元素作为全屏容器。 `'video'`：仅使视频画面区域进入全屏。
defaultLiveLine	number	否	无	默认直播频道，即观众进入直播间时，观看页默认播放的直播频道。如未设置，则默认直播频道为频道语言与观众 PC 端浏览器语言或移动端系统语言相同的直播频道。例如取值 `0` 表示设置直播间的第一个直播频道为默认直播频道，取值 `1` 表示设置直播间的第二个直播频道为默认直播频道，以此类推。如果取值无法与直播间内的直播频道匹配，则播放器不在观看页展示。
liveLineChangeIcon	string \| HTMLElement	否	无	通过传入 DOM 字符串或 DOM 元素，自定义播放器内多线路切换的按钮文案或图标。例如，设置参数值为 `<div style="color: #fff">频道</div>`。
autoPlay	AUTOPLAY_OPTIONS	否	`AUTO_PLAY`	视频的自动播放模式。由于浏览器自动播放策略等限制，视频可能会转为静音自动播放或不自动播放。详见为什么直播或点播视频无法自动播放或者只能静音自动播放？。
watermarkConfig	WatermarkConfig	否	-	点播播放器的全屏水印。说明本参数仅适用于在观看页展示点播播放器的场景。
tickerConfig	TickerConfig	否	-	点播播放器的跑马灯。说明本参数仅适用于在观看页展示点播播放器的场景。
playerConf	PlayerConf	否	-	播放器交互相关配置。
keepPlayWhenPageHide	boolean	否	`false`	页面隐藏时是否保持视频播放。取值如下： `true`：页面隐藏时保持视频播放，不注册页面隐藏时的暂停插件。 `false`：页面隐藏时暂停视频播放。说明该参数仅在移动端生效。
softSolution	boolean	否	无	是否在移动端强制开启或关闭播放器软解解码直播视频。开启软解后可解决移动端部分浏览器或 App 下播放器被劫持的问题。取值如下： `true`：强制开启。 `false`：强制关闭。
autoplayFailedIcon	boolean	否	`true`	自动播放失败后，是否展示点击播放按钮。取值如下： `true`：展示点击播放按钮。 `false`：展示播放图标。
externalReport	ExternalReport	否	`不适用`	数据上报配置。详见 ExternalReport。
disablePlayer	boolean	否	`false`	是否禁用播放器。取值如下： `true`：禁用播放器。 `false`：初始化播放器。
isVodMsgOpen	boolean	否	`false`	是否开启回放中弹幕消息的透传，同时禁用播放器的弹幕渲染功能。取值如下： `true`：开启。开启后，SDK 将通过 im.playback.message 事件发送回放视频中的弹幕数据，而不在播放器画面上渲染弹幕。 `false`：关闭。SDK 将在播放器页面上直接渲染弹幕。
liveDefinitionTextMap	DefinitionTextMap	否	`详见 DefinitionTextMap`	直播间观看页面的清晰度名称。可用于自定义不同清晰度对应的文案。
vodDefinitionTextMap	DefinitionTextMap	否	`详见 DefinitionTextMap`	点播间观看页面的清晰度名称。可用于自定义不同清晰度对应的文案。
errorConfig	IErrorConfig	否	`{retryDuration: 300000, errorTipsText: '线路异常，请点击下方卡片切换其他线路'}`	当直播流因网络不稳定等原因发生中断时，通过此配置定义 SDK 的重试逻辑和提示信息。

PortraitMenuConf

移动端竖屏直播间的图标或按钮相关参数。使用示例可参考自定义竖屏直播间图标的样式和背景颜色。

配置项	类型	是否必选	默认值	说明
name	string	是	无	图标或按钮的名称。该名称仅在图标或按钮收纳在更多图标中时显示在图标或按钮下方。
icon	PortraitMenuIcon	否	-	竖屏直播间显示的图标。
render	string	否	无	竖屏直播间显示的图标或按钮。例如：`<div style="color: #fff">赞</div>`。
key	string	是	无	图标或按钮的唯一标识。支持以下两类取值：任意字符串：表示自定义图标或按钮的 key。 `SYS:*`：表示系统预设的图标或按钮 key。具体枚举如下： `SYS:HEART`：点赞图标。默认 index：5 `SYS:GIFT`：礼物图标。默认 index：15 `SYS:CART`：购物车图标。默认 index：10 `SYS:IMAGE_MENU`：图文介绍图标。默认 index：35 `SYS:IMAGETEXT_LIVE`：互动工具图标。默认 index：25 `SYS:SHARE`：分享图标。默认 index：45 `SYS:NOTIFICATION_SWITCH`：通知开关图标。默认 index：70 `SYS:NICKNAME_MODIFY`：昵称修改图标。默认 index：80 `SYS:LANGUAGE_SWITCH`：语言切换图标。默认 index：90 `SYS:SCREEN_CLEAN`：清屏图标。默认 index：100 `SYS:CANCEL_SCREEN_CLEAN`：取消清屏图标。默认 index：100 `SYS:DEFINITION_SWITCH`：清晰度图标。默认 index：95 `SYS:PLAYBACKRATE_SWITCH`：播放速度切换图标。默认 index：95 `SYS:GIFT_SWITCH`：礼物开关图标。默认 index：71 `SYS:EMBEDDED_URL`：内嵌链接图标。默认 index：40 `SYS:CONNECT`：申请连麦图标。 `SYS:PRIVATE_CHAT`：私聊互动图标。默认 index：30 `SYS:USERCREDIT`：表扬点赞图标。默认 index：50 `SYS:REPORT_ACTIVITY`：举报图标。默认 index：100 `SYS:VIDEO_UNDERSTANDING`：AI 总结图标。默认 index：75 说明为兼容旧版本，直接传入上述系统 `key` 裸值时也会按预设系统图标处理。
onClick	Function	否	无	点击事件回调。
visible	boolean	否	`true`	是否显示该图标或按钮。取值如下： `true`：显示。 `false`：隐藏，不占据 HTML 空间。说明对于预设系统图标，只有在启用对应功能后，`visible: true` 才会生效；若未启用，即使设置为 `true`，图标也不会显示。
index	number	是	`0`	图标或按钮的显示顺序。数值越大，越靠左显示。值大于 70 会收纳在更多图标内。如果图标和按钮总数超过 4 个（包括直播间内的默认图标），超过部分的图标或按钮会收纳在更多图标内。要查看系统预设图标或按钮的默认 `index` 值，查看上文 `key` 参数的描述。

LandscapeMenuConf

移动端横屏直播间中，自定义的动态菜单页签参数。使用示例可参考自定义横屏直播间的菜单。

配置项	类型	是否必选	默认值	说明
name	string	是	无	菜单页签的标题。
key	string	是	无	菜单页签的唯一标识。
onClick	Function	否	无	切换到该菜单页签时触发的回调。返回值即 key 的参数值。
index	number	是	`0`	菜单页签的显示顺序。数值越小越靠左。
tabPaneRootElement	string	是	无	TabPane 根节点选择器。仅支持 `#id` 格式。WebSDK 会在对应 TabPane 内容区内创建该根节点。
onCreated	`() => void`	否	无	当 WebSDK 成功创建并挂载 TabPane 根节点后触发的回调。
onFailed	`(reason: string) => void`	否	无	当创建失败时触发的回调。参数 `reason` 为失败原因。当前预设值如下： `unsupported_mode`：当前不是移动端横屏直播间，无法插入动态菜单页签。 `invalid_name`：`name` 为空或不是有效字符串。 `invalid_key`：`key` 为空或不是有效字符串。 `invalid_index`：`index` 不是有效数字。 `invalid_tab_pane_root_element`：`tabPaneRootElement` 非法，仅支持 `#id` 格式。 `duplicate_key`：`key` 与已有动态菜单页签重复。 `duplicate_tab_pane_root_element`：`tabPaneRootElement` 或对应根节点已存在。 `create_tab_pane_root_element_failed`：创建或挂载 TabPane 根节点失败。

LandscapeInputBarIconConf

移动端横屏直播间中，输入框右侧图标相关参数。

配置项	类型	是否必选	默认值	说明
key	string	是	无	图标的唯一标识。支持以下两类取值：任意字符串：表示自定义图标 `key`。 `SYS:*`：表示预设系统图标 `key`。系统图标枚举如下： `SYS:GIFT`：礼物图标。 `SYS:USERCREDIT`：表扬图标。 `SYS:CART`：购物车图标。 `SYS:THUMBS`：点赞图标。说明为兼容旧版本，直接传入上述系统 `key` 裸值时也会按预设系统图标处理。
visible	boolean	否	`true`	是否显示该图标。取值如下： `true`：显示。 `false`：隐藏，不占用 HTML 空间。说明对于预设系统图标，只有在启用对应功能后，`visible: true` 才会生效；若未启用，即使设置为 `true`，图标也不会显示。
index	number	否	无	图标的显示顺序。数值越小，越靠左显示。
img	string	否	无	自定义图标的图片链接。仅对自定义图标生效。支持的图片格式与 `img` 标签支持的图片格式相同。
onClick	`(key: string) => void`	否	无	点击事件回调。仅自定义图标生效。返回值即 key 的参数值。

MobileGesture

移动端播放器手势相关配置参数。

配置项类型是否必选默认值说明

配置项	类型	是否必选	默认值	说明
disableGesture	boolean	否	`false`	是否禁用移动端手势。禁用后，观众无法通过左右滑动预告或回放画面来拖动进度条。取值如下： `true`：禁用 `false`：不禁用

disableGesture

boolean

否

false

是否禁用移动端手势。禁用后，观众无法通过左右滑动预告或回放画面来拖动进度条。取值如下：

true：禁用
false：不禁用

PlayerConf

播放器交互相关配置参数。

配置项	类型	是否必选	默认值	说明
closeVideoDblclick	boolean	否	`false`	PC 端：是否禁用在双击播放器时，进入全屏模式。取值如下： `true`：禁用。双击播放器，不会进入全屏模式。 `false`：不禁用。双击播放器，进入全屏模式。移动端：是否禁用在双击播放器时，暂停或播放直播或点播内容。取值如下： `true`：禁用。双击播放器，不会暂停或播放直播或点播内容。 `false`：不禁用。双击播放器，暂停或播放直播或点播内容。
ignores	string[]	否	无	在观看页的播放器上隐藏的内置插件。取值如下： `play`：播放和暂停按钮。 `replay`：重播按钮。 `refresh`：刷新按钮。 `pip`：进入和退出画中画模式按钮。 `sdkerrorplugin`：错误页面。 `controls`：播放器控制栏。 `loading`：loading 动画。 `playnext`：播放下一个按钮。 `fullscreen`：进入和退出全屏按钮。 `volume`：音量按钮。例如设置参数值为`['play','pip','replay']` ，则观看页的播放器上不显示播放和暂停按钮、进入和退出画中画模式按钮和重播按钮。
closeVideoClick	boolean	否	`false`	是否禁用在 PC 端单击播放器时，暂停或播放直播或点播内容。取值如下： `true`：禁用。单击播放器，不会暂停或播放直播或点播内容。 `false`：不禁用。单击播放器，暂停或播放直播或点播内容。
showCursorOverPlayer	boolean	否	`false`	是否在播放器进入非活跃（inactive 状态）后，仍显示鼠标光标。取值如下： `true`：显示。播放器进入非活跃状态后，鼠标光标仍显示在播放器区域内。 `false`：不显示。保持播放器默认行为，进入非活跃状态后隐藏鼠标光标。说明该参数同时作用于 PC 端和移动端。
controls	{ autoHide?: boolean; mode?: "normal" \| "flex" \| "bottom"; initShow?: boolean; }	否	`autoHide：true；mode：flex；initShow：false`	播放器控制栏相关配置。例如播放和暂停按钮、进入和退出全屏按钮和音量按钮等。 `autoHide`：是否自动隐藏播放器控制栏。取值如下： `true`：隐藏。 `false`：不隐藏。 `mode`：播放器控制栏的布局方式。取值如下： `normal`：播放按钮分布于左右两边，进度条位于顶部。 `flex`：两侧播放按钮和进度条呈三排布局。 `bottom`：播放按钮分布于左右两边，进度条位于底部。 `initShow`：是否在播放器初始化时，显示播放器控制栏。取值如下： `true`：显示。在播放器初始化时，显示播放器控制栏。 `false`：不显示。在播放器开始播放直播或点播内容后，显示播放器控制栏。
icons	IIcon	否	-	播放器内各功能按钮的图标。
play	PluginConfigs	否	-	播放按钮相关设置。
pip	PluginConfigs	否	-	PC 端进入和退出画中画模式按钮相关设置。
refresh	PluginConfigs	否	-	刷新按钮相关设置。
fullscreen	PluginConfigs	否	-	进入和退出全屏按钮相关设置。
volume	PluginConfigs	否	-	音量按钮相关设置。
playbackrateV2	PluginConfigs	否	-	选择倍速按钮相关设置。
definitionV2	PluginConfigs	否	-	选择清晰度按钮相关设置。

SDKVodPlayerConf

SDK 初始化参数，用于在观看页展示点播播放器。

说明

SDK 的配置优先级高于企业直播控制台和服务端 OpenAPI 的配置。

配置项	类型	是否必选	默认值	说明
service	string	是	`不适用`	服务名称，仅用于标记。企业直播技术支持会在配置白名单后，向您同步该参数值。
modules	Module[]	否	`[{mode: 'player', id: 'bytelive-default-player'}]`	模块配置。不配置，则默认创建一个页面元素 ID 为 `bytelive-default-player` 的播放器模块。支持以下参数： `id`：页面元素 ID，指定模块需要渲染的位置和大小。 `mode`：模块名称。取值固定为 `player`，即播放器模块。PC 端建议最小宽度为 640 px。
vodPlayerToken	string	是	`不适用`	播放器 Token。您可通过调用 GetVodPlayerToken 接口获取 Token，也可以在企业直播控制台的媒资库 > 播放器设置页面获取 Token。
vodPlayerConfigId	string	否	-	观看页展示的点播播放器的 ID。您可通过调用 ListVodPlayerConfig 接口获取 ID，也可以在企业直播控制台的媒资库 > 播放器设置页面获取 ID。不配置，则展示默认点播播放器。
vid	string	是	`不适用`	视频 ID。您可通过调用 ListActivityMediaAPI 接口获取视频 ID，也可以在企业直播控制台的媒资库 > 视频管理 > 视频库页面获取视频 ID。
options	Partial<playerOptions>	否	-	可选配置项。

AUTOPLAY_OPTIONS

类型：enum

视频的自动播放模式。

属性	值	说明
AUTO_PLAY	`1`	非静音自动播放视频。但由于浏览器自动播放策略等限制，视频可能会转为静音自动播放或不自动播放。详见为什么直播或点播视频无法自动播放或者只能静音自动播放？。
MUTED_AUTO_PLAY	`2`	静音自动播放视频。但由于浏览器自动播放策略等限制，视频可能不会自动播放。
NO_AUTO_PLAY	`3`	不自动播放视频。观众必须手动点击播放视频。

WatermarkConfig

类型：interface

自定义的全屏水印配置。

Content

类型：string

全屏水印内容。

TickerConfig

类型：interface

自定义的跑马灯配置。

Content

类型：string

跑马灯内容。

最近更新时间：2026.06.18 17:21:13

这个页面对您有帮助吗？

有用

无用

企业直播

SDKConf #

Module #

baseOptions #

LotteryIcon #

UserConnectConfig #

CustomInteractionIcons #

FloatingInteractionIconConf #

playerOptions #

PortraitMenuConf #

LandscapeMenuConf #

LandscapeInputBarIconConf #

MobileGesture #

PlayerConf #

SDKVodPlayerConf #

AUTOPLAY_OPTIONS #

WatermarkConfig #

Content #

TickerConfig #

Content #

SDKConf

Module

baseOptions

LotteryIcon

UserConnectConfig

CustomInteractionIcons

FloatingInteractionIconConf

playerOptions

PortraitMenuConf

LandscapeMenuConf

LandscapeInputBarIconConf

MobileGesture

PlayerConf

SDKVodPlayerConf

AUTOPLAY_OPTIONS

WatermarkConfig

Content

TickerConfig

Content