企业直播
企业直播
- 文档首页
企业直播微信小程序观播 SDK集成微信小程序观播 SDK
文档反馈
问问助手微信小程序观播 SDK 是一套帮助开发者在自有微信小程序中快速集成直播观看页面的工具集。使用本 SDK 可以显著降低开发成本，为用户提供稳定、高清的直播观看体验。SDK 适用于电商带货、在线教育、企业培训等需要在小程序内实现直播功能的场景。本文介绍微信小程序观播 SDK 的功能支持情况以及集成方法。
功能支持
微信小程序观播 SDK 支持以下功能：
功能 | 说明 |
|---|---|
横竖屏直播间 | 横屏适用于活动、大会、培训等直播场景，竖屏适用于营销、卖货等直播场景。 |
展示直播封面、背景和主题 | 支持设置直播间的横竖屏封面、背景图或背景色，以及外观主题。 |
播放暖场预告片 | 支持上传播放预告片，进行直播活动预热，传递直播价值点，吸引更多用户转化。 |
点播回放 | 支持直播结束后生成回放文件自动上架到直播间观看页。 |
发送评论 | 支持发送评论。 |
高亮主持人发言 | 支持高亮主持人发言。 |
观众连麦 | 观众可以申请连麦，和主持人实时语音、视频互动。 |
商品卡片 | 支持在直播间展示在控制台配置的商品卡片信息。支持观看页浮层展示商品卡片或新页面展示内容、浮窗展示商品卡片，以及调整商品卡片显示顺序。 说明 微信小程序观播 SDK 仅支持展示商品卡片，默认不支持直接跳转。您可以通过监听 SDK 的菜单商品卡片点击事件 card.click 和浮窗商品卡片点击事件 floatingCard.click，在小程序内自行实现跳转。 |
签到 | 支持在直播间内发起签到。 |
答题 | 支持在直播间内发起答题。 |
图文介绍菜单 | 自定义在直播间展示的图文信息及跳转链接。 |
浮标广告 | 支持在直播间内展示在控制台配置的浮标广告。配置步骤详见广告位设置。 说明
|
观众踢出 | 被踢出的观众可通过点击继续观看重新进入当前直播间。 说明 仅 0.0.9 及以上版本的微信小程序观播 SDK 支持观众踢出功能。 |
观众封禁 | 被封禁的观众无法进入或继续停留在当前直播间。 说明 仅 0.0.9 及以上版本的微信小程序观播 SDK 支持观众封禁功能。 |
禁止重复登录 | 禁止观众使用相同账号重复登录同一直播间，后一次登录成功的同时前一次的登录会被强制退出。 说明 仅 0.0.9 及以上版本的微信小程序观播 SDK 支持禁止重复登录功能。 |
前提条件
- 您已开通尊享版套餐。详见计费说明。
- 如需使用直播功能，您需要开通微信直播组件 live-player 的权限，详见申请开通 live-player。
- 登录小程序开发者后台，在开发管理 > 开发设置 > 服务器域名中配置以下服务器域名白名单。
request合法域名：添加以下以
https开头的域名。https://live.byteoc.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;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;
集成方法
原生微信小程序
完成以下步骤，将观播 SDK 集成到您的原生微信小程序中。
下载 SDK 压缩包，解压缩至您自己的项目目录下。
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 中参考示例代码处理登录逻辑，传入用户的授权 tokensignToken的值。
- 组件的
在
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
Partial<Options>
否
-
可选配置项。
uni-app 框架
您可下载并运行 Demo，体验观看页效果。
完成以下步骤，将观播 SDK 集成到 uni-app 框架中。
下载 SDK 压缩包，解压缩至您自己的项目目录下。
SDK 文件夹的结构如下：|volc-mini-sdk |---lib/ SDK 依赖文件 |---assets/ 静态文件索引 |---components/ 组件文件夹 |---|---chat/ 聊天组件 |---|---player/ 播放器组件 |---|---volc-live-portrait 竖屏直播间整体组件 |---|---volc-live-landscape 横屏直播间整体组件 |---index.js 初始化模块 |---store/ 数据缓存目录在 uni-app 项目目录下创建
wxcomponents文件夹，将解压后的 SDK 文件夹volc-mini-sdk添加至该文件夹下。在项目的
pages.json文件中按需引入直播间整体组件，示例代码如下："pages": [ { "path": "pages/index/index", "style": { "usingComponents": { "PortLiveRoom": "/wxcomponents/volc-mini-sdk/components/volc-live-portrait/volc-live-portrait", // 竖屏直播间整体组件 "LansLiveRoom": "/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 --> <PortLiveRoom ref="livePortrait" :configs="configs"></PortLiveRoom> // 引入竖屏直播间整体组件并初始化 configs 参数 </view> </template> <script> export default { data() { return { title: 'Hello', configs: null, } }, onLoad() { // 参数说明请参考下表 this.configs = { activityId: 17229****9941234, signToken: 'ak3T%2FdaG****zSFD7%2F1GPG', mode: 2, }; // 设置 configs 后，需要等组件渲染完成后再获取 sdkInstance。 this.$nextTick(() => { const portComp = this.$refs.livePortrait if (!portComp) { return } const sdkInstance = portComp?.data?.sdkInstance console.log('sdkInstance', 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) }); sdkInstance.on(EVENTS.floatingCard.click, (payload) => { console.log('floatingCard.click', payload); }); sdkInstance.on(EVENTS.adFloating.click, (payload) => { console.log('adFloating.click', payload); }); // 把 sdkInstance 挂到 this 上，方便其他函数内使用 this._sdkInstance = sdkInstance }) }, onUnload() { // 此处销毁 sdkInstance。 this._sdkInstance?.destroy(); }, methods: { } } </script>相关参数说明如下所示。
名称
类型
是否必选
默认值
说明
activityId
Integer
是
无
直播间的活动 ID。您可通过调用 CreateActivityAPIV2 或 ListActivityAPI 接口获取活动 ID，也可以在企业直播控制台的直播间左上角获取活动 ID。一个直播间对应一个 activityId。
mode
Integer
是
无
鉴权模式。取值如下：
1：公开鉴权模式。观众以游客身份进入直播间，在点击评论输入框等需要用户信息的场景下，SDK 会触发commentCheck。2：自定义鉴权模式。观众在进入直播间时使用的是您自定义的用户信息，因此可以直接发送评论等。
signToken
string
是
无
用户进入直播间或点播间的授权 Token。
token与signToken至少需传入其中一个参数；当两者同时传入时，以signToken为准。不同鉴权模式（mode）下，signToken的获取方式不同。详情参考获取直播间登录秘钥中使用说明一节。token
String
是
无
用户进入直播间时的授权 Token。
token与signToken至少需传入其中一个参数；当两者同时传入时，以signToken为准。不同鉴权模式（mode）下，token的获取方式不同：mode取值为1时，您可通过调用 GetSDKTokenAPI 接口获取用户 Token，也可以在企业直播控制台直播间内的观看页管理 > 页面嵌入 > Web SDK嵌入中获取用户 Token。mode取值为2时，您可通过调用 GetSDKTokenAPI 接口获取用户 Token。
options
Partial<Options>
否
-
可选配置项。
功能实现：自定义跳转逻辑
观众在小程序内点击菜单内商品卡片、浮窗商品卡片和浮标广告时，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 支持自定义跳转逻辑的功能以及相关事件和观看页位置如下表所示。
功能 | 事件 | 观看页位置 |
|---|---|---|
菜单内商品卡片 | ||
浮窗商品卡片 | ||
浮标广告 |