> 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
<!--
videoOption 为视频配置
controls 为控制栏配置
appSettings 为鉴权配置
配置字段见 API 说明
-->
<polyv-live-player
  id="polyvPlayer"
  videoOption="{{videoOption}}"
  controls="{{controls}}"
  appSetting="{{appSetting}}"
>
</polyv-live-player>
```

## 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
<polyv-live-player
  id="polyvPlayer"
  videoOption="{{videoOption}}"
  appSetting="{{appSetting}}"
  bind:onChannelDetailReq="onChannelDetailReq"
  bind:onLiveStatusChange="onLiveStatusChange"
  bind:onLiveTypeChange="onLiveTypeChange"
>
</polyv-live-player>
```

#### 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

* 保利威云直播小程序播放插件发布。