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

• 播放器 SDK：提供丰富的播放控制功能和良好的用户交互体验。SDK 还支持播放日志上报功能，用于统计播放量、播放失败率、首帧时间、卡顿率等播放指标。通过与质量平台的配合，您可以进行精细化的指标统计、实时的数据监控和深入的指标分析。
• 滑动切换组件：在视频竖屏上下滑动的播放场景中，实现流畅顺滑的切换效果。

具体效果如下：

前提条件

• 在小程序后台 > 开发 > 开发设置 > 服务器域名中添加日志上报域名 https://mcs.zijieapi.com。操作截图示例如下。
  

  说明

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

• 在视频点播控制台新建应用并获取应用 ID。具体步骤请见创建应用。
  

添加依赖

# npm
npm i veplayer-mp-douyin  // 播放器 SDK
npm i veplayer-mp-swiper-douyin // 滑动切换组件

# yarn 
yarn add veplayer-mp-douyin  // 播放器 SDK
yarn add veplayer-mp-swiper-douyin // 滑动切换组件

构建 npm 包

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

引入 SDK

在页面的 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

使用播放器 SDK

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

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

您需要在对应应业务组件中添加日志上报所需的配置，如下表所示：

示例代码如下：

// index.js
Component({
  data: {
    src: 'https://xxxx.mp4',
    // 配置日志上报
    logInfo: {
      appId: xxx,
      userId: "xxx",
      tag: 'recommend',
      subtag: 'hot',
    }
  }
})

查看日志上报数据

视频信息配置完成后，如需查看日志上报数据，可以按以下操作步骤进行：

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 继承了抖音小程序 video-player 组件提供的短剧行业能力，方便开发者通过抖音小程序内容库对短剧内容进行送审。

前提条件

• 按照抖音开放平台文档配置行业 SDK 的权限。
• 短剧行业能力依赖于抖音小程序 video-player 组件。video-player 只在抖音 23.8 以上版本支持。播放器组件会自动使用 tt.canIUse('video-player') 校验用户的抖音版本能否支持 video-player 组件。

实现方式

在项目中引用播放器 SDK 时，传入album-id（原片 ID）和 episode-id（剧集 ID）。播放器 SDK 会通过这两个 ID 从抖音小程序内容库中获取视频播放地址。
示例代码如下：

<veplayer
  id="video"
  tt:ref="refHandler"
  album-id="{{aid}}"
  episode-id="{{eid}}"
  autoplay="{{true}}"
  bindgetsource="getSource"
  ...
></veplayer>

在对应业务组件中添加播放配置，示例代码如下：

Component({
  // ...
  data: {
    aid: 'x32432w',
    eid: 'xxsddw',
    // 抖音 23.8 以下版本不支持短剧行业能力时使用的兜底地址
    degradeSrc: 'https://xx.demo.com/d.mp4'
  },
  methods: {
    refHandler(ref) {
      this.player = ref;
    },
    getSource(e){
      // do something
    },
    playVideo(){
      // do something
      const videoContext = this.player.media;
      videoContext.play()
    }
  }
})

播放器 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 作为占位图。