贴片广告与暂停广告

ZWPlayer 支持两种自有广告形式，均使用使用者自己的视频/图片资源，不依赖第三方广告网络：

贴片广告（bumper）：在正片播放前（pre-roll）或播放后（post-roll）插入宣传片
暂停广告（pauseAd）：用户暂停正片时在画面上叠加推广素材

1. 贴片广告（bumper）

1.1 配置示例

new ZWPlayer({
  playerElm: 'player',
  url: 'main.mp4',
  bumper: {
    preRoll: {
      url: 'https://cdn.example.com/intro.mp4',
      skipOffset: null,
      clickThrough: 'https://brand.example.com'
    },
    postRoll: {
      url: 'https://cdn.example.com/outro.mp4',
      skipOffset: 5
    }
  }
});

1.2 bumper 对象属性

属性	类型	必填	默认	说明
`preRoll`	object	否	—	片头贴片配置（正片播放前播出）
`postRoll`	object	否	—	片尾贴片配置（正片播放完后播出）

1.3 preRoll / postRoll 属性

属性	类型	必填	默认	说明
`url`	string	是	—	贴片视频 URL，支持 mp4/webm 等标准格式。协议限 http/https/blob
`skipOffset`	number\|null	否	`null`	跳过策略：`null`=强制完整播放、`0`=立即可跳、`N`=N 秒后出现跳过按钮
`clickThrough`	string	否	—	点击跳转 URL（新标签页打开），显示为"了解更多"按钮

1.4 skipOffset 三态说明

值	行为	适用场景
`null`	强制完整播放，无跳过按钮	品牌片头、法定声明
`0`	贴片出现即可点击跳过	软性推广，用户可立即跳过
`5`（数字）	5 秒后出现跳过按钮，之前显示倒计时	平衡曝光与体验

1.5 也可以写在 ZWMAP 播放列表中

{
  "zwp_protocol": "ZWMAP/1.0",
  "zwp_type": "playlist",
  "groups": [{
    "name": "正片",
    "items": [{
      "name": "第一集",
      "url": "https://cdn.example.com/ep01.mp4",
      "bumper": {
        "preRoll": { "url": "https://cdn.example.com/intro.mp4", "skipOffset": null }
      }
    }]
  }]
}

配置合并优先级：VideoItem 的 bumper 字段 > 播放器构造参数 bumper > 无配置（不播贴片）

2. 暂停广告（pauseAd）

2.1 配置示例

new ZWPlayer({
  playerElm: 'player',
  url: 'main.mp4',
  pauseAd: {
    image: {
      url: 'https://cdn.example.com/banner.jpg',
      clickThrough: 'https://promo.example.com'
    },
    video: {
      url: 'https://cdn.example.com/promo.mp4',
      muted: true,
      loop: true
    },
    prefer: 'image'
  }
});

2.2 pauseAd 对象属性

属性	类型	必填	默认	说明
`image`	object	否	—	图片素材配置（jpg/png/webp/gif）
`video`	object	否	—	视频素材配置
`prefer`	string	否	`"image"`	`"image"` 或 `"video"`，两者都配时优先展示哪个。优先素材加载失败时降级到另一个

2.3 image 属性

属性	类型	必填	说明
`url`	string	是	图片 URL（jpg/png/webp/gif）
`clickThrough`	string	否	点击跳转 URL

2.4 video 属性

属性	类型	必填	默认	说明
`url`	string	是	—	视频 URL
`muted`	boolean	否	`true`	暂停广告视频默认静音
`loop`	boolean	否	`true`	暂停期间循环播放
`clickThrough`	string	否	—	点击跳转 URL

2.5 触发规则

暂停广告仅在用户主动暂停时触发（点击暂停按钮、按空格键、调用 player.pause()）。

以下暂停场景不触发暂停广告：

页面失去焦点自动暂停
逐帧播放（stepFrame）
视频流错误导致的暂停
贴片广告播放期间

3. 事件回调

通过配置项 onbumperevent 和 onpauseadevent 可监听广告事件：

new ZWPlayer({
  // ...
  onbumperevent(type, payload) {
    // type: 'prestart' | 'preend' | 'poststart' | 'postend' | 'skip' | 'error'
  },
  onpauseadevent(type, payload) {
    // type: 'show' | 'hide' | 'click' | 'close' | 'error'
  }
});

4. 注意事项

URL 协议限制：所有 URL（贴片/暂停广告/clickThrough）仅接受 http://、https://、blob:，拒绝 javascript:/data: 等危险协议
独立播放元素：贴片广告使用独立的 <video> 元素播放，不影响主视频的 HLS/DASH 流
loop 模式：正片循环播放时，贴片只在首次播放时各播一次，后续循环不再插播
播放模式限制：贴片和暂停广告仅在 standard（标准）模式下生效，preview（悬停预览）和 music（音乐面板）模式下不生效