You need to enable JavaScript to run this app.
导航

集成微信小程序 SDK

最近更新时间2023.10.16 16:19:07

首次发布时间2023.06.06 17:46:16

视频点播支持微信小程序点播 SDK 组件的使用。本文为您介绍完成小程序播放器组件接入的全流程。

前提条件

小程序后台 > 开发 > 开发设置 > 服务器域名中添加以下域名配置:

日志上报域名:https://mcs.zijieapi.com

操作截图示例如下所示。

说明

视频资源的 CDN 域名不需要添加到域名配置中。

安装

# npm
npm i veplayer-mp-wechat
npm i veplayer-mp-logger

# yarn 
yarn add veplayer-mp-wechat
yarn add veplayer-mp-logger

构建 npm 包

说明

请优先了解微信小程序官网对于 npm 支持 的介绍。

您需要点击微信开发者工具菜单栏中的工具 > 构建 npm

引入组件

详情请参考微信官方文档小程序自定义组件的引入方式。引入微信小程序点播 SDK 的代码示例如下:

{
  "usingComponents": {
    "veplayer": "veplayer-mp-wechat"
  }
}

使用组件

配置播放器日志

  1. 您需要在火山引擎视频点播控制台新建应用并获取应用 ID(App ID)。

  2. 引入日志组件,在页面加载前设置数据采集 SDK 的构造器。

    代码示例如下所示:

    import { CollectorManager } from 'veplayer-mp-wechat/tool/index'
    import Collector from 'veplayer-mp-logger'
    
    CollectorManager.setCollector(Collector, {
      appId: 11***1,                  // 您在视频点播控制台中获取的应用 ID
      userId: '7231102***76007992'   // 用户 ID。强烈建议您使用与业务相关的用户 ID。如不传入,SDK 将随机生成一个值
     })
    

    说明

    • 上述代码示例是 ES6 写法,该写法需要开启相关配置:在微信开发者工具的本地设置下,勾选 将JS编译成ES5
    • 请注意 setCollector 方法第二项参数中的 userId。这是用于识别单一用户的 ID。强烈建议您使用与业务相关的用户 ID,以便在发生播放错误时进行单点排查,精准定位故障。如您没有设置用户 ID,SDK 将随机生成一个值。
    • 如果在不使用小程序点播 SDK 的情况下,也能够进行播放日志上报,具体操作请参考 veplayer-mp-logger

使用播放器组件

按照如下示例代码在项目中引用播放器。

<view>
  <!-- 以下是对小程序播放器组件的引用 -->
  <veplayer
    id="videoContainer"
    showPlayBtn
    autoplay
    src="{{src}}"
    logInfo="{{logInfo}}"
    bindplay="onPlay"
  />
</view>

对应业务组件中添加日志上报需要的视频信息配置,代码示例如下:

// index.js
Component({
  data: {
    src: 'https://xxxx.mp4',
    logInfo: {
      vtype: 'MP4',        // [可选]播放格式类型, 默认为 'MP4',可选值'HLS' || 'MP4' 
      codecType: 'h264',   // [可选]视频编码类型,默认 h264,'h264' || 'h265'
      sourceType: 'url',   // [可选]播放资源类型, 可选 'url'
      bitrate: 1334556,    // [可选]视频码率,默认为 0
      tag: 'myTag',        // [可选]播放场景
      subtag: 'subtag',    // [可选]二级播放场景
      logger: true,        // [可选] 是否开启 log 打印,默认 false, 开发环境可设置为 true
    }
  }
})

查看日志上报数据

视频信息配置完成后,查看日志上报数据的操作步骤如下:

  1. 登录视频点播控制台

  2. 单击左侧导航栏质量平台 > 播放看板,进入播放看板页面,选择大盘速览页签。

  3. 在查询条件中选择微信小程序。详细操作说明请见查看大盘速览

    注意

    小程序播放质量数据仅采集真机 Android 和 iOS 系统的数据。

    • 一般情况下,数据延时为 5~10 分钟。
    • 如果发现过去很久没有看到数据,可能的原因为您通过开发者工具模拟器桌面端微信播放的小程序数据均会被过滤。

组件属性

小程序播放器封装了 video 原生组件,支持配置大部分的 video 属性。原生组件支持的属性配置详情请参考微信官方文档。以下列表展示了新增属性及差异化属性。

说明

  • 列表中的部分属性以 show- 开头的开关,既影响原生组件,又影响自定义 UI。
  • 不在列表中的只影响原生组件。
  • 原生微信 video 组件的属性,如:show-play-btn 这类中划线分割的属性名,需要改写成驼峰式命名showPlayBtn
属性类型默认值是否必选说明

mode

'portrait' | 'landscape'

landscape

UI 模式。支持 2 种播放 UI 模式。取值如下:

  • portrait:竖屏。展示偏向于普通的 PC 视频播放器 UI 模式。

  • (默认值)landscape:横屏。展示类似抖音等短视频播放 UI 模式。

disableLogVerify

Boolean

false

关闭日志配置验证。取值如下:

  • false:否。如果没有配置日志,则会播放器报错。
  • true:是。关闭日志配置验证。

componentId

String

-

video 组件 ID。

  • 通过createVideoContext获取视频 VideoContext。

  • 不传,随机生成一个 ID,通过组件上下文的getContext()方法获取视频 VideoContext。

logInfoObject日志上报时用到的视频信息
srcString-播放视频的资源地址。支持网络路径、本地临时路径、云文件 ID等。

controls

'custom' | 'native'|false

custom

  • custom: 自定义 UI。

  • native: 原生组件 UI。

  • false: 完全关闭播放 UI 控件(包括自定义 UI 及原生组件UI)。

说明

播放 UI 控件指 loading 状态、播控按钮、进度条、时间显示等。

duration

number

-

指定视频时长。

说明

不会控制实际播放的时长。因此该属性不设置给原始 video 组件,只提供给自定义 UI 使用。

showCenterPlayBtn

Boolean

true

是否显示视频正中心的播放按钮。取值如下:

  • true:是

  • false:否

showBottomProgress

Boolean

true

是否展示底部进度条。取值如下:

  • true:是

  • false:否

needLoading

Boolean

true

是否显示 loading 加载标识。

说明

  • controls 属性取值为 custom 时,该 needLoading 属性生效。
  • v0.1.12之后的版本生效。
bindplayeventhandle-当开始/继续播放时触发 play 事件。
bindpauseeventhandle-当暂停播放时触发 pause 事件。
bindendedeventhandle-当播放到末尾时触发 ended 事件。

bindtimeupdate

eventhandle

-

播放进度变化时触发 timeupdate 事件。

event.detail = {currentTime, duration} 。

触发频率 250ms 一次。

bindfullscreenchange

eventhandle

-

视频进入和退出全屏时触发 fullscreenchange 事件。

event.detail = {fullScreen, direction} // direction 有效值为 vertical 或 horizontal
bindwaitingeventhandle-视频出现缓冲时触发 waiting 事件。
binderroreventhandle-视频播放出错时触发 error事件。

bindprogress

eventhandle

-

加载进度变化时触发 progress 事件,只支持一段加载。

event.detail = {buffered} //百分比

bindloadedmetadata

eventhandle

-

视频元数据加载完成时触发 loadedmetadata 事件。

event.detail = {width, height, duration}

bindcontrolstoggle

eventhandle

-

切换 controls 显示隐藏时触发 controlstoggle 事件。

event.detail = {show}
bindenterpictureinpictureeventhandle-播放器进入小窗 enterpictureinpicture 事件。
bindleavepictureinpictureeventhandle-播放器退出小窗 leavepictureinpicture 事件。

bindseekcomplete

eventhandle

-

seek 完成时触发 seekcomplete 事件。

说明

position 的单位区别如下:

  • 系统类型为 iOS,单位为 s。
  • 系统类型为 Android,单位为 ms。

组件接口

小程序播放器封装了 VideoContext,提供同原生接口一致的 API。代码示例如下所示。

const component = this.selectComponent("#videoContainer");
const player = component.getContext()

// 原生接口
player.play()
player.pause()
player.stop()
player.seek(10)
player.sendDanmu(Object data)
player.playbackRate(1)
player.requestFullScreen({ direction: 90 })
player.exitFullScreen()
player.exitPictureInPicture()
player.requestBackgroundPlayback()
player.exitBackgroundPlayback()

组件事件

微信小程序播放器对外支持 2 种方式的事件监听形式:

  • 组件属性 bind 方式事件监听

  • 组件对象提供事件订阅的机制进行事件监听

请选择其中一种进行订阅,尽量不要两者混用。这两种方式在组件实例中,被从页面节点树移除(lifetimes->detached)时,进行事件解绑,您无需单独关注事件泄漏的问题。

组件属性 bind 方式事件监听

请参见组件属性中 bind 开头的事件属性。

组件对象提供事件订阅的机制进行事件监听

小程序播放器提供了接口可以获取 player context,并可以对 player 添加事件订阅,从而实现任意时刻对各种播放事件添加/移除监听的功能。代码示例如下所示。

const component = this.selectComponent("#videoContainer");
const player = component.getContext();

// 事件订阅
player.on('error', (e) => {
  console.log('event error:', e)
});
player.on('timeupdate', (e) => {
  const { currentTime, duration } = e.detail;
  console.log('event timeupdate:', currentTime, duration)
});
// ...

详细的事件列表如下所示。

事件名称是否可自定义事件说明
play当开始/继续播放时触发 play 事件。
pause当暂停播放时触发 pause 事件。
ended当播放到末尾时触发 ended 事件。
timeupdate播放进度变化时触发。
fullscreenchange视频进入和退出全屏时触发 fullscreenchange 事件。
waiting视频出现缓冲时触发 waiting 事件。
error视频播放出错时触发 error 事件。
progress加载进度变化时触发 progress 事件,只支持一段加载。
loadedmetadata视频元数据加载完成时触发 loadedmetadata 事件。
controlstoggle切换 controls 显示隐藏时触发 controlstoggle 事件。
enterpictureinpicture播放器进入小窗 enterpictureinpicture 事件。
leavepictureinpicture播放器退出小窗 leavepictureinpicture 事件。
seekcompleteseek 完成时触发 seekcomplete 事件。