音视频前端【免费下载链接】xgplayerA HTML5 video player with a parser that saves traffic项目地址https://gitcode.com/gh_mirrors/xg/xgplayer点击查看免费下载xgplayer-ads 是 xgplayer 官方提供的广告插件它的核心价值是让播放器以最小成本快速接入标准广告能力插件内置了 Google IMA SDK 的加载与管理逻辑并为符合 VAST、VMAP、VPAID、SIMID 等 IAB 标准的广告提供完整的播放、状态同步与事件回调。读完本文你将掌握ad配置块的完整语义adType、ima、controls及 IMA 六项子配置、广告事件监听方式、SDK 自动加载与自动播放策略以及广告 UI 与主播放器 UI 完全解耦的设计原理能够直接在真实项目中完成从 0 到 1 的贴片广告接入。一、插件定位为 xgplayer 补齐标准广告接入能力在播放器业务中广告接入往往意味着要分别对接多家广告 SDK、适配多种广告协议。xgplayer-ads 的目标就是把这部分复杂度收敛到一个插件里。根据官方 README 的说明该插件集成了Google IMA与Google DAI后者标注为待开发对外提供符合 VAST、VMAP、VPAID 等标准的广告接入方式开发者不需要关心广告请求、渲染、进度上报等底层细节。从源码结构看插件的能力边界非常清晰见 packages/xgplayer-ads/srcplugin.jsAdsPlugin插件入口与对外 API注册名为adstatic get pluginName () { return ad }对外暴露play、pause、requestAds、playAds、skip、reset、updateConfig等方法和paused、currentTime、duration等只读状态imaAdManager.jsImaAdManagerGoogle IMA SDK 的具体对接层负责 SDK 加载、AdsLoader/AdsManager 初始化、广告事件转发baseAdManager.jsBaseAdManager广告管理器的公共基类维护广告播放上下文与内容播放阻塞标志ui/adUIManager.jsAdUIManager广告 UI 管理器负责广告播控 UI 的装饰与替换events.js全部广告事件常量定义。插件当前版本为 3.0.26见 package.json依赖can-autoplay、eventemitter3与xgplayer-streaming-shared与xgplayer3.0.26 互为 peerDependency。二、快速接入最小可运行示例在xgplayer播放器中接入广告插件只需三步引入插件、注册到plugins、在ad配置块中填写广告参数。README 给出的最小示例import Player from xgplayer import AdPlugin, { ADEvents } from xgplayer-ads import xgplayer/dist/xgplayer.min.css const player new Player({ id, url, autoplay: true, plugins: [AdPlugin], ad: { adType: ima, ima: { locale: zh_cn, adsRequest: createAdsRequest() } } })对这段代码做几点拆解插件注册将AdPlugin放入plugins数组后播放器初始化时会在beforePlayerInit阶段创建AdUIManager并根据adType进入对应的广告管理器初始化分支见 plugin.js。该阶段返回一个initPromise播放器初始化会等待广告管理器准备就绪IMA_READY_TO_PLAY事件触发时 resolve。ad配置块这是插件读取配置的唯一入口adType指定广告 SDK 类型ima是 IMA 专属配置。注意插件实际接受的adType有两种写法ima与google-ima都会被识别并走客户端广告初始化分支见 plugin.js。createAdsRequest()示例中它是一个返回google.ima.AdsRequest实例的工厂函数开发者也可改用更简单的adTagUrl字符串详见下文配置表。此外插件还提供 UMD 构建见 index.umd.js全局变量名为AdPluginUMD 类额外挂载了静态属性AdEvents适合不使用打包器的场景。三、配置项详解Ad Config 与 IMA Config3.1 Ad Config顶层广告配置配置字段类型默认值含义adTypegoogle-ima|google-dai|aws-media-tailer-广告 SDK 类型目前仅支持google-imaimaobjectIMA Config为客户端实现方案 IMA 提供的配置controlsbooleantrue是否需要在广告期间展示播控 UI三个字段的职责边界很明确adType是路由开关。从 plugin.js 的_initClientSideAd可以看出ima与google-ima目前都映射到_initImaAd()google-dai、aws-media-tailer处于待开发状态传入时不会初始化任何广告管理器ima是 IMA 广告管理器的全部配置来源ImaAdManager构造时直接取this.config.ima见 plugin.jscontrols决定广告播放期间是否展示播放控制条。AdUIManager在showAdUI时若检测到config.controls false会将控制条整块移入 DocumentFragment 暂存广告结束再原位恢复见 adUIManager.js 与hideControls/showControls的实现。3.2 IMA ConfigIMA 专属配置配置字段类型默认值含义debugbooleanfalse在插件加载前开发者可自行引入 IMA SDK若插件检测到没有google.ima对象会自动加载 IMA SDK此开关为true时加载 debug 版本 SDKloadSdkTimeoutnumber3000由 ImaAdManager 内部加载 IMA SDK 时的加载超时时间单位毫秒localestring-IMA 界面与文案的本地化语言如zh_cnadsRequestobject-google.ima.AdsRequest实例或等价对象可携带广告标签、尺寸、跳过策略等完整请求参数adsResponsenull | string | non-null Document-用作广告响应的 VAST 2.0 文档内容字符串或 DOM直接作为响应而非请求广告服务器当adsRequest被设置时此参数不生效adTagUrlstring-广告服务器请求地址VAST 标签 URL当adsRequest|adsResponse被设置时此参数不生效3.3 三种广告请求方式的优先级与底层实现adsRequest、adsResponse、adTagUrl三种方式互斥其优先级在源码中有明确体现。ImaAdManager.requestAds()见 imaAdManager.js的实现逻辑为if (adTagUrl) { adsRequest.adTagUrl adTagUrl } else if (adsResponse) { adsRequest.adsResponse adsResponse } else if (providedAdsRequest typeof providedAdsRequest object) { Object.keys(providedAdsRequest).forEach(key { adsRequest[key] providedAdsRequest[key] }) }也就是说adTagUrl优先级最高其次是adsResponse直接使用本地 VAST 文档常见于测试场景可完全离线验证广告流程最后才是adsRequest对象。当使用adsRequest时插件会将其属性逐项拷贝到新建的google.ima.AdsRequest实例上因此你也可以传入 IMA SDK 支持的任意扩展字段。值得注意的细节无论使用哪种方式插件都会主动填充广告位尺寸与自动播放意图——linearAdSlotWidth/Height、nonLinearAdSlotWidth/Height取自播放器player.sizeInfo并通过setAdWillAutoPlay(autoplayAllowed)、setAdWillPlayMuted(autoplayRequiresMuted)告知 SDK 广告的启播环境见 imaAdManager.js这两个标志来自后文要讲的自动播放检测结果。四、事件系统广告生命周期完全可观测广告事件独立于普通视频播放事件统一通过播放器或插件实例的on方法监听。player.on(ad_play, (){ // do something })4.1 常用广告事件事件名含义ad_play当广告启播时发布含广告从暂停中恢复播放的场景ad_pause当广告暂停时发布ad_time_update当广告类型为线性贴片时广告当前时间发生变更时触发ad_complete当线性广告单个完成时发布ad_all_completed当所有广告广告串 pod 全部完成时发布4.2 完整事件常量README 列出了上述 5 个常用事件实际上插件内部还定义了更细粒度的事件常量全部集中在 events.js接入时建议直接引用常量而非手写字符串通用广告事件AD_START(ad_start)、AD_PLAY(ad_play)、AD_PAUSE(ad_pause)、AD_TIME_UPDATE(ad_time_update)、AD_SKIPPED(ad_skipped)、AD_ERROR(ad_error)、AD_COMPLETE(ad_complete)、AD_ALL_COMPLETED(ad_all_completed)。IMA 专属事件前缀ima_IMA_SDK_LOAD_START、IMA_SDK_LOAD_SUCCESS、IMA_SDK_LOAD_ERROR、IMA_AD_LOADER_READY、IMA_AD_MANAGER_READY、IMA_AD_ENDED、IMA_AD_SKIPPED、IMA_AD_COMPLETE、IMA_ALL_ADS_COMPLETED、IMA_AD_ERROR、IMA_AD_SEEKING、IMA_AD_SEEKED、IMA_AD_LOADED、IMA_AD_BREAK_READY、IMA_CONTENT_PAUSE_REQUESTED、IMA_CONTENT_RESUME_REQUESTED、IMA_READY_TO_PLAY。其中IMA_READY_TO_PLAY是插件初始化完成的关键信号播放器初始化流程会等待它来 resolveinitPromise见 plugin.jsIMA_AD_LOADED事件携带{ ad, isPreroll }可用于区分前贴片podIndex 0与其他广告位。4.3 事件监听与广告状态读取README 提供了两种等价监听方式既可挂在播放器上也可挂在广告插件实例上import Events from xgplayer import AdPlugin, { ADEvents } from xgplayer-ads player.on([ADEvents.AD_PLAY, ADEvents.AD_PAUSE], () { // do something }) // or const adPlugin player.getPlugin(AdPlugin.pluginName) adPlugin.on([ADEvents.AD_PLAY, ADEvents.AD_PAUSE], () { // do something })监听回调中可读取三个广告状态属性均为ImaAdManager同步到插件上的只读 getter见 plugin.jsadPlugin.paused广告是否处于暂停态其判定为isLinearAdRunning paused即仅在线性广告正在播放中才反映广告的暂停状态adPlugin.currentTime广告当前播放时间点秒由AD_PROGRESS事件持续更新adPlugin.duration广告总时长秒同样来自AD_PROGRESS事件携带的AdProgressData见 imaAdManager.js。4.4 广告控制方法const adPlugin player.getPlugin(AdPlugin.pluginName) adPlugin.play() adPlugin.pause()play()与pause()直接透传给底层adsManager.resume()/adsManager.pause()见 imaAdManager.js。此外插件还公开了requestAds()重新发起广告请求、playAds()手动启播广告、skip()当AdsManager.getAdSkippableState()为 true 时跳过当前广告、reset()销毁 adsManager 并复位状态与updateConfig()运行时热更新配置。五、Google IMA 集成细节SDK 加载、隐私合规、本地化与 VPAID5.1 SDK 自动加载与降级策略README 明确说明内置默认会自动下载 IMA SDK同时提供开关让开发者自行引入。这里的开关就是ima.debug与loadSdkTimeout。ImaAdManager._loadIMASdk()见 imaAdManager.js的实现逻辑是若全局已存在google.ima对象说明开发者已自行引入直接 resolve不再重复加载否则动态创建script标签src为https://imasdk.googleapis.com/js/sdkloader/ima3.jsdebug: true时加载ima3_debug.js调试版本以loadSdkTimeout || 3000毫秒为超时阈值超时或脚本加载失败则 reject。SDK 加载过程会依次发布IMA_SDK_LOAD_START、IMA_SDK_LOAD_SUCCESS事件一旦加载失败插件会发布IMA_SDK_LOAD_ERROR并立即将shouldBlockVideoContent置为false见 imaAdManager.js——这意味着广告 SDK 不可用时不会阻塞正片播放属于优雅降级广告播不了正片照常放。5.2 数据隐私合规CCPA由于插件默认会从 Google 域名动态加载 IMA SDKREADME 特别提示使用本插件时必须遵守 IMA SDK 的数据隐私要求CCPA。这属于接入方的合规义务——一旦决定使用自动加载能力请在业务侧评估并落实对应的隐私声明与用户选择机制如果希望完全掌控 SDK 的引入时机与合规流程可以通过前置引入google.ima的方式让插件跳过自动加载对应debug配置的说明自行承担 SDK 下载。5.3 Locale 本地化广告 UI 的文案与语言环境通过 IMA 的settings.setLocale()控制。插件在_initConfig()中读取ima.locale并调用该方法见 imaAdManager.js也可在业务代码中直接调用google.ima.settings.setLocale(zh-CN);5.4 VPAID 支持对于需要复杂交互、可测量性的 VPAID 广告可通过 IMA 设置开启 VPAID 模式google.ima.settings.setVpaidMode(google.ima.ImaSdkSettings.VpaidMode.ENABLED);VpaidMode支持DISABLED关闭、ENABLED开启、INSECURE允许不安全协议等取值具体行为以 IMA SDK 文档为准。六、广告 UI 设计原则与主播放器完全解耦6.1 三条设计要点README 对广告 UI 提出了明确的设计约束这也是本插件架构上最值得借鉴的部分AD UI 完全独立于 xgplayer广告播控 UI 不直接修改主播放器源码而是通过继承内置 UI 插件的功能独立实现并复写需要修改的状态/事件内置 AdUIManager 统一管理由AdUIManager监听广告播放状态响应广告 UI 的展示与隐藏主播放器 UI 只提供可复写能力xgplayer 的 UI 插件为广告场景做了微调但内部不对广告状态做特殊编码只暴露可继承、可覆写的能力。这样设计的收益在于未集成广告插件时对主包体积的影响被降到最低集成时又不必侵入播放器核心代码。6.2 AdUIManager 的装饰器替换机制AdUIManager见 adUIManager.js维护了一张装饰对照表把主播放器的内置 UI 插件映射为广告专用版本主播放器插件广告装饰插件说明PlayIcon播放按钮AdPlayIconadPlay监听AD_PAUSE/AD_PLAY切换动画点击时调用adPlugin.play()/pause()TimeIcon时间显示AdTimeIconadTime展示广告的currentTime/durationProgress进度条AdProgressadProgress展示广告进度且强制关闭拖拽 seek见后文VolumeIcon音量null广告期间不展示CssFullscreenIcon / FullscreenIcon全屏null广告期间不展示这些装饰插件adPlay、adTime、adProgress分别见 adPlay.js、adTime.js、adProgress.js通过覆写父类的duration、currentTimegetter 和listenEvents实现数据源切换——同一套 UI 逻辑数据源从正片切换到广告。例如AdProgress.afterCreate会强制写入isCloseClickSeek: true、isDraggingSeek: true、closeMoveSeek: true从配置层面杜绝用户在广告期间拖动进度条。showAdUI/hideAdUI的核心技巧是DocumentFragment 占位替换广告播放时把正片 UI 插件节点整体移入 fragment用广告装饰插件顶替其 DOM 位置广告结束后再逆操作还原见 adUIManager.js。之所以不用简单的 CSS 隐藏是因为那会导致插件 DOM 顺序错乱、影响样式选择器命中。同时通过播放器根节点的状态类xgplayer-ad-start、xgplayer-ad-show-ui见 adStateClass.js驱动容器显隐start插件在广告期间被单独隐藏以避免与广告播控冲突。6.3 广告状态、事件、方法的实现汇总状态adPlugin.paused、adPlugin.currentTime、adPlugin.duration见 4.3 节。事件通过player.on([ADEvents.AD_PLAY, ADEvents.AD_PAUSE], ...)或adPlugin.on(...)监听见 4.3 节示例。方法adPlugin.play()、adPlugin.pause()以及requestAds()、playAds()、skip()等见 4.4 节。七、广告生命周期与自动播放策略源码级原理理解广告请求到播放的完整时序有助于排查广告不播/正片被卡类问题。把 plugin.js 与 imaAdManager.js 串起来典型生命周期如下初始化beforePlayerInit创建AdUIManager与ImaAdManagerImaAdManager.init()依次完成 SDK 加载、locale 配置、媒体事件挂载、AdDisplayContainer与AdsLoader创建、广告请求初始化请求广告若配置了adTagUrl/adsResponse/adsRequest三者之一先执行自动播放检测_checkAutoplaySupport()再调用requestAds()检测结果通过setAdWillAutoPlay/setAdWillPlayMuted传给 SDK等待广告就绪AdsLoader加载完成触发ADS_MANAGER_LOADED_onAdsManagerLoaded创建AdsManager并挂载全部广告事件监听包括LOADED、STARTED、PAUSED、RESUMED、COMPLETE、ALL_ADS_COMPLETED、CONTENT_PAUSE_REQUESTED、CONTENT_RESUME_REQUESTED、SKIPPED、AD_PROGRESS、FIRST_QUARTILE、MIDPOINT、THIRD_QUARTILE、CLICK等 20 余种见 imaAdManager.js随后发布IMA_AD_MANAGER_READY启播广告若自动播放被允许autoplayAllowed立即playAds()内部执行displayContainer.initialize()、adsManager.init(w, h, viewMode)、adsManager.start()若不允许则通过player.useHooks(play, cb)挂载钩子等用户手动触发正片播放时再启播广告并最终发布IMA_READY_TO_PLAY放行播放器初始化广告播放与事件转发onAdEvent把 IMA 事件翻译为插件级事件——STARTED/RESUMED→AD_START/AD_PLAYPAUSED→AD_PAUSEAD_PROGRESS→ 同步currentTime/duration并触发AD_TIME_UPDATECOMPLETE→AD_COMPLETE携带hasNextInPod表示广告串内是否还有下一条ALL_ADS_COMPLETED→AD_ALL_COMPLETED内容暂停/恢复CONTENT_PAUSE_REQUESTED时置isLinearAdRunning true并暂停正片、给播放器根节点添加xgplayer-ads-playing类CONTENT_RESUME_REQUESTED时复位标志并恢复正片播放见 imaAdManager.js 与_resumeContent错误处理_handleAdError会销毁 adsManager、解除内容阻塞、发布IMA_AD_ERROR/AD_ERROR并尝试恢复正片保证广告故障不影响主内容。7.1 自动播放检测的兜底策略_checkAutoplaySupport()见 imaAdManager.js使用can-autoplay库检测当前环境的自动播放能力考虑 Safari 等平台自动启播耗时较长将检测超时兜底值设为 800ms对 Tizen、WebOS 等已知支持自动播放的 TV 平台直接跳过检测。检测结果有三种组合——autoplayAllowed可自动播放、autoplayRequiresMuted仅可静音自动播放广告以静音方式启播、两者皆否等待用户手势。7.2 内容播放阻塞机制广告准备与播放期间正片不应抢占播放。AdsPlugin._blockContentPlay()监听播放器的play事件一旦shouldBlockVideoContent为真就立即player.pause()阻止正片启播见 plugin.js。该标志在 baseAdManager.js 中定义为isLinearAdRunning || _shouldBlockVideoContent覆盖广告准备期 线性广告播放期两个阶段同时针对 Tizen/WebOS 这类广告与正片共用 video 元素的 TV 环境该 getter 会直接返回false避免误阻塞。八、总结与延伸阅读xgplayer-ads 用一个插件完成了广告接入的最后一公里配置上adTypeimacontrols三个维度覆盖了 SDK 选择、请求参数与 UI 策略能力上广告事件与正片事件完全隔离UI 通过装饰器替换机制与主播放器解耦健壮性上SDK 加载失败、广告错误、自动播放受限均有兜底路径正片播放不受广告故障牵连。如需进一步深入建议按以下路径阅读仓库源码插件入口与生命周期packages/xgplayer-ads/src/plugin.jsIMA 对接与事件翻译packages/xgplayer-ads/src/imaAdManager.js广告管理器公共基类packages/xgplayer-ads/src/baseAdManager.jsUI 装饰替换机制packages/xgplayer-ads/src/ui/adUIManager.js事件常量全集packages/xgplayer-ads/src/events.js广告装饰插件示例adPlay.js、adProgress.js、adTime.js赞分享音视频前端【免费下载链接】xgplayerA HTML5 video player with a parser that saves traffic项目地址https://gitcode.com/gh_mirrors/xg/xgplayer点击查看免费下载相关推荐ExoPlayer IMA 扩展模块指南基于 Interactive Media Ads SDK 的广告插入实战ExoPlayer IMA 扩展模块指南基于 Interactive Media Ads SDK 的广告插入实战 导读 本文介绍 ExoPlayer 仓库中的音视频移动开发interactive_media_ads 接入实战在 Flutter 中集成 IMA SDK 播放 VAST 视频广告interactive_media_ads 接入实战在 Flutter 中集成 IMA SDK 播放 VAST 视频广告 interactive_media_跨平台移动开发UI组件开发工具ExoPlayer IMA 模块接入指南基于 IMA SDK 的客户端与服务端广告插入ExoPlayer IMA 模块接入指南基于 IMA SDK 的客户端与服务端广告插入 本文以 ExoPlayer 仓库中的 extensions/ima 模音视频移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考