mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-10 21:06:15 -08:00
146 lines
7.2 KiB
Markdown
146 lines
7.2 KiB
Markdown
# 视频与 HTML 广告
|
||
|
||
[English](../en/plugin/ads.md)
|
||
|
||
在内容首次播放时展示一次前贴片广告，可以使用独立视频或 HTML。插件自带倒计时、关闭、详情、静音和全屏控件，不需要 IMA SDK；VAST 广告请求由另一个 [VAST 插件](./vast.md)处理。本页描述未发布的重构分支，在线示例与未固定版本的包不等于当前候选。
|
||
|
||
## 安装和示例
|
||
|
||
```sh
|
||
yarn add artplayer artplayer-plugin-ads
|
||
```
|
||
|
||
```js
|
||
import Artplayer from 'artplayer';
|
||
import artplayerPluginAds from 'artplayer-plugin-ads';
|
||
```
|
||
|
||
使用 script 时先加载 ArtPlayer，再加载 `dist/artplayer-plugin-ads.js`，全局名为 `artplayerPluginAds`。下面保留[原在线示例](https://artplayer.org/?libs=./uncompiled/artplayer-plugin-ads/index.js&example=ads)，其中同时配置 video/html 时使用视频。
|
||
|
||
<div className="run-code" data-libs="./uncompiled/artplayer-plugin-ads/index.js">▶ Run Code</div>
|
||
|
||
```js
|
||
// npm i artplayer-plugin-ads
|
||
// import artplayerPluginAds from 'artplayer-plugin-ads';
|
||
|
||
const art = new Artplayer({
|
||
container: '.artplayer-app',
|
||
url: '/assets/sample/video.mp4',
|
||
autoSize: true,
|
||
fullscreen: true,
|
||
fullscreenWeb: true,
|
||
plugins: [
|
||
artplayerPluginAds({
|
||
// html广告，假如是视频广告则忽略该值
|
||
html: '<img src="/assets/sample/poster.jpg">',
|
||
|
||
// 视频广告的地址
|
||
video: '/assets/sample/test1.mp4',
|
||
|
||
// 广告跳转网址，为空则不跳转
|
||
url: 'http://artplayer.org',
|
||
|
||
// 必须观看的时长，期间不能被跳过，单位为秒
|
||
// 当该值大于或等于totalDuration时，不能提前关闭广告
|
||
// 当该值等于或小于0时，则随时都可以关闭广告
|
||
playDuration: 5,
|
||
|
||
// 广告总时长，单位为秒
|
||
totalDuration: 10,
|
||
|
||
// 多语言支持
|
||
i18n: {
|
||
close: '关闭广告',
|
||
countdown: '%s秒',
|
||
detail: '查看详情',
|
||
canBeClosed: '%s秒后可关闭广告',
|
||
},
|
||
}),
|
||
],
|
||
})
|
||
|
||
// 广告被点击
|
||
art.on('artplayerPluginAds:click', (ads) => {
|
||
console.info('广告被点击', ads)
|
||
})
|
||
|
||
// 广告被跳过
|
||
art.on('artplayerPluginAds:skip', (ads) => {
|
||
console.info('广告被跳过', ads)
|
||
})
|
||
```
|
||
|
||
## 配置
|
||
|
||
配置可省略，也可传入 `{}` 使用默认值。
|
||
|
||
| 字段 | 类型 | 默认值 | 含义 |
|
||
| --- | --- | --- | --- |
|
||
| `html` | `string` | `''` | 广告 HTML，可包含图片；不会自动清理 HTML，仅使用可信内容 |
|
||
| `video` | `string` | `''` | 广告视频地址，非空时优先于 html |
|
||
| `url` | `string` | `''` | 点击广告或详情时打开的地址；为空不跳转并隐藏详情按钮 |
|
||
| `playDuration` | `number` | `5` | 关闭按钮开放前的倒计时秒数，不限制应用直接调用 skip |
|
||
| `totalDuration` | `number` | `10` | 广告倒计时总秒数，不取广告视频的实际时长 |
|
||
| `muted` | `boolean` | `false` | 广告视频初始静音状态 |
|
||
| `i18n` | `Translations` | 下表 | 整体替换默认翻译对象，四个字段必须一起提供 |
|
||
|
||
| 翻译字段 | 默认值 |
|
||
| --- | --- |
|
||
| `close` | `'关闭广告'` |
|
||
| `countdown` | `'%s秒'` |
|
||
| `detail` | `'查看详情'` |
|
||
| `canBeClosed` | `'%s秒后可关闭广告'` |
|
||
|
||
`%s` 用于时间替换。配置按浅合并处理，不支持只传一项 i18n。时长应使用数字秒，字符串不进行转换，而是被运行时校验拒绝。`source/type` 只是旧工作区声明遗留字段，不会被当作 video/html 的别名；图片通过 html 的 img 提供。
|
||
|
||
建议使用正整数时长。`playDuration <= 0` 时可立即用按钮关闭；`playDuration >= totalDuration` 时隐藏提前关闭按钮。倒计时按每次定时器执行累计一秒，页面隐藏时暂停；不是对视频 currentTime 或现实经过时间的精确计费。视频循环播放，广告结束由倒计时或 skip 决定。
|
||
|
||
## 方法和事件
|
||
|
||
插件同步注册，结果在 `art.plugins.artplayerPluginAds`，name 固定为 `artplayerPluginAds`。
|
||
|
||
| 方法 | 实际行为 |
|
||
| --- | --- |
|
||
| `pause()` | 暂停倒计时，不暂停广告视频 |
|
||
| `play()` | 恢复倒计时，不播放广告视频，也不创建重复计时链 |
|
||
| `skip()` | 结束广告一次；不受关闭按钮的 playDuration 限制 |
|
||
|
||
三个方法都同步返回 `undefined`。未初始化时 play/pause 不启动广告，skip 取消尚未显示的前贴片并发出一次 skip 事件，不创建 DOM 或主动开始内容播放。广告结束后重复 skip 无额外效果。
|
||
|
||
| 播放器事件 | 参数与时机 |
|
||
| --- | --- |
|
||
| `artplayerPluginAds:click` | 广告内容或可用详情按钮被点击，传入该次归一化配置；有 url 时先请求打开新窗口 |
|
||
| `artplayerPluginAds:skip` | 广告完成时传入同一个归一化配置；倒计时结束、手动跳过或媒体失败均可能触发，并非只表示用户点击 |
|
||
|
||
事件参数不是只读快照，监听器修改其中字段会影响后续读取，例如 totalDuration。实际打开广告详情还受浏览器窗口策略约束。
|
||
|
||
## 生命周期和媒体
|
||
|
||
在构造选项中安装插件。插件等到 ready 后的第一次 play 或 video:playing 信号才创建覆盖层并暂停正文；晚于 ready 安装不会补发已经过去的 ready。视频广告等到自己的 metadata 后启动倒计时并请求播放，HTML 广告直接开始计时。
|
||
|
||
广告视频加载或播放失败会结束广告；内部请求播放的 Promise 拒绝会记录警告。正常结束先请求恢复正文播放，再暂停广告、隐藏覆盖层并同步发出 skip。恢复请求不保证浏览器已经开始播放，应用直接调用 `art.play()` 的拒绝行为也没有改变。
|
||
|
||
结束后隐藏的广告层保留到播放器销毁。销毁释放广告视频来源、监听器、定时器和覆盖层，并清理自己创建的 `art.template.$ads`；即使保留播放器 HTML 也会清理。插件没有独立公开的 destroy、reset 或再次投放接口。样式沿用 `artplayer-plugin-ads*` 类名；全屏按钮调用核心 fullscreen。
|
||
|
||
独立广告视频需要浏览器能够加载与解码；主播放器的自定义 SDK/代理不会自动接管它。原生全屏、移动端播放策略及实际媒体效果需要目标环境验收，页面导航通过不代表这些能力已验证。
|
||
|
||
## TypeScript 兼容
|
||
|
||
根入口和 `/legacy` 接受旧声明中的 `totalDuration: string`，但运行时仍拒绝字符串。已批准的类型修正使 `Parameters<typeof ads>[0].totalDuration` 读取为 `number | string | undefined`，旧工作区 source/type 也变为可选；依赖过去推导的代码需要缩窄或迁到精确 Option。
|
||
|
||
新代码可选择相同实现的 `/runtime`：
|
||
|
||
```ts
|
||
import ads from 'artplayer-plugin-ads/runtime';
|
||
import type { Option, Result } from 'artplayer-plugin-ads';
|
||
|
||
const options: Option = { video: '/advertisement.mp4', totalDuration: 10 };
|
||
const installAds = ads(options);
|
||
|
||
function pauseCountdown(plugin: Result): void {
|
||
plugin.pause();
|
||
}
|
||
```
|
||
|
||
公开类型包括 Translations、Option、LegacyOption、WorkspaceOption、CompatOption、Result、Callable、Factory、RuntimeCallable、RuntimeFactory。LegacyOption/WorkspaceOption 用于明确表示历史声明，不新增运行时别名。CommonJS 支持函数本身和 `.default(...)`，ESM 使用默认导出；精确入口不是第二套插件实现。
|