WeChat Mini Program VOD Plugin Trial Play

Applicable version: v1.19.1 and above.

Feature Description

Configure trialEnabled=true and trialDuration=60 to enable a 60-second preview of the main content. The preview is based on the video timeline, not cumulative actual watch time. Playback at increased speed still ends at the 60-second mark; pausing does not consume preview time. Both regular and encrypted videos use the same frontend restrictions.

When the preview boundary is reached, playback pauses and triggers trialEnded once, with event.detail set to { vid, currentTime, trialDuration }, where currentTime is the preview boundary. The full playback end ended event or post-credits scene is not triggered. The business side can display purchase guidance in this event; full-screen guidance can use the custom slot.

<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, public seek(), control bar dragging, and horizontal screen swiping are all restricted by the preview boundary. If WeChat native controls exceed the boundary, playback pauses and position is corrected on the next progress callback.
• During preview, local resume progress is neither read nor written, and remote resume positioning is not initiated. The video's original total duration and progress bar display remain unchanged.
• After preview ends, directly playing, switching quality, or switching audio/video mode does not remove the restriction. Calling seek(0) followed by play() can restart the preview, or you can seek to another position within the preview range and play; reaching the boundary again triggers the event again. In native control mode, use the public seek() API to reset the preview.
• Switching videos resets the preview end state. Dynamically modifying the toggle or duration immediately re-evaluates the boundary; after disabling preview, call play() to continue playback.
• If the preview duration is shorter than the video duration, loop playback is disabled; if it is greater than or equal to the video duration, playback ends normally, plays post-credits, or loops according to the original logic.
• On HarmonyOS phones, when an effective preview is enabled (trialEnabled is true and trialDuration is a finite positive number), route picture-in-picture is disabled, including after preview ends; after disabling preview, the original pictureInPictureMode setting is restored. Android and iOS picture-in-picture configurations remain unchanged.
• This feature is for frontend experience control. The stopping timing is affected by WeChat's progress callback frequency and does not provide server-side paid access control. Background audio and picture-in-picture need to be verified for callback and pause behavior on target devices.

Integration Properties

Preview End Overlay

After preview ends, a semi-transparent black overlay covers the entire player by default, with "Preview ended" centered. It auto-hides after restarting preview, switching videos, or disabling preview. The overlay is inside the video element and enters fullscreen with the player; it intercepts clicks and drags on the video area. The custom control bar is above the overlay and supports operations like fullscreen exit.

External mini-programs can customize via the trialMask object; unspecified fields use default values:

<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 is used to receive the "time-up end" notification; trialAction is used to receive user clicks on purchase guidance. The plugin does not navigate or initiate payments on its own. If the host uses the custom slot to draw its own overlay, set trialMask.show=false to prevent the built-in overlay from covering custom content.

Usage Restrictions

Preview is for frontend playback experience control and does not replace server-side authentication or paid access control. Purchase pages, payments, and purchase result verification are implemented by the host mini-program; viewing restrictions should not be removed based solely on frontend click events.

Frequently Asked Questions

Q: After setting trialDuration, why can I still play the full video?

A: You need to set trialEnabled to true and trialDuration to a finite positive number. If the total video duration does not exceed the preview duration, the video plays to the end according to the original rules.

Q: How to restart preview or continue playback after purchase?

A: To restart preview, call seek(0) followed by play(). After the business server confirms a successful purchase, set trialEnabled to false, then call play() to continue playback. Disabling preview alone does not automatically resume playback.

Q: Does hiding the preview overlay cancel the preview restriction?

A: No. trialMask.show only controls whether the built-in overlay is displayed; to cancel preview, set trialEnabled to false.

Q: Why is there no picture-in-picture on HarmonyOS phones when preview is enabled?

A: On HarmonyOS phones, when an effective preview is enabled, route picture-in-picture is disabled, including after preview ends, to prevent preview pause from not working correctly in picture-in-picture mode. After disabling preview, the original picture-in-picture configuration is restored; Android and iOS picture-in-picture configurations remain unchanged.