文档中心

企业直播

Web 观播 SDK

集成 Web 观播 SDK

Web 观播 SDK 提供看直播、发评论、参与抽奖等功能。本文介绍 Web 观播 SDK 的集成方法。

前提条件

您已开通尊享版套餐。详见计费说明。
由于 Web 观播 SDK 的 API 不支持跨域调用，在集成 Web 观播 SDK 前，您需参考Web SDK 配置将您使用的域名 URL 加入白名单。

功能支持

Web 观播 SDK 支持的功能情况，详见功能列表。

配置重试机制

由于网络抖动或运营商域名劫持等原因，Web 观播 SDK 的静态资源有较小概率加载失败，导致 Web 观播 SDK 初始化失败。为避免此情况，提高 SDK 静态资源加载的稳定性，在使用 SDK 之前，您需配置资源加载重试机制。在静态资源加载失败时，系统将通过多个域名进行重试，最多可重试 9 次。

原生 Web 集成

UniApp 集成

如果您是原生 Web 场景，请将以下代码添加到 HTML 的 <head> 标签中：

<html>
  <head>
    <script>
      function _slicedToArray(e,r){return _arrayWithHoles(e)||_iterableToArrayLimit(e,r)||_unsupportedIterableToArray(e,r)||_nonIterableRest()}function _nonIterableRest(){throw new TypeError("Invalid attempt to destructure non-iterable instance.
In order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}function _unsupportedIterableToArray(e,r){if(e){if("string"==typeof e)return _arrayLikeToArray(e,r);var t=Object.prototype.toString.call(e).slice(8,-1);return"Object"===t&&e.constructor&&(t=e.constructor.name),"Map"===t||"Set"===t?Array.from(e):"Arguments"===t||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t)?_arrayLikeToArray(e,r):void 0}}function _arrayLikeToArray(e,r){(null==r||r>e.length)&&(r=e.length);for(var t=0,n=new Array(r);t<r;t++)n[t]=e[t];return n}function _iterableToArrayLimit(e,r){var t=null==e?null:"undefined"!=typeof Symbol&&e[Symbol.iterator]||e["@@iterator"];if(null!=t){var n,o,i,a,u=[],f=!0,c=!1;try{if(i=(t=t.call(e)).next,0===r){if(Object(t)!==t)return;f=!1}else for(;!(f=(n=i.call(t)).done)&&(u.push(n.value),u.length!==r);f=!0);}catch(e){c=!0,o=e}finally{try{if(!f&&null!=t.return&&(a=t.return(),Object(a)!==a))return}finally{if(c)throw o}}return u}}function _arrayWithHoles(e){if(Array.isArray(e))return e}!function(e,r){"object"==typeof exports&&"undefined"!=typeof module?module.exports=r():"function"==typeof define&&define.amd?define(r):(e="undefined"!=typeof globalThis?globalThis:e||self).vcloudAssetsRetry=r()}(this,(function(){"use strict";var e="retryTimes",r="succeeded",t="failed",n="maxRetryCount",o="onRetry",i="onSuccess",a="onFail",u="domain",f="styleImageNoImportant",c="data-assets-retry-hooked",l="data-assets-retry-ignore",s="data-retry-id",d=window,y=window.document,h=d.HTMLElement,v=d.HTMLScriptElement,g=d.HTMLStyleElement,p=d.HTMLLinkElement,m=d.HTMLImageElement,b=function(e){return e},A=function(){},E=function(e,r,t){var n=e.indexOf(r);return-1===n?e:e.substring(0,n)+t+e.substring(n+r.length)},T=function(e){return[].slice.call(e)},w=function(e,r){var t=arguments.length>2&&void 0!==arguments[2]?arguments[2]:A,n=arguments.length>3&&void 0!==arguments[3]&&arguments[3]||e.defer||e.async;if("loading"!==y.readyState||/Edge|MSIE|rv:/i.test(navigator.userAgent)||n){var o=y.createElement("script");Object.keys(v.prototype).forEach((function(r){if("src"!==r&&e[r]&&"object"!=typeof e[r])try{o[r]=e[r]}catch(e){}})),o.src=r,o.onload=e.onload,o.onerror=e.onerror,o.setAttribute(s,L());var i=e.getAttribute("nonce");i&&o.setAttribute("nonce",i),y.getElementsByTagName("head")[0].appendChild(o)}else{var a=L(),u=e.outerHTML.replace(/data-retry-id="[^"]+"/,"").replace(/src=(?:"[^"]+"|.+)([ >])/,`${s}=${a} src="${r}"$1`);y.write(u);var f=y.querySelector(`script[${s}="${a}"]`);f&&(f.onload=t)}},j=function(e){try{return e.rules}catch(r){try{return e.cssRules}catch(e){return null}}},I=function(e,r,t){var n=y.createElement("link");Object.keys(p.prototype).forEach((function(r){if("href"!==r&&e[r]&&"object"!=typeof e[r])try{n[r]=e[r]}catch(e){}})),n.href=r,n.onload=t||e.onload,n.onerror=e.onerror,n.setAttribute(s,L()),y.getElementsByTagName("head")[0].appendChild(n)},S=function(e){return e?e instanceof h?[e.nodeName,e.src,e.href,e.getAttribute(s)].join(";"):"not_supported":"null"},L=function(){return Math.random().toString(36).slice(2)},O=function(e){return e instanceof v||e instanceof m?e.src:e instanceof p?e.href:""},_={},k=function(e){return Array.isArray(e)?e.reduce((function(e,r,t,n){return e[r]=n[(t+1)%n.length],e}),{}):e},$=function(e,r){return e.substr(e.indexOf(r)+r.length,e.length)},x=function(e,r){return Object.keys(r).filter((function(r){return e.indexOf(r)>-1})).sort((function(e,r){return r.length-e.length}))[0]},M=function(n,o){var i=R(n,o),a=i[0],u=i[1];return a?(_[a]=_[a]||{[e]:0,[t]:[],[r]:[]},[u,_[a]]):[]},R=function(e,r){var t=x(e,r);return t?[$(e,t),t]:["",""]},H={};var N={},C=[],B=function(e,r){var t=["backgroundImage","borderImage","listStyleImage"];e.forEach((function(e){var n=j(e);if(null!==n){var i=T(n);i.forEach((function(n){t.forEach((function(t){!function(e,r,t,n,i){var a,f=i[u],c=i[o],l=null==(a=null==r?void 0:r.style)?void 0:a[e];if(l&&!/^url(["']?data:/.test(l)){var s=(l.match(/^url(["']?(.+?)["']?)/)||[])[1];if(s){var d=x(s,f);if(d){for(var y=d,h={[y]:!0};y&&f[y];){var v=f[y];if(h[v])break;h[v]=!0,y=v}var g=Object.keys(h).map((function(e){var r=E(s,d,e),t=c(r,s,null);return t?`url("${t}")`:null})).filter(Boolean).join(","),p=r.selectorText+`{ ${function(e){return e.replace(/([a-z])([A-Z])/g,(function(e,r,t){return`${r}-${t.toLowerCase()}`}))}(e)}: ${g} ${i.styleImageNoImportant?"":"!important"}; }`;try{t.insertRule(p,n.length)}catch(v){t.insertRule(p,0)}}}}}(t,n,e,i,r)}))})),e.href&&(N[e.href]=!0),e.ownerNode instanceof g&&C.push(e.ownerNode)}}))},W=function(e,r){return T(e).filter((function(e){if(!function(e){return!!j(e)}(e))return!1;if(!e.href){var t=e.ownerNode;return!(t instanceof g&&C.indexOf(t)>-1)}return!N[e.href]&&!!x(e.href,r)}))};return function(){var h=arguments.length>0&&void 0!==arguments[0]?arguments[0]:{};try{if("object"!=typeof h[u])throw new Error("opts.domain cannot be non-object.");var g=[a,u,"retryAsync",o,i,n,f],$=Object.keys(h).filter((function(e){return-1===g.indexOf(e)}));if($.length>0)throw new Error("option name: "+$.join(", ")+" is not valid.");var x={[n]:h[n]||3,[o]:h[o]||b,[i]:h[i]||A,[a]:h[a]||A,[u]:k(h[u]),[f]:h[f]||!1};return function(f){var d=f[o],h=f[i],g=f[a],b=f[u],A=function(r){if(r){var o=r.target||r.srcElement,i=O(o);if(i){var a=M(i,b),u=a[0],y=a[1],h=o instanceof HTMLElement&&o.hasAttribute(l);if(y&&u&&!h){y[e]++,y[t].push(i);var A=y[e]>f[n];if(A){var T=R(i,b)[0];g(T)}if(b[u]&&!A){var j=b[u],_=E(i,u,j),k=d(_,i,y);if(null!==k){if("string"!=typeof k)throw new Error('a string should be returned in "onRetry" function');if(o instanceof m&&o.src)return o.setAttribute(s,L()),void(o.src=k);var $=S(o);if(!H[$]){if(H[$]=!0,o instanceof v&&!o.getAttribute(c)&&o.src)return void w(o,k);if(o instanceof p&&!o.getAttribute(c)&&o.href)return void I(o,k)}}}}}}};y.addEventListener("error",A,!0),y.addEventListener("load",(function(e){if(e){var t=e.target||e.srcElement,n=O(t);if(n){var o=M(n,b)[1],i=_slicedToArray(R(n,b),1)[0],a=function(){o&&o[r].push(n),h(i)};if(t instanceof p){if(y.styleSheets){var u=T(y.styleSheets).filter((function(e){return e.href===t.href}))[0],f=j(u);if(null!==f){if(0===f.length)return void A(e);a()}}}else a()}}}),!0)}(x),function(e){var r=y.styleSheets,t=e[u];if(!r)return!1;setInterval((function(){var r=W(y.styleSheets,t);r.length>0&&B(r,e)}),250)}(x),_}catch(g){d.console&&console.error("[assetsRetry] error captured",g)}}}));
    </script>
    <script>
      try {
        window.vcloudAssetsRetry({
            domain: ['unpkg.byted-static.com', 'lf-cdn-tos.bytescm.com/obj/unpkg', 'lf-livesaas.volccdn.com/obj/unpkg'],
            maxRetryCount: 9,
        })
        window.vcloudAssetsRetry({
          domain: ['mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client', 'lf-livesaas.volccdn.com/obj/vcloud-fe/livesaas-client', 'lf3-cm.ecombdstatic.com/obj/vcloud-fe/livesaas-client'],
          maxRetryCount: 9,
        })
      } catch(_e) {}
    </script>
  </head>

如果您是 UniApp 集成场景，直接将重试脚本内联到 index.html 中可能导致构建失败。您需将重试脚本保存为独立 JS 文件后再引入。请参考以下步骤完成配置。

下载 assets-retry.js 文件，并将该文件放入项目的静态资源目录中：
assets-retry.js
未知大小

在项目的 index.html 中，通过 <script> 标签引入重试脚本：

<script src="[您的静态资源访问前缀]/assets-retry.js"></script>

初始化重试机制：

<script>
try {
  window.vcloudAssetsRetry({
    domain: [
      'unpkg.byted-static.com',
      'lf-cdn-tos.bytescm.com/obj/unpkg',
      'lf-livesaas.volccdn.com/obj/unpkg'
    ],
    maxRetryCount: 9,
  })

  window.vcloudAssetsRetry({
    domain: [
      'mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client',
      'lf-livesaas.volccdn.com/obj/vcloud-fe/livesaas-client',
      'lf3-cm.ecombdstatic.com/obj/vcloud-fe/livesaas-client'
    ],
    maxRetryCount: 9,
  })
} catch (_e) {}
</script>

集成方法

完成以下步骤，将观播 SDK 集成到您的 Web 应用中。推荐您使用 byted-livesaas-dev Skill 快速集成。

步骤一：引入 SDK 资源

您可选择使用 WebSDK Loader 接入，或手动指定 SDK 版本接入。推荐您使用 WebSDK Loader 加载观播 SDK。

（推荐）方式一：使用 WebSDK Loader 接入

WebSDK Loader 用于统一加载 Web 观播 SDK，可降低 SDK 接入、升级和问题排查成本。接入后，Loader 会前置加载稳定性监控能力，在 SDK 资源加载失败、初始化失败等异常发生时更早采集诊断日志，便于定位与解决问题；在您允许远程升级的前提下，Loader 可自动选择经过灰度验证的稳定版本，减少手动修改版本号和重新发版的成本，并支持快速回滚和异常自动兜底到稳定版本。
Loader 仅负责稳定性监控、版本决策和资源调度。接入时，您只需引入一个 Loader script，并在初始化 Web 观播 SDK 前等待 Loader 加载完成，无需在页面中手动引入 Web 观播 SDK 的 CSS 和 JS 资源。接入前，您可以结合 Loader 的体积和加载耗时评估对页面性能的影响。
参考以下代码，在本地项目工程的 index.html 文件内引入 WebSDK Loader。

<script
      id="livesaas-websdk-loader-script-tag"
      src="https://unpkg.byted-static.com/byted/livesaas-websdk-loader/1.0.3/dist/index.min.js"
      defer
      crossorigin="anonymous"
      data-access-type="mobile"
      data-fallback-version="2.1.55"
      data-allow-remote-update-sdk-version="true"
      data-decision-service-endpoint="https://live.byteoc.com/apiservice/websdk-loader-decision"
      data-fetch-timeout-ms="3000"
      data-live-activity-id="1815732009407497"
    ></script>

参数说明如下所示：

参数	是否必填	说明
`id`	是	Loader script 标签的唯一标识。固定取值为 `livesaas-websdk-loader-script-tag`。
`src`	是	WebSDK Loader 的资源地址。固定取值为 `https://unpkg.byted-static.com/byted/livesaas-websdk-loader/1.0.3/dist/index.min.js`。
`crossorigin`	否	跨域资源加载配置。固定取值为 `anonymous`，表示发起不携带用户凭证的跨域请求，便于浏览器按跨域资源规则加载 Loader。
`data-access-type`	是	接入终端资源的类型。可取值： `pc`：PC 端，仅支持模块化接入 `player-pc`：PC 端（单独接入播放器模块，仅支持点播、直播、清晰度、倍速以及多线路等播放器相关功能。性能优于 PC 端模块化接入方式） `mobile`：移动端，支持模块化接入或整页接入 `mobile-all`：移动端，仅支持整页接入，性能优于其他移动端整页接入方式 `player-mobile`：移动端（单独接入播放器模块，仅支持点播、直播、清晰度、倍速以及多线路等播放器相关功能。性能优于其他移动端模块化接入方式）注意如需在观看页展示点播播放器，则必须采用单独接入播放器模块的方式。如需在同一页面展示多个直播或点播播放器，则必须采用单独接入播放器模块的方式。具体实现，详见多实例接入。建议平板接入 PC 端的 Web SDK，以获得更佳的视觉效果。移动端如需接入直播预约、主播账号、页头图等非特定模块所属的功能，可采用整页接入方式。
`data-allow-remote-update-sdk-version`	否	是否允许远程升级至稳定版本。默认为 `false`。取值如下： `false`：不允许远程升级至稳定版本。您需手动修改版本号和重新发版。 `true`：允许远程升级至稳定版本。Loader 将自动选择经过灰度验证的最新稳定版本，减少您手动修改版本号和重新发版的成本。若您有定制化的版本需求，可联系技术支持，通过 `data-live-activity-id`、`data-live-account-id` 和 `data-uuid` 参数指定对应的直播活动 ID、账号 ID 和观众 ID，以便我们为您定制化升级至稳定版本。
`data-fallback-version`	是	当 `data-allow-remote-update-sdk-version` 取值为 `false` 或资源加载异常时，兜底使用的 Web 观播 SDK 版本。
`data-load-timeout-ms`	否	单次资源加载超时时间，单位为毫秒。默认为 `3000`。说明该参数仅在 `data-allow-remote-update-sdk-version` 为 `true` 时生效。
`data-live-account-id`	否	企业直播账号 ID。若您有定制化的版本需求，可联系技术支持，通过本参数指定企业直播账号。说明该参数仅在 `data-allow-remote-update-sdk-version` 为 `true` 时生效。
`data-live-activity-id`	否	直播间活动 ID。若您有直播间维度的定制化版本需求，可联系技术支持，通过本参数指定直播间。说明该参数仅在 `data-allow-remote-update-sdk-version` 为 `true` 时生效。
`data-uuid`	否	观众的唯一标识。若您有观众维度的定制化版本需求，可联系技术支持，通过本参数指定观众。说明该参数仅在 `data-allow-remote-update-sdk-version` 为 `true` 时生效。

方式二：手动指定版本接入

参考以下代码，在本地项目工程的 index.html 文件内引入样式文件和脚本文件。
国内域名：https://mediaservice-fe.volccdn.com/obj/vcloud-fe
注意事项

如需在观看页展示点播播放器，则必须采用单独接入播放器模块的方式。
如需在同一页面展示多个直播或点播播放器，则必须采用单独接入播放器模块的方式。具体实现，详见多实例接入。
建议平板接入 PC 端的 Web SDK，以获得更佳的视觉效果。
移动端如需接入直播预约、主播账号、页头图等非特定模块所属的功能，可采用整页接入方式。

// PC 端（仅支持模块化接入）
<link rel="stylesheet" href="https://mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client/pc/css/index.2.1.59.css">
<script src="https://mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client/pc/js/index.2.1.59.js"></script>

// PC 端（单独接入播放器模块，仅支持点播、直播、清晰度、倍速以及多线路等播放器相关功能。性能优于 PC 端模块化接入方式）
<link rel="stylesheet" href="https://mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client/player-pc/css/index.2.1.59.css">
<script src="https://mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client/player-pc/js/index.2.1.59.js"></script>

// 移动端（支持模块化接入或整页接入）
<link rel="stylesheet" href="https://mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client/mobile/css/index.2.1.59.css">
<script src="https://mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client/mobile/js/index.2.1.59.js"></script>

// 移动端（仅支持整页接入，性能优于其他移动端整页接入方式）
<link rel="stylesheet" href="https://mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client/mobile-all/css/index.2.1.59.css">
<script src="https://mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client/mobile-all/js/index.2.1.59.js"></script>

// 移动端（单独接入播放器模块，仅支持点播、直播、清晰度、倍速以及多线路等播放器相关功能。性能优于其他移动端模块化接入方式）
<link rel="stylesheet" href="https://mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client/player-mobile/css/index.2.1.59.css">
<script src="https://mediaservice-fe.volccdn.com/obj/vcloud-fe/livesaas-client/player-mobile/js/index.2.1.59.js"></script>

步骤二：初始化 SDK

资源引入后， ByteLiveWebSDK 挂载在 window 下。您可以通过以下方式，将观播 SDK 集成到您的 Web 应用中，从而在观看页展示直播间或点播播放器。有关代码中的参数配置，详见配置参数。有关监听与触发事件，详见事件。有关方法调用，详见属性及方法。

如果您使用 WebSDK Loader 接入，需要先等待 Loader 完成版本决策、资源加载和异常兜底后，再初始化 ByteLiveWebSDK。初始化代码如下所示：

window.LiveSaaSWebSDKLoader.ready()
  .then(function () {
    var webSDK = new window.ByteLiveWebSDK({
      activityId: 169410856822****,
      token: 'JC****',
      service: "Demo",
      mode: 1,
      modules: [
        {
          id: "player", // 接入方页面内的元素 ID, 视频模块会嵌入到此元素内
          mode: "player",
        },
        {
          id: "content", // 接入方页面内的元素 ID, 菜单栏模块会嵌入到此元素内
          mode: "menu",
        },
      ],
      options: {
        mobileBackgroundTransparent: true,
        saveUserInfo: true,
      },
    });

    webSDK.on("error", console.log);
  })
  .catch(function (error) {
    console.error("LiveSaaSWebSDKLoader ready failed", error);
  });

手动指定版本接入的示例代码如下所示：

直播间

点播播放器

直播间 SDK 初始化代码示例如下所示：

var webSDK = new window.ByteLiveWebSDK({
  activityId: 169410856822****,
  token: 'JC****',
  service: 'Demo',
  mode: 1,
  modules: [
    {
      id: "player",
      mode: "player", 
    }, 
    {
      id: "menu", 
      mode: "menu",
      menu: ["comment"],
    }
  ],
  options: {}
})

webSDK.emit('player.pause'); // 触发事件
webSDK.on('player.pause', () => {}); // 监听事件

点播间 SDK 初始化代码示例如下所示：

var webSDK = new window.ByteLiveWebSDK({
  vodPlayerToken: 'ceed74dcb2ceaba3c92a91fc2ebd****',
  vid: 'v03a49g10000cojk12bc77ua72bm****',
  vodPlayerConfigId: 'vcid-179665696630****',
  service: 'Demo',
  modules: [
    {
      id: "player",
      mode: "player",
    }
  ],
  options: {}
})

webSDK.emit('player.pause'); // 触发事件
webSDK.on('player.pause', () => {}); // 监听事件

（可选）步骤三：自定义样式

SDK 元素的 class 属性值不可更改。您可以通过变更 class 属性的样式属性及其属性值，覆盖对应元素的样式，实现样式自定义。

步骤四：验证效果

您可以选择以下任一方法验证接入效果。

本地调试

在本地 localhost:8080 端口进行调试，但此种调试方法无法播放预告和回放。有关本地调试方法，详见 Demo 体验集成示例。

线上调试

建议在 PC 上使用 SDK demo playground 进行线上效果调试。通过 SDK demo playground 配置不同版本的 SDK 以及不同直播间，修改模板代码后可实时预览效果。详见企业直播 Web SDK demo playground。

常见问题

Web 观播 SDK 常见问题

版本更新说明

自 2.1.0 版本开始，域名从 https://lf-cdn-tos.bytescm.com/obj/static 变更为企业直播专属域名 https://mediaservice-fe.volccdn.com/obj/vcloud-fe。原域名 https://lf-cdn-tos.bytescm.com/obj/static 后续可能不再支持使用，建议您在集成 2.1.0 及以上版本时，使用新域名 https://mediaservice-fe.volccdn.com/obj/vcloud-fe。
受 Chrome 发起的【RTC 建联过程中的 SDP 禁止修改】改动影响，观众连麦功能在 Chrome 139 (预期 2025.7.30 发布) 及以上版本的浏览器中可能无法正常使用。如需继续使用观众连麦功能，请在 2025 年 7 月 30 日之前，将 Web 观播 SDK 更新至 2.1.22 及以上版本。

最近更新时间：2026.09.09 18:36:43

这个页面对您有帮助吗？

有用

无用

企业直播

前提条件

功能支持

最新版本

相关 Skill

配置重试机制

集成方法

步骤一：引入 SDK 资源

（推荐）方式一：使用 WebSDK Loader 接入

方式二：手动指定版本接入

步骤二：初始化 SDK

（可选）步骤三：自定义样式

步骤四：验证效果

本地调试

线上调试

常见问题

版本更新说明

企业直播

前提条件 #

功能支持 #

最新版本 #

相关 Skill #

配置重试机制 #

集成方法 #

步骤一：引入 SDK 资源 #

（推荐）方式一：使用 WebSDK Loader 接入

方式二：手动指定版本接入

步骤二：初始化 SDK #

（可选）步骤三：自定义样式 #

步骤四：验证效果 #

本地调试

线上调试

常见问题 #

版本更新说明 #

前提条件

功能支持

最新版本

相关 Skill

配置重试机制

集成方法

步骤一：引入 SDK 资源

步骤二：初始化 SDK

（可选）步骤三：自定义样式

步骤四：验证效果

常见问题

版本更新说明