Communitygithub.com

HTML5 展示广告

构建可用于 Google Ads / Google 展示广告网络及其他广告服务器的生产级动画 HTML5 展示广告(横幅),每个尺寸一个独立 ZIP 包,支持基于视频、Figma 设计稿、PNG 导出或文案需求生成广告。

HTML5 展示广告 是什么?

HTML5 展示广告技能是一款专门用于创建、调整和修复动画 HTML5 展示广告(广告横幅)的专业开发工具。其主要目标是生成符合 Google Ads HTML5 技术规范的生产级广告素材,每个尺寸生成一个自包含的 ZIP 压缩包。该技能不仅支持从视频帧、Figma 设计稿、PNG 导出文件或纯文案需求中提取素材,还提供了完整的构建流程:素材处理(包括图片缩放、量化、LOGO 放大)、版面规划(基于 Figma 框架或参考帧精确匹配)、通过标准模板构建广告、全面的质量检测(QA)以及生成预览 MP4/GIF。技能文档中包含了丰富的元知识,例如 20 种标准尺寸列表(涵盖方形、摩天楼、横幅、移动端等)、常见陷阱(如类名冲突、括号错误、150KB 字节限制)以及针对不同平台的详细参考文档。它适用于 Claude Code、Cursor 等支持自定义技能或脚本调用的 AI 代码编辑器或智能体环境,通过 `scripts/` 和 `references/` 目录中的脚本和文档来实现半自动化的广告生产流程,开发者主要专注于源素材和版面设计。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Mgunther60/claude-skills-html/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

HTML5 展示广告 是做什么的?

构建一组动画 HTML5 横幅广告,每个尺寸一个独立的 ZIP 压缩包,通过 Google Ads 的 HTML5 合规检查。 scripts/ 目录中的脚本负责机械性工作(构建、QA、预览、图片处理);你的任务是获取正确的源素材和版面布局,这也正是绝大多数反复沟通的来源。

在首次构建前阅读 references/google-ads-html5.md(限制、clickTag、尺寸、上传步骤)。 如果需求涉及 Figma、视频或导出的帧,请立即阅读 references/sources-and-figma.md。 编写布局规范时阅读 references/spec-format.md。references/example-closet-world-bf2026.md 是一个完整的工作示例(21 个尺寸),可复制其模式。

如果 scripts/ 和 references/ 不在该文件旁边(例如只上传了 SKILL.md),请手动执行相同的工作流程:为每个广告编写 index.html,采用相同的结构(ad.size meta、var clickTag 在 head 中、整个广告的 window.open(window.clickTag) 退出、CSS 类时间线、#end 钩子、1px 边框),将每个尺寸与 index.html 一起压缩,并在无头浏览器中运行相同的检查。

如果项目属于某个拥有自身设计系统技能的品牌(例如 Closet World 的 cw-foundations 和 cw-social),也请阅读该技能:它决定了标志、颜色、字体和文案规则。本技能则决定广告格式。

工作流程

1. 需求获取(仅询问无法推断的信息)

获取:尺寸(如果用户说“所有尺寸”或未指定,使用下面标准的 20 尺寸集);优惠信息和标题文案;行动号召(CTA)措辞;点击 URL(使用默认值即可,因为 Google Ads 会替换 clickTag 为最终 URL);以及设计的来源:视频剪辑、Figma 框架、PNG 导出,或无来源(此时需根据需求说明和品牌规则自行设计)。 检查上传文件:用户提到的文件可能未实际到达。请查看 /mnt/user-data/uploads。

标准集(20 个尺寸)。 方形:200x200, 240x400, 250x250, 250x360, 300x250, 336x280, 580x400。 摩天楼:120x600, 160x600, 300x600, 300x1050。 横幅:468x60, 728x90, 930x180, 970x90, 970x250, 980x120。 移动端:300x50, 320x50, 320x100。将此列表保存为变量并基于它构建广告,这样即使在多轮迭代中也不会遗漏任何尺寸。

2. 源素材:获取真实作品,并确保足够分辨率

每个广告的质量都依赖于这一步。优先级排序:

  1. 官方文件(用户上传的标志、组合标志、照片)。请按图层名称和导出比例索取。
  2. Figma 通过连接器:get_metadata 可获取框架尺寸和图层坐标;get_screenshot 配合 enableBase64Response 可让你看到框架。沙盒中通常无法直接下载 figma.com 资源(curl 返回退出码 6),因此通常无法保存 Figma 像素。建议用户导出特定图层。
  3. 视频帧(layers.py frames),将作品从纯色背景上分离(layers.py key),并裁剪出产品(layers.py cutout --region)。这些帧清晰度高(1080 px),但构图紧凑。
  4. 1x 原始帧导出(来自用户):构图精确,但分辨率低。需结合更清晰的来源(layers.py find 可在更清晰图片中定位裁剪区域;layers.py blend 可将清晰渲染图合并到模糊导出图中)。

始终明确说明每个资源来自何处及其代价(例如“标志从视频中提取,因此较模糊;请发送官方文件修复”)。用户首先会注意到模糊的标志。

3. 各尺寸版面布局

  • 当某个尺寸存在 Figma 框架或导出的 PNG 时,请精确匹配。 通过 PNG 测量位置(面板颜色通道,艺术元素 alpha 或非背景边界框);不要目测。检查 PNG 的实际像素尺寸:框架命名可能出错(例如“120x600”导出为 160 宽,“970x90”绘制为 960)。请在 Google 定义的尺寸下构建,将多余像素放置在某个中性区域(实色面板),并告知用户。
  • 当某个尺寸没有对应框架时,从同一系列中最近似且已批准的尺寸推导(参见 references/spec-format.md 中的系列模式),告知用户这是你的改编版本,并提供调整选项。
  • 用户常按场景发送帧(画面 1、2、3)。请将这些视为照片、裁剪和任何移动元素(例如标志在标语出现时下移)的每个场景的真实依据。
  • 翻转的 Figma 图层会报告令人困惑的 x 坐标。请改用屏幕截图或导出版本进行测量。

4. 准备资源

  • 图片按 2 倍 CSS 尺寸(照片为 JPG,质量 60-78),艺术作品使用调色板 PNG(quantize,16-64 色)。标志按 3 倍(因为人们第一眼会看它们;layers.py logo 可完成此操作)。
  • 横跨双色背景的产品:将每个场景的全宽产品素材平铺在广告自身背景上,分割行位于整数像素处,确保图片边缘与 CSS 之间无可见接缝。
  • 确保每个 ZIP 包小于等于 150,000 字节;必要时降低 JPG 质量或将大照片缩放到 1.5 倍。

5. 构建

为每个尺寸编写一个 JSON 规范(references/spec-format.md),然后运行:

python scripts/build_ad.py specs/300x250.json --assets prepared/300x250 --out build

该命令会生成 build/300x250/index.html 及其资源,以及 build/<prefix>_300x250.zip(文件位于 ZIP 根目录),并输出字节数和文件数量。模板已包含:<meta name="ad.size">、head 中的 var clickTag、整个广告的退出 window.open(window.clickTag)、共享的运动时间线、1px 边框、减少运动支持以及一个跳转到结束帧的 #end URL 钩子。

动画(除非有要求,否则保持整组一致):标题进入(0.2 秒)、优惠信息弹出(0.9 秒)、场景 2(2.4 秒)、场景 3 标题与标签互换(4.8 到 5.1 秒)、结束卡片上滑显示优惠信息、标志和 CTA(7.6 到 8.7 秒)、CTA 闪亮效果;播放两次后,停留在大约 21 秒的结束卡片上(低于 Google 的 30 秒限制)。

6. 质量检查(每次每个尺寸都必须执行)

python scripts/qa_ads.py build/300x250 build/728x90 --zips build/*.zip --timing

检查 ad.size meta、clickTag 声明和退出功能、CSS 花括号平衡、页面和控制台错误、外部请求、损坏的图片、溢出广告的元素、结束卡片显示、CTA 文本裁剪、点击是否能打开 clickTag URL、两次播放后的静止状态、ZIP 根目录结构、字节数和文件数量。修正问题并重新运行,直到全部通过。然后查看结果:渲染每个场景状态(类 still s1 s2、still s1 s2 c2、still s1 s2 c2 c3 s3 和 end),并与参考帧并排比较。按区域(左边区域、照片、优惠信息)进行像素差异分析可快速找出差异。

7. 预览

python scripts/record_preview.py build/300x250 build/728x90 --out outputs/preview_name --zoom 2

该命令生成实际速度的 MP4 和 GIF(通过页面时钟重新调整捕获时间)。在展示前检查四个关键帧(大约 1.5、3.4、6.0 和 9.5 秒):标题和优惠信息、场景 2、标签行、结束卡片。

8. 交付

  • 首先检查覆盖率: 将生成的 ZIP 文件名与需求尺寸列表进行比对,补充任何缺失的尺寸后再回复(250x250 曾因错误在多轮迭代中丢失)。对共享资源(标志、优惠信息、模板)进行任何更改后,需重新对整个集合运行 QA。
  • 每个尺寸一个 ZIP,命名为 <Brand>_<Campaign>_<WxH>.zip,复制到 /mnt/user-data/outputs/,并先展示预览 GIF。如果重新生成了 ZIP,请确认交付文件内容已更改(使用 cmp 命令比较文件内部),因为时间戳可能看起来陈旧。
  • 对于完整集合,还需交付一个包含所有尺寸的打包文件(README、每个尺寸的概览图以及 ZIP 包)。
  • 回复内容应包括:每个文件中包含什么、动画的简短序列、尺寸大小(KB)、哪些布局遵循了 Figma 框架、哪些是你的改编版本,以及任何妥协(模糊来源、更改的 CTA 措辞、960 变为 970 等)。
  • 对于首次使用的用户,应解释 HTML 文件位于 ZIP 包内,他们上传的是 ZIP 文件本身,解压后双击 index.html 即可预览(图片必须与其保持在同一目录)。

通过艰难教训总结的注意事项

  • 类名与状态类冲突。 时间线会给 #ad 添加 c2/c3 类;切勿给元素赋予这些类名(一个图片类 .c2{opacity:0} 曾导致整个广告被隐藏)。模板使用 sc2/sc3。
  • 花括号拼写错误会禁用其后的所有规则。 一个多余的 } 可能静默地禁用结束卡片。构建器和 QA 都会检查花括号平衡。
  • 视频编码会轻微改变颜色;Figma 是精确的。 品牌颜色应从 Figma(在纯色图层上使用 get_design_context)或品牌技能中获取,而不是从视频像素获取。如果创意中使用的红色与品牌标准冲突,应说明差异,而不是默默“修正”它。
  • 无头浏览器捕获运行速度比实际慢 10-35% 且不均匀。 永远不要信任录制的原始时间戳;请使用 record_preview.py。
  • 50 像素高的文本。 “Schedule a free consultation” 在 300x50 的结束卡片上放不下;请使用简短的 CTA(如“Book now”),并在合适的地方保留完整措辞。告知用户。
  • Google 计数 150 KB。 确保小于等于 150,000 字节,以避免该限制的两种解释方式导致问题。
  • CTA 文本拥挤。 比按钮内边距稍宽的标签仍然可见,但会偏离中心。qa_ads.py 会对此发出警告;可以减小按钮内边距(从 14 像素减小到 10 像素)或减小字号。
  • 共享资源的更改会影响每个 ZIP。 当标志或组合标志被替换时,需要重新生成所有尺寸,重新运行 QA,替换或删除旧的打包文件(例如旧的“所有尺寸”ZIP),并确认每个交付文件都已更改。
  • 一次性精确提问。 当需要文件时,请以表格形式列出精确的图层、框架和导出比例,同时提供替代方案(机构所有者可以将 www.figma.com 加入白名单)。对于已经回答过的问题,不要再次询问。

相关技能