微信小程序点播插件试看

下载 PDF

下载 Word

适用版本：v1.19.1 及以上。

功能说明

配置 trialEnabled=true 和 trialDuration=60，即可试看正片前 60 秒。按视频时间轴判断，不累计实际观看时间，倍速播放仍在第 60 秒处结束；暂停不会消耗试看时间。普通视频和加密视频使用相同的前端限制。

到达试看边界后暂停，触发一次 trialEnded，event.detail 为 { vid, currentTime, trialDuration }，其中 currentTime 是试看边界。不会触发完整播放结束的 ended 事件或播放片尾。业务方可在该事件中显示购买引导；全屏引导可使用 custom 插槽。

<polyv-player
  id="player"
  vid="{{vid}}"
  trialEnabled="{{trialEnabled}}"
  trialDuration="{{60}}"
  bind:trialEnded="onTrialEnded"
/>

Page({
  data: { trialEnabled: true },
  onTrialEnded(e) {
    // 由业务方展示购买引导。
    this.setData({ showPurchase: true });
  },
  replayTrial() {
    const player = this.selectComponent('#player');
    player.seek(0);
    player.play();
  },
  onPurchaseVerified() {
    // 业务服务端确认购买成功后解除试看。
    this.setData({ trialEnabled: false }, () => {
      this.selectComponent('#player').play();
    });
  },
});

• startTime、公开 seek()、控制栏拖拽和画面横滑均受试看边界限制。微信原生控件越界后在下一次进度回调中暂停并校正位置。
• 试看期间不读取或写入本地续播进度，也不发起远端续播定位。视频原有总时长和进度条展示保持不变。
• 试看结束后直接播放、切换清晰度或音视频模式不会解除限制。调用 seek(0) 后 play() 可重新试看，也可跳到试看范围内的其他位置再播放；再次到达边界会再次触发事件。原生控件模式下同样用公开 seek() API 重置试看。
• 切换视频会重置试看结束状态。动态修改开关或时长立即重新判断边界；关闭试看后需调用 play() 继续播放。
• 试看时长小于视频时长时禁用循环播放；大于或等于视频时长时按原有逻辑正常结束、播放片尾或循环。
• 鸿蒙手机端开启有效试看（trialEnabled 为 true 且 trialDuration 为有限正数）时禁用路由小窗，包括试看结束后；关闭试看后恢复传入的 pictureInPictureMode。Android 和 iOS 的小窗配置不变。
• 该能力用于前端体验控制，停止时机受微信进度回调频率影响，不提供服务端付费访问控制。后台音频和小窗需在目标设备上验证回调与暂停行为。

接入属性

试看结束遮罩

试看结束后，默认使用半透明黑色遮罩覆盖整个播放器，居中显示“试看已结束”。重新试看、切换视频或关闭试看后自动隐藏。遮罩位于 video 内，随播放器进入全屏；遮罩拦截画面区域的点击和拖动，自定义控制栏位于遮罩上方，可使用全屏返回等操作。

外部小程序通过 trialMask 对象自定义；未填写的字段使用默认值：

<polyv-player
  id="player"
  vid="{{vid}}"
  trialEnabled="{{true}}"
  trialDuration="{{60}}"
  trialMask="{{trialMask}}"
  bind:trialAction="onTrialAction"
/>

Page({
  data: {
    trialMask: {
      text: '试看已结束，购买后观看完整视频',
      backgroundColor: 'rgba(0, 0, 0, 0.65)',
      color: '#ffffff',
      buttonText: '立即购买',
    },
  },
  onTrialAction(e) {
    // 点击遮罩或按钮均触发此事件，由宿主小程序打开自己的购买页面。
    // e.detail = { vid, trialDuration }
  },
});

trialEnded 用于接收“到时结束”通知；trialAction 用于接收用户点击购买引导的操作。插件不会自行跳转或发起支付。若宿主使用 custom 插槽绘制自己的遮罩，请设置 trialMask.show=false，避免内置遮罩覆盖自定义内容。

使用限制

试看用于前端播放体验控制，不替代服务端鉴权或付费访问控制。购买页面、支付和购买结果校验由宿主小程序实现，不应仅凭前端点击事件解除观看限制。

常见问题

Q：设置了 trialDuration，为什么仍能播放完整视频？

A：需要同时设置 trialEnabled 为 true，并将 trialDuration 设置为有限正数。如果视频总时长不超过试看时长，视频按原有规则正常播放结束。

Q：如何重新试看或在购买后继续播放？

A：重新试看时依次调用 seek(0) 和 play()。业务服务端确认购买成功后，将 trialEnabled 设置为 false，再调用 play() 继续播放。关闭试看本身不会自动恢复播放。

Q：隐藏试看遮罩是否会取消试看限制？

A：不会。trialMask.show 只控制内置遮罩是否显示；取消试看需将 trialEnabled 设置为 false。

Q：鸿蒙手机开启试看后为什么没有小窗？

A：鸿蒙手机开启有效试看时会禁用路由小窗，包括试看结束后，避免小窗中无法正常执行试看暂停。关闭试看后恢复传入的小窗配置，Android 和 iOS 的小窗配置不变。