# 短剧播放器接口

本文主要介绍下短剧播放器插件提供的几个接口，在 JS 代码里，插件接口示例通过下面的代码获取

```javascript
// 名字 playlet-plugin 必须和 app.json 里面引用的插件名一致
const playletPlugin = requirePlugin('playlet-plugin')
```

## playletPlugin.onPageLoad()

onPageLoad就是播放器页面的 onLoad 事件，接受的参数是函数，直接在 app.js 的 onLaunch 里面调用即可

```javascript
App({
  onLaunch(options) {
    playletPlugin.onPageLoad(this._onPlayerLoad.bind(this))
  },
  _onPlayerLoad(info) {
    console.log('onPlayerLoad', info.playerId, info)
    // 在这里可以调用
    const pm = playletPlugin.PlayletManager.getPageManager(info.playerId)
    console.log('get playlet manager', pm)
  },
})
```

## playletPlugin.getPluginVersion()

接口返回当前的插件版本，例如 0.1.4

## playletPlugin.getShareParams()

接口返回 Promise 实例，当从App跳转、分享、公众号、二维码等场景，直接进入到播放器页面的时候，开发者可通过此接口获取跳转到页面链接上的参数。

> 注意：如果不是直接进入播放器页面的，返回 `Promise.reject({err: '首个页面不是播放器页面'})`。

```javascript
playletPlugin.getShareParams().then(res => {
    console.log('getShareParams res', res)
}).catch(err => {
    console.log('getShareParams err', err)
})
```

## playletPlugin.setLoggerConfig(Object param)

设置播放器插件的日志输出：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| info | boolean | 否 | 是否输出 info 日志，默认为 false |
| debug | boolean | 否 | 是否输出 debug 日志，默认为 false |
| log | boolean | 否 | 是否输出 log 日志，默认为 false |
| warn | boolean | 否 | 是否输出 warn 日志，默认为 true |
| error | boolean | 否 | 是否输出 error 日志，默认为 true |

## playletPlugin.PlayletManager

PlayletManager 是一个类，可通过 `playletPlugin.PlayletManager.getPageManager(playerId)` 获取其实例，大部分的接口都在该实例对象上提供，例如 `getInfo`、`showChargeDialog` 等。获取 PlayletManager 示例如下：

```javascript
App({
  onLaunch(options) {
    playletPlugin.onPageLoad(this._onPlayerLoad.bind(this))
  },
  _onPlayerLoad(info) {
    console.log('onPlayerLoad', info.playerId, info)
    // 在这里可以调用
    const pm = playletPlugin.PlayletManager.getPageManager(info.playerId)
    console.log('get playlet manager', pm)
  },
})
```

在很多接口，都可以获取到 playerId，例如 onPageLoad 事件、充值组件、运营组件等，然后通过 playerId 可以获取到 PlayletManager 实例。

PlayletManager 实例的更多接口介绍如下：

### PlayletManager.setCanPlaySerialList(Object param)

初始化剧集状态，接受的参数字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| serialList | `Array<SerialItem>` | 否 | 剧集状态列表 |
| data | string | 否 | 剧集状态的加密串 |
| freeList | `Array<FreeItem>` | 否 | 免费剧集列表，注意：此字段仅改变目录中的剧集显示 UI，并不会做真正的解锁处理 |

serialList 和 data 选填一项即可，两者的区别是 serialList 无需加密，而 data 则为加密串，加密方式可参考[短剧播放器加密方案章节](videoplayer#_3-2-7-数据加密方案)。选用加密方案的话安全性相对较高，但性能会有所损耗，可根据实际情况选用对应方案。

SerialItem 字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| start_serial_no | number | 是 | 起始免费剧集编号，从 1 开始 |
| end_serial_no | number | 是 | 结束免费剧集编号，包含此集 |
| status | number | 是 | 上面的起始和结束区间内剧集是否解锁；1 - 已解锁，2 - 未解锁 |

FreeItem 字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| start_serial_no | number | 是 | 起始免费剧集编号，从 1 开始 |
| end_serial_no | number | 是 | 结束免费剧集编号，包含此集 |

```javascript
// 无需加密方案
pm.setCanPlaySerialList({
  serialList: [{
    start_serial_no: 1,
    end_serial_no: 4,
    status: 1, // 解锁
  }, {
    start_serial_no: 5,
    end_serial_no: 20,
    status: 2, // 未解锁
  }],
})

// 加密方案
const data = await getEncryptData() // getEncryptData 需要开发者自行实现
pm.setCanPlaySerialList({
  data,
})
```

### PlayletManager.setFreeList(Object param)

在用户观看过程中重新设置免费剧列表，注意：此接口仅改变目录中的剧集显示 UI，并不会做真正的解锁处理。接受的参数字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| list | `Array<FreeItem>` | 否 | 免费剧集列表 |

FreeItem 字段定义如下：

|字段名 |类型 |必填 |描述 |
|:--:|:--:|:--:|:--|
| start_serial_no | number | 是 | 起始免费剧集编号，从 1 开始 |
| end_serial_no | number | 是 | 结束免费剧集编号，包含此集 |

### PlayletManager.getInfo()

获取当前剧集信息，返回 Object 字段定义如下：

| 字段名 | 类型 | 描述 |
|:--:|:--:|:--|
| playerId | string | 播放器页面唯一 ID，可通过此参数获取到 PlayletManager 实例 |
| srcAppid | string | 提审方 appid |
| dramaId  | string | 媒资管理后台上传的剧目 id |
| serialNo | number | 当前播放到第几集 |
| extParam | string | 扩展参数 |

> 注意：以上为固定常用字段，页面路径上的其他参数也会在此处返回。

### PlayletManager.onCheckIsCanPlay(Function func)

播放到需要解锁的剧集会触发此事件，开发者可在此事件内解锁剧集。

| 参数名 | 类型 | 描述 |
|:--:|:--:|:--|
| serialNo | number | 剧集 ID |
| isRetry | boolean | 是否因重试而触发。当遇到可能由于 session_key 过期等原因引发解密失败时，插件会重试一次触发 onCheckIsCanPlay |
| needToCancelAdTimer | boolean | 当前剧集是否可以取消展示广告倒计时弹窗 |

### PlayletManager.isCanPlay(Object param)

设置剧集解锁状态，接受的参数字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| serialList | `Array<SerialItem>` | 否 | 剧集状态列表 |
| data | string |否 | 剧集状态的加密串 |
| serialNo | number |是 | 剧集ID |
| useLastStatus | boolean |否 | 表示维持之前设置的剧集未解锁状态，此字段设置为 true 时可不传 serialList/data 字段，使用**免开发激励视频广告**解锁时不可使用此字段 |

类似 setCanPlaySerialList 接口，serialList 和 data 选填一项即可，两者的区别是 serialList 无需加密，而 data 则为加密串，加密方式可参考[短剧播放器加密方案章节](videoplayer#_3-2-7-数据加密方案)。选用加密方案的话安全性相对较高，但性能会有所损耗，可根据实际情况选用对应方案。

SerialItem 字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| start_serial_no | number | 是 | 起始免费剧集编号，从 1 开始 |
| end_serial_no | number | 是 | 结束免费剧集编号，包含此集 |
| status | number | 是 | 上面的起始和结束区间内剧集是否解锁；1 - 已解锁，2 - 未解锁 |

```javascript
// 无需加密方案
pm.onCheckIsCanPlay(param => {
  pm.isCanPlay({
    serialNo: 15,
    serialList: [{
      start_serial_no: 15,
      end_serial_no: 15,
      status: 1, // 解锁
    }],
  })
})

// 加密方案
pm.onCheckIsCanPlay(async param => {
  const data = await getEncryptData() // getEncryptData 需要开发者自行实现
  pm.isCanPlay({
    serialNo: 15,
    data,
  })
})

// 维持原本的未解锁状态
pm.onCheckIsCanPlay(param => {
  pm.isCanPlay({
    serialNo: 15,
    useLastStatus: true,
  })
})
```

### PlayletManager.onShowChargeDialog(Function func)

监听充值弹窗打开事件

### PlayletManager.offShowChargeDialog(Function func)

取消监听充值弹窗打开事件

### PlayletManager.onHideChargeDialog(Function func)

监听充值弹窗关闭事件

### PlayletManager.offHideChargeDialog(Function func)

取消监听充值弹窗关闭事件

### PlayletManager.hideChargeDialog()

关闭充值弹窗

### PlayletManager.showChargeDialog()

打开充值弹窗

### PlayletManager.play()

继续播放

### PlayletManager.pause()

暂停播放

### PlayletManager.onDataReport(Function func)

监听播放器内各个功能的相关事件

### PlayletManager.onBack(Function func)

监听播放器内左上角返回点击事件

### PlayletManager.changeDrama(Object param)

更换剧目，接受的参数字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| queryString | string |是 | key=value&key1=value1 格式的参数 |

### PlayletManager.updateChargeDialogInfo(Object param)

更新充值弹窗，接受的参数字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| isTransparentBackground | boolean | 否 | 弹窗背景是否为透明，默认为 false |
| isDestroyOnHide | boolean | 否 | 每次收起充值弹窗后是否销毁充值组件，默认为 false |
| maskTransparent | boolean | 否 | 弹窗遮罩是否为透明，默认为 false |
| maskClosable | boolean | 否 | 是否可点击弹窗遮罩来关闭弹窗，默认为 true |

### PlayletManager.updateChargeDialogHeight(Object param)

更新充值弹窗高度，接受的参数字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| height | number | 是 | 设置充值弹窗高度 |

### PlayletManager.setVisualEffectOnCapture(Object param)

接口含义和参数同 wx.setVisualEffectOnCapture

### PlayletManager.setDramaFlag(Object param)

设置分享参数，接受的参数字段定义如下：

|字段名 |类型 |必填 |描述 |
|:--:|:--:|:--:|:--|
| share | boolean | 是 | 是否打开分享，默认 true |
| withShareTicket | boolean | 否 | 同小程序分享的 withShareTicket，默认 true |

### PlayletManager.setExtParam(string extParam)

修改 extParam 参数

### PlayletManager.setCustomer(Object param)

设置客服按钮

|字段名 |类型 |必填 |描述 |
|:--:|:--:|:--:|:--|
| isShow | boolean | 是 | 是否展示客服按钮，默认 false |

### PlayletManager.onCustomEvent(string name, Function func)

监听自定义事件，用于在充值组件、playletManager、自定义运营位等组件间通信

### PlayletManager.offCustomEvent(string name, Function func)

取消监听自定义事件

### PlayletManager.emitCustomEvent(string name, Function func)

触发自定义事件

### PlayletManager.updateOpenArea(Object param)

设置自定义开放区域参数，接受的参数字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| showLeft | boolean | 否 | 是否显示组件 open-area-left，默认为 false |
| leftWidth | number | 否 | 设置组件 open-area-left 的宽度 |
| leftHeight | number | 否 | 设置组件 open-area-left 的高度 |
| leftsideAreaList | `Array<LeftSideOption>` | 否 | 设置多个 open-area-left-side 组件，数组每一项为 LeftSideOption 对象 |
| ext | string | 否 | 自定义参数，组件 open-area-left、open-area-right、open-area-left-side 均可通过属性获取到此参数 |

LeftSideOption 对象定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| left | number | 否 | 设置组件的距离渲染区域左边缘位置，如果传了 right 则默认为 auto，未传则默认为 0 |
| top | number | 否 | 设置组件的距离渲染区域上边缘位置，如果传了 bottom 则默认为 auto，未传则默认为 0 |
| right | number | 否 | 设置组件的距离渲染区域右边缘位置，默认为 auto |
| bottom | number | 否 | 设置组件的距离渲染区域下边缘位置，默认为 auto |
| width | number | 否 | 设置组件宽度 |
| height | number | 否 | 设置组件高度 |
| wxKey | string | 否 | 这一项的 key，用于插件里遍历列表时填入 wx:key 中，未传则默认为该项在列表中的下标 |

> 注意：在 LeftSideOption 也可以传一些额外的字段，在 open-area-left-side 组件的 item 属性中可以接收到这些字段

### PlayletManager.setVideoOption(Object param)

设置播放器的播放配置，接受的参数字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| objectFit | string |否 | 同 video 组件的 object-fit 属性，默认会根据视频宽高进行计算 |
| aspectRatio | number |否 | 视频高宽比，当 objectFit 为 fill 时有效 |
| loop | boolean | 否 | 是否循环播放，默认 false |

### PlayletManager.startBackgroundPreview(Object param)

设置剧集未解锁时的视频预览播放，接受的参数字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| loop | boolean | 否 | 是否循环播放，默认为 true |
| mask | boolean | 否 | 是否显示遮罩，默认为 true |
| muted | boolean | 否 | 是否静音，默认为 true |

### PlayletManager.stopBackgroundPreview()

停止剧集未解锁时的视频预览播放。

### PlayletManager.setActivityInfo(Object param)

设置运营活动位，接受的参数字段定义如下：

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| url | string | 是 | 活动页面的路径 |
| logo | string | 否 | 显示的 icon 的 url |

### PlayletManager.setUseAdUnlock(Object param)

设置需要广告解锁的剧集。注意：设置为广告解锁后，该剧集在选集列表中的样式会表现为免费剧集；在解锁页中则会有广告解锁专属 UI

| 字段名 | 类型 | 必填 | 描述 |
|:--:|:--:|:--:|:--|
| list | `Array<AdUnlockItem>` | 否 | 免费剧集列表 |

AdUnlockItem 字段定义如下：

|字段名 |类型 |必填 |描述 |
|:--:|:--:|:--:|:--|
| start_serial_no | number | 是 | 起始免费剧集编号，从 1 开始 |
| end_serial_no | number | 是 | 结束免费剧集编号，包含此集 |

### PlayletManager.onUseAdUnlock(Function func)

当进入了需要广告解锁的剧集，用户点击解锁页中的解锁按钮时会触发此事件

### PlayletManager.navigateTo(Object param)

接口含义和参数同 wx.navigateTo。

> 注意：接口调用成功的前提是用户必须至少点击过页面。

### PlayletManager.navigateBack(Object param)

接口含义和参数同 wx.navigateBack。

> 注意：接口调用成功的前提是用户必须至少点击过页面。

### PlayletManager.redirectTo(Object param)

接口含义和参数同 wx.redirectTo。

> 注意：接口调用成功的前提是用户必须至少点击过页面。

### PlayletManager.switchTab(Object param)

接口含义和参数同 wx.switchTab。

> 注意：接口调用成功的前提是用户必须至少点击过页面。

### PlayletManager.reLaunch(Object param)

接口含义和参数同 wx.reLaunch。

> 注意：接口调用成功的前提是用户必须至少点击过页面。