> For the complete documentation index, see [llms.txt](https://polyv.gitbook.io/document/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://polyv.gitbook.io/document/docs/live/miniprogram/mini_app_live_plugin.md).
# 保利威云直播小程序播放插件
保利威云直播小程序播放插件提供了开箱即用的直播播放器，为客户在小程序端快速接入直播能力提供了有力支持。
## 快速接入
注意：请确保您的小程序具备**电商平台**或**在线视频课程**类目，否则无法使用本插件（详见[微信小程序相关文档说明](https://developers.weixin.qq.com/miniprogram/introduction/plugin.html#%E5%BC%80%E6%94%BE%E8%8C%83%E5%9B%B4%E5%8F%8A%E6%9C%8D%E5%8A%A1%E7%B1%BB%E7%9B%AE)）。
在接入过程中，除了本文档，也可以参阅官方的[小程序插件使用说明](https://developers.weixin.qq.com/miniprogram/dev/framework/plugin/using.html)。
### 添加插件
在小程序管理后台的“设置-第三方服务-插件管理”中查找并添加插件，有两种查找方式：
* 通过 appid 查找。填写 **wxfb2e591959a8bacf** ，搜索插件并添加。
* 通过插件名称查找。填写 **Polyv观看** ，搜索插件并添加。
### 引入插件代码包
如无特殊情况，请尽量使用插件的最新版本。
```json
// 使用插件前，使用者要在 app.json 中声明需要使用的插件
"plugins": {
"polyv-live-player": {
"version": "0.11.0",
"provider": "wxfb2e591959a8bacf"
}
}
```
```json
// 使用插件提供的自定义组件。在 json 文件定义需要引入的自定义组件时，使用 plugin:// 协议指明插件的引用名和自定义组件名
"usingComponents": {
"polyv-live-player": "plugin://polyv-live-player/live-player"
}
```
### 调用播放器组件
```html
```
## API
### 参数说明
```javascript
videoOption: {
uid: '',
cid: '',
// 自动切换直播/暂存
isAutoChange: true,
// 画中画，同微信小程序video的 picture-in-picture-mode
pipMode: [],
// statistics 设置自定义统计参数
statistics: {
param1: 'param1',
param2: 'param2',
param4: 'param4',
param5: 'param5'
},
// 自动播放，默认true
autoplay: true,
// 回放视频循环播放，默认false
vodLoop: true,
// 回放指定视频初始播放位置, 单位秒
vodInitialTime: 20
},
// app参数设置
appSetting: {
// polyv后台appId
apiId: appId,
// 加密sign， 需要channelId, appId, timestamp 3个参数按照加密规则生成参数
sign,
// 时间戳
timestamp,
},
/**
* controls: Array | null | string
* 方式1: Array: ["play", "progress", "fullscreen", "refresh", "setting"]
* play：播放/暂停按钮
* progress：进度条
* fullscreen：全屏按钮
* refresh：刷新按钮（仅直播支持
* setting: 设置按钮 (回放 + 直播)
*
* 方式2: controls: null 不显示控制栏
*
* 方式3：controls: 'default' 显示默认的控制栏
**/
controls: ["play", "progress", "fullscreen", "refresh", "setting"]
```
### 播放器接口
#### 获取组件的实例
```javascript
// 假设插件的组件id为polyvPlayer
const polyvVideoContext = this.selectComponent('#polyvPlayer');
```
#### getVideoContext(): [VideoContext](https://developers.weixin.qq.com/miniprogram/dev/api/media/video/VideoContext.html) | [LivePlayerContext](https://developers.weixin.qq.com/miniprogram/dev/api/media/live/wx.createLivePlayerContext.html)
获取当前播放视频的上下文，具体内置方法，请参考微信官方文档。
#### getLiveType() :'live' | 'warmImage' | 'warmVideo' | 'vod' | ''
获取当前的直播状态。返回值说明：
* ''：播放器初始化未完成时，liveType为空字符串。
* 'live'：处于直播状态。
* 'warmImage'：处于显示暖场图片或暂无直播状态。
* 'warmVideo'：处于暖场视频状态。
* 'vod'：处于暂存回放状态。
#### destroy() : void
销毁播放器（逻辑上销毁）。UI 界面请通过 wx:if 控制。
### 播放器事件
#### 使用示例
```html
```
#### onLiveTypeChange
liveType 发生改变时触发。
示例：
```javascript
onLiveTypeChange(e) {
// e.detail 即为状态的字符串表示（见 getLiveType 的返回值说明）
console.log('liveType:', e.detail);
}
```
#### onLiveStorageProgress
适用于直播回放、暖场等场景，在进度发生改变时触发。
示例：
```javascript
onLiveStorageProgress(e) {
// e.detail.currentTime 为当前视频的播放进度
console.log('onLiveStorageProgress', e.detail.currentTime);
}
```
#### onLiveVodWaiting
适用于回放等场景，在播放发生缓冲时触发。
示例：
```javascript
onLiveVodWaiting() {
console.log('onLiveVodWaiting');
},
```
#### onLiveVodEnd
适用于直播回放、暖场等场景，在播放结束时触发。
示例：
```javascript
onLiveVodEnd() {
console.log('onLiveVodEnd');
},
```
#### onChannelDetailReq
频道详情接口请求成功后触发的事件。
示例：
```javascript
onChannelDetailReq(e) {
// e.detail 为频道详情数据
console.log('onChannelDetailReq', e.detail);
},
```
#### onLiveStatusChange
直播状态改变时触发。
示例：
```javascript
onLiveStatusChange(e) {
// status 为当前直播状态的字符串表示，有 'live' 和 'end' 两个取值
// sessionId 为直播场次
console.log('onLiveStatusChange', e.detail.status, e.detail.sessionId)
}
```
## 扩展
本插件仅具备视频播放能力，如需实现直播介绍、聊天室、连麦等功能，可参考[微信小程序SDK](https://help.polyv.net/#/live/js/mini_app_sdk_3)进行集成。
## Change log
### v0.11.0
* 缓冲loading显示逻辑优化
### v0.10.1
* 插件bug修复。
### v0.10.0
* 新增播放组件参数autoplay、vodLoop、vodInitialTime。
* 新增回放缓冲事件onLiveVodWaiting。
### v0.9.0
* 新增回放功能。
### v0.8.0
* 支持低延迟播放。
### v0.7.0
* 增加小窗播放参数。
* 新增获取视频上下文实例的方法 getVideoContext()。
### v0.6.0
* 优化初始化的加载速度。
### v0.5.0
* 新增参数控制播放器控制栏的元素, 参数controls，不传这个参数时显示默认控制栏，传空数组时不显示控制栏，传非空数组时根据数组内容显示对应的元素。
* 新增事件 onChannelDetailReq 返回频道详情数据。
* 新增事件：onLiveTypeChange。
* 新增接口：getLiveType。
* 修复 全屏状态下，回放切直播之后退出全屏。
* 修复 播放器控件栏会先出现直播的控制栏，再切到回放的控制栏。
### v0.2.0\~0.4.0
* Bug 修复。
### v0.1.0
* 保利威云直播小程序播放插件发布。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://polyv.gitbook.io/document/docs/live/miniprogram/mini_app_live_plugin.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.