集成微信小程序观播 SDK--企业直播-火山引擎

文档中心

企业直播

微信小程序观播 SDK

集成微信小程序观播 SDK

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

功能支持

微信小程序观播 SDK 支持以下功能：

功能	说明
横竖屏直播间	横屏适用于活动、大会、培训等直播场景，竖屏适用于营销、卖货等直播场景。
展示直播封面	支持设置直播间的横竖屏封面。
播放暖场预告片	支持上传播放预告片，进行直播活动预热，传递直播价值点，吸引更多用户转化。
倒计时	在直播开播前进入直播间，显示直播倒计时时间。详见直播倒计时。说明仅 0.0.19 及以上版本的微信小程序观播 SDK 支持倒计时功能。
预约直播	支持预约直播，支持在直播开始前，通过短信等提醒观众开播。详见直播预约。说明仅 0.0.19 及以上版本的微信小程序观播 SDK 支持预约直播功能。
点播回放	支持直播结束后生成回放文件自动上架到直播间观看页。
发送评论	支持发送评论。
高亮主持人发言	支持高亮主持人发言。
观众连麦	观众可以申请连麦，和主持人实时语音、视频互动。
商品卡片	支持在直播间展示在控制台配置的商品卡片信息。支持观看页浮层展示商品卡片或新页面展示内容、浮窗展示商品卡片，以及调整商品卡片显示顺序。说明微信小程序观播 SDK 仅支持展示商品卡片，默认不支持直接跳转。您可以通过监听 SDK 的菜单商品卡片点击事件 card.click 和浮窗商品卡片点击事件 floatingCard.click ，在小程序内自行实现跳转。
商品脚本	支持在视频播放到指定时间点时，自动展示相应的商品。详见商品脚本。
签到	支持在直播间内发起签到。详见签到。
答题	支持在直播间内发起答题。详见答题。
实时抽奖	在配置并发送实时抽奖后，观众可以在直播间内参与抽奖。配置发送抽奖和观众参与抽奖的步骤详见实时抽奖。说明配置抽奖参与条件时，请您暂时避免勾选“投票”选项。由于小程序 SDK 暂不支持这些条件，勾选后会影响观众在小程序中的参与体验。
卡券	在配置并发送卡券后，观众可以在直播间内领取卡券。配置发送卡券和观众领取卡券的步骤详见卡券。说明配置卡券参与条件时，请您暂时避免勾选 “观众等级”选项。由于小程序 SDK 暂不支持该条件，勾选后会影响观众在小程序中的参与体验。
红包	在配置并发送红包后，观众可以在直播间内领取红包。配置发送红包和观众领取红包的步骤详见红包。说明配置红包参与条件时，请您暂时避免勾选“投票”选项。由于小程序 SDK 暂不支持该条件，勾选后会影响观众在小程序中的参与体验。
问卷	支持在直播间内发送匿名或实名问卷。详见问卷。说明仅 0.0.19 及以上版本的微信小程序观播 SDK 支持问卷功能。
直播间点赞	在控制台开启点赞功能后，观众可以在直播间内点击点赞按钮为直播间点赞。开启点赞功能的步骤详见直播间点赞。
图文介绍菜单	自定义在直播间展示的图文信息及跳转链接。
浮标广告	支持在直播间内展示在控制台配置的浮标广告。配置步骤详见广告位设置。说明微信小程序观播 SDK 仅支持展示浮标广告，默认不支持直接跳转。您可以通过监听 SDK 的浮标广告点击事件adFloating.click ，在小程序内自行实现跳转。
观众等级	在控制台配置观众等级后，观众可以在直播间内查看昵称前的观众等级标签。详见观众等级。
观众踢出	被踢出的观众可通过点击继续观看重新进入当前直播间。
观众封禁	被封禁的观众无法进入或继续停留在当前直播间。
禁止重复登录	禁止观众使用相同账号重复登录同一直播间，后一次登录成功的同时前一次的登录会被强制退出。
聊天置顶	支持对聊天内容进行置顶。说明仅 0.0.18 及以上版本的微信小程序观播 SDK 支持聊天置顶功能。
图片评论	支持发送和接收图片评论。说明仅 0.0.18 及以上版本的微信小程序观播 SDK 支持图片评论功能。
动态表情包	观众可以发送动态表情包，提升直播间的互动氛围与弹幕量。暂不支持触发评论区特效。详见动态表情包。说明仅 0.0.18 及以上版本的微信小程序观播 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.215/volc-mini-sdk-0.0.19.zip
要使用 video 组件观播，请复制以下链接至浏览器，下载 SDK 压缩包：
说明
使用该版本 SDK 的直播功能无需开通 live-player 权限。
https://res.gcloudcache.com/volc-fe/mini-program/1.0.0.215/volc-mini-sdk-0.0.19-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 实例。您需在下文步骤 c 中参考示例代码创建 SDK 实例，再将 SDK 实例传入对应的直播间组件。
- 组件的 commentCheck 属性用于判断用户是否可发送评论，您需在下文步骤 c 中参考示例代码处理登录逻辑，传入用户的授权 token signToken 的值。

在 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](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html#onLoad-Object-query)() {
    // 页面加载时，创建 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](https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html#onLoad-Object-query)() {
    // 页面加载时，创建 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();
  }
})

说明

仅 0.0.9 及以上版本的微信小程序观播 SDK 支持 signToken 参数。

创建 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.215/volc-mini-sdk-0.0.19.zip
要使用 video 组件观播，请复制以下链接至浏览器，下载 SDK 压缩包：
说明
使用该版本 SDK 的直播功能无需开通 live-player 权限。
https://res.gcloudcache.com/volc-fe/mini-program/1.0.0.215/volc-mini-sdk-0.0.19-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 组件库
    }
  },

按需引入直播间整体组件并初始化 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: 1722918339941389,
                token: 'psNBho',
                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>

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

观众在小程序内点击菜单内商品卡片、浮窗商品卡片和浮标广告时，SDK 默认仅触发点击事件，不做跳转。要实现跳转，您需要监听相关事件，在观众点击后实现自定义跳转逻辑。

说明

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

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

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}`);
});

目前小程序 SDK 支持自定义跳转逻辑的功能以及相关事件和观看页位置如下表所示。

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

最近更新时间：2026.05.18 16:50:04

这个页面对您有帮助吗？

有用

无用

企业直播

功能支持 #

最新版本 #

前提条件 #

集成方法 #

原生微信小程序 #

uni-app 框架 #