集成抖音小程序 SDK

视频点播为抖音小程序播放场景提供播放器、日志上报、滑动切换等一系列 SDK 和组件，助您实现需要的业务功能。

• 播放器 SDK：提供完善的播放控制与良好的交互体验。

• 日志上报 SDK：支持上报播放日志，覆盖播放量、播放失败率、首帧时间、卡顿率等播放指标，与质量平台配合使用，可实现精细化的指标统计、实时的数据监控和深度的指标分析。

• 滑动切换组件：在视频竖屏上下滑动的播放场景中，实现流畅顺滑的切换效果。

具体效果如下：

前提条件

您需要在小程序后台 > 开发 > 开发设置 > 服务器域名中添加日志上报域名 https://mcs.zijieapi.com。

操作截图示例如下。

添加依赖

# npm
npm i veplayer-mp-douyin  // 播放器 SDK
npm i veplayer-mp-logger  // 日志上报 SDK
npm i veplayer-mp-swiper-douyin // 滑动切换组件

# yarn 
yarn add veplayer-mp-douyin  // 播放器 SDK
yarn add veplayer-mp-logger  // 日志上报 SDK
yarn add veplayer-mp-swiper-douyin // 滑动切换组件
        

构建 npm 包

在抖音开发者工具编辑器左侧功能栏 NPM功能:依赖管理中点击 npm 构建。

引入

在页面的 JSON 文件中引入 SDK 和组件。详情请参考抖音小程序自定义组件的使用方式。

{
  "usingComponents": {
    "veplayer": "ext://veplayer-mp-douyin/veplayer" // 播放器 SDK
    "veplayer-swiper": "ext://veplayer-mp-swiper-douyin/veplayer-swiper", // 滑动切换组件容器
    "veplayer-swiper-item": "ext://veplayer-mp-swiper-douyin/veplayer-swiper-item" // 滑动切换组件播放器容器
  }
}

使用

使用日志上报 SDK

1. 在火山引擎视频点播控制台，新建应用并获取应用 ID（App ID）。

   

2. 引入日志上报 SDK，并在页面加载前设置日志上报 SDK 的构造器。代码示例如下所示：

   import { initCollector } from 'veplayer-mp-logger'
   
   initCollector({
     appId: xxxx, // 火您可在火山引擎视频点播控制台上获取应用 AppID
     userId: '7231102**007992', // 用户 ID，强烈建议您使用与业务相关的用户 ID。如不传入，SDK 将随机生成一个值
   })
   

   说明

   • 上述代码示例采用了 ES6 写法，该写法需要开启相关配置：在抖音开发者工具的工程配置下，勾选 ES6 转 ES5。
   • 请注意 setCollector 方法第二项参数中的 userId。这是用于识别单一用户的 ID。强烈建议您使用与业务密切相关的用户 ID，以便在播放过程中出现错误时，可以进行单点故障排查，精确定位问题。如果您没有设定用户 ID，组件将随机生成一个。
   • 如果你想要在不使用火山引擎小程序播放器 SDK 的情况下，也能够进行播放日志上报，请参考 veplayer-mp-logger。

使用播放器 SDK

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

   <view>
     <!-- 以下是对小程序播放器 SDK 的引用 -->
     <veplayer
       id="videoContainer"
       src="{{src}}"
       muted
       loop
       logInfo="{{logInfo}}"
     />
   </view>
   

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

   // 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 分钟的延时。如果长时间看不到数据，可能是因为您通过开发者工具模拟器或桌面端微信播放的小程序数据被过滤掉了。

使用滑动切换组件

滑动切换组件包含以下两个部分：

• veplayer-swiper: 基于抖音小程序开放平台的 swiper 开发，可作为轮播视图的容器。
• veplayer-swiper-item: 基于抖音小程序开放平台的 swiper-item 开发，可作为播放器的容器。

引用组件

在 player/index.ttml 文件引用 veplayer-swiper 和 veplayer-swiper-item 组件。请注意以下参数的设置：

• index：播放列表的序号。
• current：swiper 激活项，需要与 veplayer-swiper 的 current 保持一致。
• videoId：为播放器内原生 video 组件的 ID，也对应小程序播放器 SDK 的 componentId 属性。videoId 作用是在切换视频时实现自动播放的效果，因此请确保在播放列表中，每一项的 videoId 是唯一的。

此外，为了实现用户第一次进入播放页面时以及选集后自动播放视频，推荐将播放器的 autoplay 属性设置为 autoplay="{{index === current}}"。

示例代码如下：

<veplayer-swiper
  current="{{current}}"
  class="swiper"
  bindchange="onChange"
  bindanimationfinish="onAnimationfinish"
  bindtransition="onTransition"
>
  <block
    tt:for="{{list}}"
    tt:for-item="item"
    tt:for-index="index"
  >
    <veplayer-swiper-item
      videoId="{{item.vid}}"
      poster="{{item.poster}}"
      index="{{index}}"
      current="{{current}}"
      preloadSrc="{{item.src}}"
    >
      <view slot="video" style="width: 100%; height:100%; position: relative">
        <veplayer
          src="{{item.src}}"
          poster="{{item.poster}}"
          autoplay="{{index === current}}"
          componentId="{{item.vid}}"
          playBtnPosition="bottom"
          enableProgressGesture="{{true}}"
          enablePlayGesture="{{true}}"
          bindended="onEnded"
          bindplay="onPlay"
          bindpause="onPause"
        ></veplayer>
        <!-- 业务功能点赞 -->
        <view style="right: 20px; top:50%; position: absolute; color: #fff">❤️</view>
      </view>
    </veplayer-swiper-item>
  </block>
</veplayer-swiper>

在 player/index.js 文件中，您需要监听 veplayer-swiper 的 change 事件，更新 current 的值。示例代码如下：

const videoList = [
  {
    vid: 'v0ddfag10001c*****k63casl9ed0',
    poster: 'https://demo.video.com/poster.jpg',
    src: 'https://demo.video.com/video.mp4',
    des: '',
  },
  // ...
];

Component({
  data: {
    current: 0,
    list: VideoList
  },
  onChange(e) {
    // 监听 veplayer-swiper 的 change 事件，更新 current 的值
    this.setData({ current: e.detail.detail.current });
  },
})

自动播放下一集

您可以监听 onEnded 事件。在该事件的回调函数中，设置 veplayer-swiper 和veplayer-swiper-item 这两个组件的 current 属性。这样一来，播放完当前集之后，小程序就会自动播放下一集。

示例代码如下：

<veplayer
   slot="video"
   src="{{item.src}}"
   poster="{{item.poster}}"
   autoplay="{{index === current}}"
   componentId="{{item.vid + item.src}}"
   playBtnPosition="bottom"
   enableProgressGesture="{{true}}"
   enablePlayGesture="{{true}}"
   bindended="onEnded"
 ></veplayer>

onEnded() {
    const { current, list } = this.data;
    if (current + 1 < list.length) {
    // 设置 swiper 的 current 属性
      this.setData({ current: current + 1 });
    } else {
      tt.showToast({
        title: '看完了!',
        duration: 2000,
      });
    }
  }

选择或者跳转剧情

如果您希望实现在剧集列表中通过点击剧集按钮来使播放器跳转至特定剧集，可设置veplayer-swiper 的 current 属性。

示例代码如下：

onSelectChange(e) {
    this.setData({
    // 设置指定剧集的序号跳转到指定剧集
      current: target
    });
  }

播放器 SDK API

属性

播放器 SDK 封装了抖音原生 video 视频组件，支持配置大部分的 video 属性。原生 video 视频组件支持的属性详见抖音官方文档。

下表展示播放器 SDK 的新增属性及差异化属性。

{
  immersive: boolean, // 是否启用半沉浸式
  delay?: number, // 进入半沉浸状态/隐藏状态的延迟
  focusDelay?: number, // 隐藏态进入 focus 态是否自动切换
}

{
 immersive: false,
 delay: 10000,
 focusDelay: 0
}

event.detail = {currentTime, duration} // 触发频率 250ms 一次

event.detail = {fullScreen, direction} // direction 有效值为 vertical 或 horizontal

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

event.detail = {width, height, duration}

event.detail={playbackRate}。

接口

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

let player = null
// 异步获取组件内 video 的 VideoContext
const component = this.selectComponent("#videoContainer", (component) => {
  player = component.getContext()
  // 原生接口
  player.play()
  player.pause()
  player.stop()
  player.seek(10)
  player.requestFullScreen()
  player.exitFullScreen()
  player.setWaterMark({ color: "#FFFF11" })
  player.setMediaVolume({ value: 1})
  player.getMediaVolume(options)
  player.playbackRate(1)
  player.requestFullScreen({ direction: 90 })
  player.exitFullScreen()
});
// 同步获取组件内 video 的 VideoContext，需要保证是在 page 或者 component 的 ready 事件之后才能正常调用
// player = this.selectComponent("#videoContainer").getContext();
// player.play()
// ...

事件

播放器 SDK 提供两种方式进行事件监听：

• 通过 bind 属性对组件进行事件监听。
• 使用组件对象提供的事件订阅机制。

我们建议您在使用时，选择其中一种方式进行事件订阅，而不是同时使用两种方式。这两种方式都已在组件实例中实现了组件从页面节点树移除（lifetimes->detached）时的事件解绑，因此，您无需单独处理事件泄漏的问题。

通过 bind 属性对组件进行事件监听

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

使用组件对象提供的事件订阅机制

播放器 SDK 提供接口用于获取 player context。您可为 player 添加事件订阅，从而实现任意时刻对各种播放事件添加和移除监听。代码示例如下：

let player = null
const component = this.selectComponent("#videoContainer", (component) => {
  player = component.getContext()
  // 事件订阅
  player.on('error', (e) => {
    console.log('event error:', e)
  })
  player.on('timeupdate', (e) => {
    const { currentTime, duration } = e.detail;
    console.log('event error:', currentTime, duration)
  })
  ...
});

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

滑动切换组件 API

veplayer-swiper 组件属性

veplayer-swiper-item 组件属性

veplayer-swiper-item 组件插槽

veplayer-swiper-item 组件提供了两个具名插槽 slot：

• video 插槽：此插槽用于放置播放器。对于播放器类型没有限制，但请确保播放器的原生 video 属性必须绑定一个唯一 ID。这个 ID 需要传递给 veplayer-swiper-item 的 videoId 属性，用于控制视频的播放与暂停。

• placeholder 插槽：此插槽用于播放器未渲染时的占位。如果你没有设置此插槽，那么默认会使用封面图片地址 poster 作为占位图。