微信小程式點播外掛試看

適用版本：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 的小視窗配置不變。