VAST 广告

English

通过 Glomex VAST IMA Player 和 Google IMA SDK 请求并展示广告。与 Ads 插件的本地倒计时广告不同，这里使用广告标签地址或 VAST 响应。SDK 脚本和广告资源需要可访问，网络、VPN 或广告拦截规则可能阻止加载。本页描述未发布重构分支，线上示例不是当前候选的验收证据。

安装和示例

yarn add artplayer artplayer-plugin-vast

import Artplayer from 'artplayer';
import artplayerPluginVast from 'artplayer-plugin-vast';

使用 script 时先加载 ArtPlayer，再加载 dist/artplayer-plugin-vast.js，全局名为 artplayerPluginVast。插件通过其 Glomex 依赖加载 IMA，无需另造加载器。以下保留原在线示例；其中的外部广告地址并非本地测试夹具。

▶ Run Code

// Depends on:
// https://glomex.github.io/vast-ima-player/
// https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side

// Google's IMA SDK are blocked by your Ad blocker.
// Please Turn Off Your Ad Blocker.

// npm i artplayer-plugin-vast
// import artplayerPluginVast from 'artplayer-plugin-vast';

var art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  fullscreen: true,
  fullscreenWeb: true,
  plugins: [
    artplayerPluginVast(({ playUrl, imaPlayer, ima }) => {
      // Play the ad when the video is played
      art.once('play', () => {
        playUrl('https://artplayer.org/assets/vast/linear-ad.xml')
      })
    }),
  ],
})

初始化兼容模式

工厂形状为 artplayerPluginVast(callback?, options?)，返回异步注册函数。加载 SDK、创建相应上下文并 await 用户回调后，注册才完成。回调可返回 Promise，但注册完成不等于广告已请求或播放。

行为	默认 npm 模式	`{ compatibility: 'workspace-1.2' }`
回调开始时	已创建 IMA player 和容器	尚未创建，等 init/playUrl/playRes
IMA 设置	保留 SDK 自身默认值	预加载和广告结束后恢复自定义播放状态默认为 true
资源字段	imaPlayer/id/$container 是可写数据字段	三者是实时只读 getter，初始化前或释放后为 null
请求	包装层转发每次显式请求	活动广告期间抑制新的请求
容器	由 SDK 管理广告显隐，保留默认样式	黑色覆盖层，四个广告事件控制显隐和活动状态

这是已批准的兼容选择：已发布 npm 1.0.0 用户保留默认行为，依赖未发布工作区 1.2 惰性初始化的代码必须显式选择工作区模式。模式在工厂调用时读取一次；未知值立即抛出 TypeError，不会启动 SDK 加载。

回调上下文

字段	实际用途
`art`	当前播放器实例
`ima`	已加载的 IMA SDK
`adsRenderingSettings`	传给新 SDK player 的 IMA AdsRenderingSettings 对象
`playerOptions`	传给新 SDK player 的 Glomex PlayerOptions 对象
`imaPlayer`	SDK player，默认模式已创建；工作区模式可为 null
`id` / `$container`	该模式的容器 ID/元素，空值和快照规则见上表
`container`	两种模式均为当前容器的只读 getter；未创建或释放后为 null
`init()`	取得或创建当前 SDK player，终止后返回 null
`playUrl(url, config?)`	创建 AdsRequest，设置 adTagUrl 并请求广告；同步返回 void
`playRes(response, config?)`	创建 AdsRequest，设置 adsResponse 并请求广告；同步返回 void

config 是附加请求字段；沿用历史 for-in 复制行为，包括可枚举的继承字段，且复制发生在主字段之后，因此可以覆盖 adTagUrl/adsResponse。请传入应用明确控制的配置。请求构造或 SDK 同步错误可直接抛出，void 返回不表示广告成功，也不是播放完成 Promise。

要在 SDK player 创建前配置选项，使用工作区模式并先修改原 settings/options 对象，再调用 init 或请求方法。默认模式的首个 player 在回调之前已经创建；不要假设回调内修改选项能追溯改变构造行为。

默认模式释放后，imaPlayer/id/$container 仍保留上次分配的快照，但 SDK 已销毁、容器已移除；不能继续把快照当作活跃资源。显式重建会更新它们。写入这些字段不会转移插件内部资源所有权。工作区模式应保留 context 并实时读取 getter，避免解构保存初始化前的 null。

广告事件与销毁

SDK 事件通过 imaPlayer 订阅，不是同名的 ArtPlayer 事件。工作区包装层监听 AdContentPauseRequested、AdContentResumeRequested、AdStarted、AdError，改变覆盖层和活动状态；AdError 同时记录错误。默认模式不增加这些工作区监听器。正文暂停/恢复由 SDK 负责，包装层不重复实现。

结果名为 artplayerPluginVast，通过 art.plugins.artplayerPluginVast 取得，公开 destroy() 同步释放当前会话。播放器仍存活时，可再次调用回调中保留的 init/playUrl/playRes 创建新会话。重建后的 SDK 是新对象，需要重新安装应用自己的 SDK 监听器。

核心销毁使这次插件安装永久终止：SDK 加载的迟到完成不再调用回调或创建容器，init 返回 null，请求方法为空操作。它不会取消其他实例共用的 SDK 脚本加载。SDK 加载或用户回调失败会清理附件并保留原拒绝值；清理失败可能可观察，但其余资源仍会尝试释放。不要将插件 destroy 与核心 destroy 的终止语义混同。

真实广告播放还涉及可用广告响应、IMA、浏览器策略和设备。SDK 加载受阻时不能把 mock、页面导航或正文继续播放当作广告播放通过；使用目标网络和设备单独验收。

TypeScript 入口

根入口和 /legacy 保留 npm 1.0.0 的必填回调、any SDK 字段和错误的同步 name-only 返回声明，不要求旧替换函数增加 .default。实际注册一直是异步的。需要准确类型、可省略回调、第二参数或 destroy 时使用同一实现的 /runtime：

import vast from 'artplayer-plugin-vast/runtime';
import type { RuntimeResult } from 'artplayer-plugin-vast/runtime';

const installPublished = vast(({ imaPlayer }) => {
  imaPlayer.addEventListener('AdStarted', () => console.log('Ad started'));
});

const installWorkspace = vast((context) => {
  context.playerOptions.autoResize = false;
  context.init()?.addEventListener('AdStarted', () => console.log('Ad started'));
}, { compatibility: 'workspace-1.2' });

function releaseAd(result: RuntimeResult): void {
  result.destroy();
}

runtime 导出 RequestConfig、CompatibilityOptions、Context、PublishedContext、WorkspaceContext、RuntimeContext、RuntimeCallback、RuntimeResult、Registration、RuntimeFactory，及旧工作区别名 ArtplayerPluginVastOption/ArtplayerPluginVastInstance。前者是工作区回调类型，后者是 await 后的结果类型。CommonJS 无 interop 时可用 runtime 的 import = require，支持函数和 .default；这些类型不会更改旧根声明。

7.2 KiB Raw Permalink Blame History Unescape Escape