文档中心

企业直播

微信小程序观播 SDK

集成微信小程序观播 SDK

微信小程序观播 SDK 是一套帮助开发者在自有微信小程序中快速集成直播观看页面的工具集。使用本 SDK 可以显著降低开发成本，为用户提供稳定、高清的直播观看体验。SDK 适用于电商带货、在线教育、企业培训等需要在小程序内实现直播功能的场景。本文介绍微信小程序观播 SDK 的功能支持情况以及集成方法。

功能支持

微信小程序观播 SDK 支持的功能详见功能列表。

前提条件

您已开通尊享版套餐。详见计费说明。

登录小程序开发者后台，在开发管理 > 开发设置 > 服务器域名中配置以下服务器域名白名单。

request合法域名：添加以下以 https 开头的域名。

https://live.byteoc.com;
https://live.volcvideo.com;
https://mon.zijieapi.com;
https://vod.bytedanceapi.com;
https://common.rtc.volcvideo.com;
https://common-hl.rtc.volcvideo.com;
https://log.snssdk.com;
https://mcs.zijieapi.com;
https://imagex.volcengineapi.com;
https://xtjplaems7.up.imagex-accelerate.volces.com;
https://xtjplaems7.up.imagex-cn-north-1.volces.com;

socket合法域名：添加以下以 wss 开头的域名。

wss://frontier.snssdk.com;
wss://ws.rtc.volcvideo.com;
wss://ws-hl.rtc.volcvideo.com;
wss://ws-ag-agsxxa.rtc.volcvideo.com;
wss://ws-ag-aghbwh.rtc.volcvideo.com;
wss://ws-ag-agsdqd.rtc.volcvideo.com;
wss://ws-ag-agjsnj.rtc.volcvideo.com;
wss://ws-ag-aggdsz.rtc.volcvideo.com;

uploadFile合法域名：添加以下以 https 开头的域名。

https://xtjplaems7.up.imagex-accelerate.volces.com;
https://xtjplaems7.up.imagex-cn-north-1.volces.com;

集成方法

原生微信小程序

完成以下步骤，将观播 SDK 集成到您的原生微信小程序中。

下载 SDK 压缩包，解压缩至您自己的项目目录下。
（推荐）使用 live-player 组件观播
使用 video 组件观播
要使用 live-player 组件观播，请复制以下链接至浏览器，下载 SDK 压缩包：
注意
要使用该版本中的直播功能，请先开通微信直播组件 live-player 的权限，详见申请开通 live-player。
https://res.gcloudcache.com/volc-fe/mini-program/1.0.0.468/volc-mini-sdk-0.0.27.zip
要使用 video 组件观播，请复制以下链接至浏览器，下载 SDK 压缩包：
说明
使用该版本 SDK 的直播功能无需开通 live-player 权限。
https://res.gcloudcache.com/volc-fe/mini-program/1.0.0.468/volc-mini-sdk-0.0.27-video-only.zip
SDK 文件夹的结构如下：
```
|volc-mini-sdk
|---lib/         SDK 依赖文件
|---assets/      静态文件索引
|---components/  组件文件夹
|---|---chat/    聊天组件
|---|---player/  播放器组件
|---|---volc-live-portrait  竖屏直播间整体组件
|---|---volc-live-landscape 横屏直播间整体组件
|---index.js     初始化模块
|---store/       数据缓存目录
```
SDK 组件内部使用了微信官方提供的 UI 库 WeUI，因此您需要在项目的 app.json 文件中添加以下代码引入 WeUI 组件库：
```
"useExtendedLib": {
    "weui": true
}
```

参考以下步骤在项目的 page 页面实现横竖屏直播间：

在项目的 app.json 文件中按需引入直播间整体组件，示例代码如下：

"usingComponents": {
  "volc-live-portrait": "./volc-mini-sdk/components/volc-live-portrait/volc-live-portrait", // 竖屏直播间整体组件
  "volc-live-landscape": "./volc-mini-sdk/components/volc-live-landscape/volc-live-landscape" // 横屏直播间整体组件
 }

在 wxml 文件中按需使用直播间整体组件，示例代码如下：
```
<view>
 
  <volc-live-portrait sdkInstance="{{sdk}}" bind:commentCheck="commentCheck"/> 
  
  <volc-live-landscape sdkInstance="{{sdk}}" bind:commentCheck="commentCheck"/>
</view>
```
- 组件的 sdkInstance 属性即为 SDK 实例。您需在下文步骤 d 中参考示例代码创建 SDK 实例，再将 SDK 实例传入对应的直播间组件。
- 组件的 commentCheck 属性用于判断用户是否可发送评论，您需在下文步骤 d 中参考示例代码处理登录逻辑，传入用户的授权 token signToken 的值。
（可选）如需适配微信原生的关怀模式（大字版），请在每个承载直播间的页面 wxml 顶部添加以下代码。page-meta 必须是页面的第一个节点；SDK 作为自定义组件，无法代替您修改宿主页面的 root-font-size。添加后，观众在微信我 > 设置 > 关怀模式 中开启该模式后，观播页面的字体会自动放大。
说明
每个承载直播间的页面均需添加该代码。
```
<page-meta root-font-size="system" />

<view class="live-page">
  
</view>
```
同时，SDK 横屏和竖屏直播间内置独立的“关怀模式”开关，适用于未配置 page-meta，或希望在微信原生关怀模式基础上进一步放大直播间页面文字的场景。详情参考accessibility字段说明。

在 js 文件中的 onLoad 方法中创建 SDK 实例，示例代码和参数说明如下所示。

公开鉴权模式：当 mode 取值为 1 时，观众以游客身份进入直播间，在点击评论输入框等需要用户信息的场景下，SDK 会触发 commentCheck，以验证观众身份。您可在 commentCheck 里处理登录逻辑并调用 GetSDKTokenAPI 接口获取用户 Token。获取到用户 Token 后，再调用 reSetLiveInfo 方法，将 mode 的取值设为 2 并传入用户 Token，重置直播间信息。重置成功后用户即可发送评论。

import VolcMiniSdk, { EVENTS } from './volc-mini-sdk/index';
Page({
  data: {
      sdk: null,
  },
  async onLoad() {
    // 页面加载时，创建 SDK 实例。参数说明参考下表
    const sdk = new VolcMiniSdk({
      'activityId': 17229****9941234,
      'token': 'ps****',
      'mode': 1,
    });
    sdk.on(EVENTS.error, (err) => {
        console.log('sdk error', err.code, err.message);
    })
    console.log('sdkInstance', sdk);
    this.setData({
      sdk,
    })
  },
  onUnload() {
    // 页面卸载时，调用 destroy 方法销毁直播间
    this.data.sdk.destroy();
  }
  // 当用户点击评论输入框时，如果 mode 取值为 1，会触发 commentCheck，校验用户信息
  async commentCheck() {
    // 此处您需调用 GetSDKTokenAPI 接口获取用户 Token
    // 调用 reSetLiveInfo 方法重置直播间信息。参数说明参考下表
    this.data.sdk.reSetLiveInfo({
      'activityId': 17229****9941234,
      'token': 'ak3T%2FdaG****zSFD7%2F1GPG',
      'mode': 2,
    })
  },
})

自定义鉴权模式：当 mode 取值为 2 时，观众在进入直播间时，即需要获取观众进入直播间的授权 token 即 signToken 的值。您需调用 GetActivityLoginSecret 接口，获取直播间或点播间维度的登录秘钥，再自行生成 JWT（JSON Web Token）作为 signToken 的值。详情参考该接口使用说明。

import VolcMiniSdk, {EVENTS} from './volc-mini-sdk/index';
Page({
  data: {
      sdk: null,
  },
  async onLoad() {
    // 页面加载时，创建 SDK 实例。参数说明参考下表
    const sdk = new VolcMiniSdk({
      'activityId': 17229****9941234,
      'signToken': 'ak3T%2FdaG****zSFD7%2F1GPG',
      'mode': 2,
    });
    console.log('sdkInstance', sdk);
    sdk.on(EVENTS.error, (err) => {
        console.log('sdk error', err.code, err.message);
    })
    this.setData({
      sdk,
    })
  },
  onUnload() {
    // 页面卸载时，调用 destroy 方法销毁直播间
    this.data.sdk.destroy();
  }
})

创建 SDK 实例时以及 reSetLiveInfo 方法的参数说明如下：

名称	类型	是否必选	默认值	说明
activityId	Integer	是	无	直播间的活动 ID。您可通过调用 CreateActivityAPIV2 或 ListActivityAPI 接口获取活动 ID，也可以在企业直播控制台的直播间左上角获取活动 ID。一个直播间对应一个 activityId。
mode	Integer	是	无	鉴权模式。取值如下： `1`：公开鉴权模式。观众以游客身份进入直播间，在点击评论输入框等需要用户信息的场景下，SDK 会触发 `commentCheck`。 `2`：自定义模式。观众在进入直播间时使用的是您自定义的用户信息，因此可以直接发送评论等。
signToken	string	是	无	用户进入直播间或点播间的授权 Token。`token` 与 `signToken` 至少需传入其中一个参数；当两者同时传入时，以 `signToken` 为准。不同鉴权模式（`mode`）下，`signToken` 的获取方式不同。详情参考获取直播间登录密钥中使用说明一节。说明 `reSetLiveInfo` 方法暂不支持该参数。在使用 `reSetLiveInfo` 方法时，请传入 `token` 参数。
token	String	是	无	用户进入直播间时的授权 Token。`token` 与 `signToken` 至少需传入其中一个参数；当两者同时传入时，以 `signToken` 为准。不同鉴权模式（`mode`）下，`token` 的获取方式不同： `mode` 取值为 `1` 时，您可通过调用 GetSDKTokenAPI 接口获取用户 Token，也可以在企业直播控制台直播间内的观看页管理 > 页面嵌入 > Web SDK嵌入中获取用户 Token。 `mode` 取值为 `2` 时，您可通过调用 GetSDKTokenAPI 接口获取用户 Token。
options	SdkExtraOptions	否	-	可选配置项。

uni-app 框架

完成以下步骤，将观播 SDK 集成到 uni-app-demo 项目中，体验观看页效果。

下载 uni-app-demo 项目压缩包，并将其解压至本地目录。
uni-app-demo.zip
未知大小
根据实际需求，下载以下任一 SDK 压缩包。
（推荐）使用 live-player 组件观播
使用 video 组件观播
要使用 live-player 组件观播，请复制以下链接至浏览器，下载 SDK 压缩包：
注意
要使用该版本中的直播功能，请先开通微信直播组件 live-player 的权限，详见申请开通 live-player。
https://res.gcloudcache.com/volc-fe/mini-program/1.0.0.468/volc-mini-sdk-0.0.27.zip
要使用 video 组件观播，请复制以下链接至浏览器，下载 SDK 压缩包：
说明
使用该版本 SDK 的直播功能无需开通 live-player 权限。
https://res.gcloudcache.com/volc-fe/mini-program/1.0.0.468/volc-mini-sdk-0.0.27-video-only.zip
SDK 文件夹的结构如下：
```
|volc-mini-sdk
|---lib/         SDK 依赖文件
|---assets/      静态文件索引
|---components/  组件文件夹
|---|---chat/    聊天组件
|---|---player/  播放器组件
|---|---volc-live-portrait  竖屏直播间整体组件
|---|---volc-live-landscape 横屏直播间整体组件
|---index.js     初始化模块
|---store/       数据缓存目录
```
将 SDK 包解压缩至 uni-app-demo 项目目录下的 /src/wxcomponents 文件夹中。

在项目的 pages.json 文件中按需引入直播间整体组件，示例代码如下：

"pages": [ 
    {
      "path": "pages/index/index",
      "style": {
        "usingComponents": {
          "port-live-room": "/wxcomponents/volc-mini-sdk/components/volc-live-portrait/volc-live-portrait", // 竖屏直播间整体组件
          "lans-live-room": "/wxcomponents/volc-mini-sdk/components/volc-live-landscape/volc-live-landscape" // 横屏直播间整体组件
        },
        "navigationBarTitleText": "uni-app"
      }
    }
]

SDK 组件内部使用了微信官方提供的 UI 库 WeUI，因此您需要在项目的 manifest.json 文件中添加以下代码引入 WeUI 组件库：

"mp-weixin": { 
    "appid": "",
    "setting": {
      "urlCheck": false
    },
    "usingComponents": true,
    "useExtendedLib": {
      "weui": true // 引入 WeUI 组件库
    }
  },

（可选）如需适配微信原生的关怀模式（大字版），请在每个承载直播间的 .vue 模板顶部添加以下代码。page-meta 必须是页面的第一个节点；SDK 组件无法代替宿主页面修改 root-font-size。添加后，观众在微信我 > 设置 > 关怀模式 中开启该模式后，观播页面的字体会自动放大。
说明
每个承载直播间的页面均需添加该代码。
```
<template>
  <page-meta root-font-size="system" />

  <view class="live-page">
    <volc-live-portrait
      v-if="isPort"
      :sdk-instance="sdk"
    />
    <volc-live-landscape
      v-else
      :sdk-instance="sdk"
    />
  </view>
</template>
```
同时，SDK 横屏和竖屏直播间内置独立的“关怀模式”开关，适用于未配置 page-meta，或希望在微信原生关怀模式基础上进一步放大直播间页面文字的场景。详情参考accessibility字段说明。

按需引入直播间整体组件并初始化 configs 参数。示例代码如下所示。

<template>
    <view class="content">
        <!-- 通过 ref 拿到组件实例，进而获取组件内的 sdkInstance -->
        <!-- 引入竖屏直播间整体组件并初始化 configs 参数 -->
        <port-live-room
            id="livePortrait"
            ref="livePortrait"
            :configs="configs"
            @commentCheck="handleCommentCheck"
        ></port-live-room>
    </view>
</template>


<script>
    import { EVENTS } from '../../wxcomponents/volc-mini-sdk/index'


    export default {
        data() {
            return {
                title: 'Hello',
                configs: null
            }
        },
        onLoad() {
            // 参数说明请参考下表
            this.configs = {
                activityId: 17229****9941234, // 请替换为真实的活动 ID
                token: 'ps****', // 请替换为真实的 Token
                mode: 1
            }
        },
        onReady() {
            // 设置 configs 后，需要等组件渲染完成后再获取 sdkInstance。
            this.initSdkInstance()
        },
        onUnload() {
            // 此处销毁 sdkInstance
            if (this._sdkInstance && typeof this._sdkInstance.destroy === 'function') {
                this._sdkInstance.destroy()
            }
        },
        methods: {
            initSdkInstance() {
                const portComp = this.$refs.livePortrait ||
                    (this.$scope && this.$scope.selectComponent && this.$scope.selectComponent('#livePortrait'))


                if (!portComp) {
                    return
                }


                const sdkInstance = portComp.data && portComp.data.sdkInstance


                if (!sdkInstance || typeof sdkInstance.on !== 'function') {
                    return
                }


                 // 此处监听 sdkInstance 上的事件。
                sdkInstance.on(EVENTS.error, (payload) => {
                    console.log('sdk error', payload)
                })
                sdkInstance.on(EVENTS.card.click, (payload) => {
                    console.log('card.click', payload)
                    this.navigateToWebview(payload && payload.url)
                })
                sdkInstance.on(EVENTS.floatingCard.click, (payload) => {
                    console.log('floatingCard.click', payload)
                    this.navigateToWebview(payload && payload.url)
                })
                sdkInstance.on(EVENTS.adFloating.click, (payload) => {
                    console.log('adFloating.click', payload)
                    this.navigateToWebview(payload && payload.AdvertisementRedirectUrl)
                })
                // 把 sdkInstance 挂到 this 上，方便其他函数内使用
                this._sdkInstance = sdkInstance
            },
            navigateToWebview(url) {
                if (!url) {
                    return
                }


                uni.navigateTo({
                    url: `/pages/webview/webview?url=${encodeURIComponent(url)}`
                })
            },
            handleCommentCheck() {
                uni.showToast({
                    title: '请使用 mode=2 的 token',
                    icon: 'none'
                })
            }
        }
    }
</script>


<style>
    .content {
        min-height: 100vh;
    }
</style>

功能实现：自定义跳转逻辑

您可以通过配置参数 jumpConfig 来支持指定功能范围，跳转至您自定义的 Webview 页面。详见配置参数。您也可以监听点击事件，在观众点击后实现自定义跳转逻辑。本小节介绍如何通过监听点击事件的方式实现自定义跳转逻辑。

说明

了解如何在企业直播控制台配置商品卡片和浮标广告，详见商品卡片和广告位设置。

以下示例代码展示如何监听菜单内商品卡片、浮窗商品卡片和浮标广告的点击事件，并实现自定义跳转。

import { EVENTS } from './volc-mini-sdk/index';

// sdk 实例获取参考前文
sdk.on(EVENTS.card.click, (payload) => {
    // 跳转至您自行实现的 webview 组件页面
    wx.navigateTo(`/webview?url=${payload.url}`);
});
sdk.on(EVENTS.floatingCard.click, (payload) => {
    // 跳转到您自行实现的 webview 组件页面
    wx.navigateTo(`/webview?url=${payload.url}`);
});

sdk.on(EVENTS.adFloating.click, (payload) => {
    // 跳转到您自行实现的 webview 组件页面
    wx.navigateTo(`/webview?url=${payload.AdvertisementRedirectUrl}`);
});

以上示例的相关事件和观看页位置如下表所示。

功能	事件	观看页位置
菜单内商品卡片	card.click
浮窗商品卡片	floatingCard.click
浮标广告	adFloating.click

最近更新时间：2026.09.09 16:47:33

这个页面对您有帮助吗？

有用

无用

企业直播

最新版本 #

功能支持 #

前提条件 #

集成方法 #

原生微信小程序 #

uni-app 框架 #