Fluid Player 实战：免费接入 VAST 广告的 HTML5 视频播放器一小时搞定

Fluid Player 实战：免费接入 VAST 广告的 HTML5 视频播放器一小时搞定

【免费下载链接】fluid-playerFluid Player - an open source VAST compliant HTML5 video player项目地址: https://gitcode.com/gh_mirrors/fl/fluid-player

广告方甩来一个 VAST 标签、要求你的视频页加上前贴片广告时，你才发现页面上那个<video>标签只是个半成品。Fluid Player 就是干这个的——免费开源的 HTML5 视频播放器，把<video>变成带完整控制栏、多清晰度切换、HLS/DASH 流媒体和 VAST 4.0 广告能力的成品播放器。

🎬 第一步：十分钟跑通最小示例

先不碰广告，让播放器转起来。下面是够用的最小结构：

<video id="player"> <source src="movie.mp4" type="video/mp4"> </video> <script src="dist/fluidplayer.min.js"></script> <script> var player = fluidPlayer('player', { layoutControls: { posterImage: 'poster.jpg' } }); </script>

这段在干嘛：fluidPlayer接收视频元素的 id（或元素本身），返回播放器实例；posterImage只是加一张封面，删掉这行照样能跑。所有能力都是往第二个参数里塞配置对象。

📺 第二步：四种播放场景各配各的

本地视频与多清晰度

同一个视频准备几个码率，写在<video>里就是：

<video id="player"> <source src="movie-1080p.mp4">var player = fluidPlayer('player', { vastOptions: { adList: [ { roll: 'preRoll', vastTag: 'https://example.com/pre.vast' }, { roll: 'midRoll', timer: '30%', vastTag: 'https://example.com/mid.vast' }, { roll: 'postRoll', vastTag: 'https://example.com/post.vast' } ], allowVPAID: true } });

preRoll片头、midRoll中插、postRoll片尾；中插必须配timer告诉播放器什么时候插（秒数或百分比都行）。allowVPAID默认是关的，要跑 VPAID 创意必须显式打开。广告加载失败时，播放器会把进度条上的广告标记（markers）和跳过按钮一起接管，广告商只负责给 VAST，交互不用你操心。

片尾推荐视频（Suggested Videos）

视频播完别让用户走，挂一个推荐列表。推荐内容由一个 JSON 配置驱动，只填一个 URL：

var player = fluidPlayer('player', { suggestedVideos: { configUrl: 'suggested_videos.json' } });

JSON 里每项带标题、封面和各自的播放源，点击某格会直接把新视频灌进同一个播放器实例继续播。

⚡ 第三步：调参速查

布局和控制栏常用项：

广告相关常用项：

完整类型定义都写在 src/index.d.ts 里，找不到某个开关时直接查它最快。

🔧 第四步：踩坑与自救

现象：VPAID 广告完全不出现。原因：allowVPAID默认是false，播放器出于安全考虑不放行 VPAID 脚本。 解法：在vastOptions里显式设allowVPAID: true，再确认广告商给的确实是 VPAID 创意而非普通 VAST。

现象：midRoll 设了广告但永远不插。原因：中插必须带timer，缺了它播放器不知道触发时机。 解法：补上timer，支持秒数（如30）或百分比（如'50%'），长视频建议用百分比。

现象：主广告源经常超时，播放器直接干等。原因：只给了一个vastTag，请求失败就没有后手。 解法：给同一条广告加fallbackVastTags数组，播放器按顺序逐个请求，直到拿到能出广告的那个——这就是仓库测试用例里反复覆盖的瀑布流场景。

现象：页面看起来"糙"——控制栏一直杵着、视频上下留黑边。原因：autoHide默认关闭，fillToContainer等布局项用的是默认值。 解法：打开controlBar.autoHide并调短超时；视频铺不满容器时检查fillToContainer与封面尺寸posterImageSize（cover/contain）。

现象：运行时切换 HLS 源后，播放进度被重置（iOS 尤其明显）。原因：这是项目已知的问题类型，仓库 special-cases 目录里有对应复现页。 解法：暂时避开频繁动态换源，把多清晰度写进初始<source>列表让播放器内部管理切换。

生产环境组合拳

真实业务里这些配置是叠在一起用的，一份完整长这样：

fluidPlayer('player', { layoutControls: { posterImage: 'poster.jpg', controlBar: { autoHide: true, autoHideTimeout: 3 } }, vastOptions: { adList: [ { roll: 'preRoll', vastTag: 'pre.vast', fallbackVastTags: ['fallback1.vast'] } ], allowVPAID: true }, suggestedVideos: { configUrl: 'suggested.json' } });

上生产前建议照着 test/html/ 目录里的hls_vod_vast、suggested_videos等现成页面逐项核对自己的配置，广告和推荐列表各走一遍完整流程。

回到开头那个 VAST 需求：现在广告方再来要贴片，你只需要在adList里多填一行。下一步动作就一个——把 test/html/ 下对应你业务场景的示例页在本地跑起来，对着抄。

【免费下载链接】fluid-playerFluid Player - an open source VAST compliant HTML5 video player项目地址: https://gitcode.com/gh_mirrors/fl/fluid-player