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

文档中心

企业直播

微信小程序观播 SDK

集成微信小程序观播 SDK

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

功能支持

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

功能	说明
横竖屏直播间	横屏适用于活动、大会、培训等直播场景，竖屏适用于营销、卖货等直播场景。
封面/背景/主题	设置直播间的横竖屏封面、背景图或背景色，以及外观主题。说明仅 0.0.22 及以上版本的微信小程序观播 SDK 支持设置背景图、背景色和外观主题。
页头图	设置直播间的页头图。说明仅 0.0.22 及以上版本的微信小程序观播 SDK 支持设置页头图。
背景模糊	对背景进行模糊处理。说明仅 0.0.22 及以上版本的微信小程序观播 SDK 支持对背景模糊处理。
播放暖场预告片	支持上传播放预告片，进行直播活动预热，传递直播价值点，吸引更多用户转化。
倒计时	在直播开播前进入直播间，显示直播倒计时时间。详见直播倒计时。
预约直播	支持预约直播，支持在直播开始前，通过短信等提醒观众开播。详见直播预约。
人气显示	显示直播间的在线人数。说明仅 0.0.22 及以上版本的微信小程序观播 SDK 支持显示直播间的在线人数。
点播回放	支持直播结束后生成回放文件自动上架到直播间观看页。
发送评论	支持发送评论。
微信关怀模式	小程序观播页面支持微信的关怀模式。观众可以在微信中前往“我 > 设置 > 更多 > 关怀模式”开启。开启后，观播页面的字体会自动变大。
高亮主持人发言	支持高亮主持人发言。
观众连麦	观众可以申请连麦，和主持人实时语音、视频互动。
商品卡片	支持在直播间展示在控制台配置的商品卡片信息。支持观看页浮层展示商品卡片或新页面展示内容、浮窗展示商品卡片，以及调整商品卡片显示顺序。
商品脚本	支持在视频播放到指定时间点时，自动展示相应的商品。详见商品脚本。
签到	支持在直播间内发起签到。详见签到。
答题	支持在直播间内发起答题。详见答题。
实时抽奖	在配置并发送实时抽奖后，观众可以在直播间内参与抽奖。配置发送抽奖和观众参与抽奖的步骤详见实时抽奖。
卡券	在配置并发送卡券后，观众可以在直播间内领取卡券。配置发送卡券和观众领取卡券的步骤详见卡券。
红包	在配置并发送红包后，观众可以在直播间内领取红包。配置发送红包和观众领取红包的步骤详见红包。
问卷	支持在直播间内发送匿名或实名问卷。详见问卷。
直播间点赞	在控制台开启点赞功能后，观众可以在直播间内点击点赞按钮为直播间点赞。开启点赞功能的步骤详见直播间点赞。
图文介绍菜单	自定义在直播间展示的图文信息及跳转链接。详见图文介绍。
浮标广告	支持在直播间内展示在控制台配置的浮标广告。配置步骤详见广告位设置。
观众等级	在控制台配置观众等级后，观众可以在直播间内查看昵称前的观众等级标签。详见观众等级。
观众踢出	被踢出的观众可通过点击继续观看重新进入当前直播间。
观众封禁	被封禁的观众无法进入或继续停留在当前直播间。
禁止重复登录	禁止观众使用相同账号重复登录同一直播间，后一次登录成功的同时前一次的登录会被强制退出。
聊天置顶	支持对聊天内容进行置顶。
图片评论	支持发送和接收图片评论。
动态表情包	观众可以发送动态表情包，提升直播间的互动氛围。暂不支持触发评论区特效。详见动态表情包。
直播描述	支持对直播内容进行简短介绍。该描述将显示在直播间页面。详见装修直播间。说明仅 0.0.20 及以上版本的微信小程序观播 SDK 支持直播描述功能。
系统消息	支持在观看页展示抽奖通知、红包通知、动态表情包特效、送礼消息、进场消息以及自定义消息。观众可以屏蔽系统消息。说明仅 0.0.20 及以上版本的微信小程序观播 SDK 支持系统消息功能。
认真度检测	支持在直播间播放器播放的状态下对观众的切屏行为、静音停播行为和无互动行为进行弹窗提醒和记录。详见认真度检测。说明仅 0.0.20 及以上版本的微信小程序观播 SDK 支持认真度检测功能。
观众头像	支持在观看页和控制台数据页面展示观众头像。详见观众头像。说明仅 0.0.20 及以上版本的微信小程序观播 SDK 支持观众头像功能。
投票	支持在直播间内发送投票。详见投票。说明仅 0.0.20 及以上版本的微信小程序观播 SDK 支持投票功能。
公告	支持在直播间发布公告。详见公告。说明仅 0.0.20 及以上版本的微信小程序观播 SDK 支持公告功能。
福利任务	支持创建福利任务，让观众在直播间观看直播时，完成您设定的具体任务，并获得奖励。详见福利任务。说明仅 0.0.20 及以上版本的微信小程序观播 SDK 支持福利任务功能。
自动回复	支持自动回复功能，您可以在直播间预设观众评论关键词和相应的回复内容。当观众的评论包含关键词时，系统便会自动发送您预设的回复。详见自动回复。说明仅 0.0.22 及以上版本的微信小程序观播 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.380/volc-mini-sdk-0.0.22.zip
要使用 video 组件观播，请复制以下链接至浏览器，下载 SDK 压缩包：
说明
使用该版本 SDK 的直播功能无需开通 live-player 权限。
https://res.gcloudcache.com/volc-fe/mini-program/1.0.0.380/volc-mini-sdk-0.0.22-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();
  }
})

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

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

您可以通过配置参数 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.06.22 20:21:52

这个页面对您有帮助吗？

有用

无用

企业直播

最新版本 #

功能支持 #

前提条件 #

集成方法 #

原生微信小程序 #

uni-app 框架 #