播放器试看

我的收藏

效果展示

效果	描述
	功能概述：官方播放器新增支持「待解锁剧集试看」能力，即支持开发者针对付费剧集/需看广告剧集可配置x秒的试看时间，试看结束后再拉起充值面板/广告组件，利用试看时长提升用户的解锁意愿。若试看结束，平台提供通知，开发者接收通知后需要自行设置拉起广告组件或充值面板功能说明：详见「setUnlockPreview - 设置试看」，接口文档已更新 a.适用范围：IAP+IAA的付费集/需看广告剧集（非此类集不生效） b.试看秒数：支持开发者自定义针对付费集/需看广告剧集，按集维度设置试看秒数（最小值为0则无试看，最大值如超出本集剧目时长则以试看样式持续展示至整集） c.若试看结束，平台提供通知，开发者接收通知后需要自行设置拉起广告组件或充值面板 d.左侧 button：文案默认「下次再说」，支持配置，操作可自定义，用户点击则触发点击事件回调，开发者可自行拉起付费或者广告 e.文案设置： i.底部“试看4秒”：官方文案，根据当前设置的试看秒数自动进行展示； ii.底部文案（非button按钮）：文案支持开发者自定义（5<字数<26），description控制，如不传入或不符合字数要求，兜底文案“恭喜获得免费看剧福利，解锁后可继续观看” iii.右侧button文案：文案支持开发者自定义（4<字数<10），如不传入或不符合字数要求，兜底文案“X秒后试看结束”，倒计时结束触发试看结束，点击时触发事件回调； iv.左侧button文案：文案支持开发者自定义（4<字数<10），如不传入或不符合字数要求，兜底文案“下次再说”，点击时触发事件回调上线时间：2024年11月26日

代码实现

设置试看setUnlockPreview

每次调用都是全量覆盖

调用前使用canIUse判断是否可用
tt.canIUse('playlet-plugin.setUnlockPreview') {}

语法

pm.setUnlockPreview({
  albumId: 'xxxx',
  second: 5,
  description: "获得免费试看福利",
  buttons: [{
    id: 'leftBtnId', // id是自定义的，可以根据业务场景命名
    text: '解锁更多权益',
  }, {
    id: 'rightBtnId', // id是自定义的，可以根据业务场景命名
    text: '{x}秒后 试看结束', // {x} 内部会替换为倒计时
  }],
  episodeConfig: [{
    seq: 16,
    second: 4,
  }, {
    seq: 17,
    second: 6,
  }]
})

参数说明

属性名	类型	默认值	必填	说明
albumId	string	无	否	试看生效的剧ID；非必填，不填则默认进入播放器页面后，所有的剧都按配置生效，否则按配置的剧生效
second	number	无	否，second和episodeConfig必填其一	设置所有付费集的试看时长。需要大于0，否则不生效
description	string	“恭喜获得免费看剧福利，解锁后可继续观看”		顶部描述文案。字符长度5～26（包含标点符号、空格），超出则不生效，使用平台默认文案
buttons	试看按钮区配置	无	Array<ButtonConfig>	从左到右的顺序配置按钮，需要传两项
episodeConfig	Array<EpisodeConfigList>	无	否，second和episodeConfig必填其一	配置剧集维度的试看时长，不填或没有配置的剧集则按seconds配置的时长

ButtonConfig

字段	类型	含义	必填	说明
id	string	按钮	是	按钮唯一标识点击事件回调的triggerButtonId来源此配置
text	string	按钮文案	否	按钮文案右侧倒计时按钮，可配置 {x}秒后试看结束，使用‘{x}’平台会处理成倒计时效果，无需开发者处理。倒计时{x}秒仅支持右侧按钮；字符长度4～10（包含标点符号、空格），超出则不生效，会使用平台默认文案

EpisodeConfigList

属性名	类型	默认值	必填	描述
seq	number	无	是	设置试看的集
second	number	无	是	设置试看时长。单位秒需要大于等于0，否则不生效，等于0可用于覆盖配置的全局试看时长，场景：希望全局试看5s，但某n集希望不试看

设置按钮setUnlockPreviewButton

要在setUnlockPreview之后调用，否则buttons不存在id无法匹配，会触发 id not found的错误

语法

pm.setUnlockPreviewButton(id, config)

参数说明

属性名	类型	默认值	必填	描述
id	string	无	是	要配置的按钮id setUnlockPreview的buttons里配置的id
config	PreviewButtonConfig	无	是	配置的按钮内容

PreviewButtonConfig

属性名	类型	默认值	必填	描述
text	string	无	是	按钮文案倒计时按钮仅会在倒计时结束后生效字符长度4～10（包含标点符号、空格），超出则不生效

试看结束回调onPreviewEnd

倒计时结束，即试看结束回调

调用前使用canIUse判断是否可用
tt.canIUse('playlet-plugin.onPreviewEnd') {}

语法

pm.onPreviewEnd(() => {
  // 试看结束，需要处理付费/广告解锁
})

按钮点击事件onUnlockPreviewButtonClick

如果没有正确设置id，则会影响回调

参数说明

属性名	类型	默认值	必填	描述
triggerButtonId	string	无	是	触发点击事件的按钮id

配置异常onError

当配置有异常时，触发开发者error

不影响功能，但配置不会生效，需要关注。但如果second和episodeConfig配置都不对，则会没有试看。

errNo	errMsg
9	buttons需要是一个Array，且长度为2
	buttons里每一项的id不能为空影响试看功能
	second需要输入大于0的数字, 当前为${second}
	description应该在5-26个字符之间，当前为${description}

推荐用法

可在onReady生命周期调用，设置剧集试看

调用不得早于onReady生命周期。

onReady() {

  // 判断API是否可用，onUnlockPreviewButtonClick支持时，所有API均可使用
  if (tt.canIUse('playlet-plugin.onUnlockPreviewButtonClick')) {
    pm.setUnlockPreview({
      second: 5,
      description: "恭喜获得获得免费试看福利",
      buttons: [{
        id: 'leftBtn',
        text: '立即解锁',
      }, {
        id: 'rightBtn',
        text: '{x}秒后 自动拉起广告',
      }]
    })
  }
  
  // 设置右侧试看倒计时按钮，倒计时结束后的文案，注意text不能超过10个字
  pm.setUnlockPreviewButton('rightBtn', {
    text: '免费解锁'
  })
  
  // 按钮点击
  pm.onUnlockPreviewButtonClick((data) => {
    const { triggerButtonId, seq, albumId } = data;
    if (triggerButtonId === 'rightBtn') {
      // 点击了buttons id='rightBtn'的按钮
    }
    
    if (triggerButtonId === 'leftBtn') {
     //  点击了buttons id='leftBtn'的按钮
    }
  })
  
  // 试看倒计时结束
  pm.onPreviewEnd((data) => {
    const { albumId, seq } = data;
  })
}

其他小场景

设置所有解锁剧集支持10s试看

if (tt.canIUse('playlet-plugin.setUnlockPreview')) {
    pm.setUnlockPreview({
      second: 10
    })
}

设置所有剧支持试看10s，但第10集试看5s

if (tt.canIUse('playlet-plugin.setUnlockPreview')) {
    pm.setUnlockPreview({
      second: 10,
      episodeConfig: [{
        seq: 10,
        second: 5,
      }]
    })
}

设置所有剧支持试看10s，但第10集不支持试看

if (tt.canIUse('playlet-plugin.setUnlockPreview')) {
    pm.setUnlockPreview({
      second: 10,
      episodeConfig: [{
        seq: 10,
        second: 0,
      }]
    })
}

试看结束拉起支付/广告

if (tt.canIUse('playlet-plugin.onPreviewChange')) {
  pm.onPreviewEnd(() => {
    // 拉起支付/跳转广告
  })
}

注意：
每次点击按钮都会触发onUnlockPreviewButtonClick回调，所以用户支付成功后，应及时设置为解锁成功，或解锁成功后该集的试看结束回调不再处理，避免重复解锁引发反馈。

FAQs

试看倒计时结束前，不会暂停，除非进入广告之后，页面onHide会触发暂停，倒计时也会暂停。所以用户主动点击按钮触发OnUnlockPreviewButton，开发者拉起广告或支付，在拉起广告中、广告观看完成时、拉起支付、支付完成时，如果触发了onPreviewEnd倒计时结束，需要做好处理，避免多次拉起广告或支付

其他问题，大家可直接评论文档，互相交流