meta-ads-library

Meta 广告资料库

Meta 广告资料库搜索指南，以及如何生成结构化的竞品广告情报。

此技能旨在将抓取的原始广告转化为实用摘要：主要广告主、常见 CTA、反复出现的吸引点、近期发布的创意素材，以及（可选）经过补充信息的潜在客户名单。所有输出均直接显示在聊天中——没有数据库或持久化层。

不在此技能范围内——请转交其他技能

请求	转交至
多来源竞品研究（网站、社交媒体、搜索排名等，而不只是广告）	competitor-intel
根据研究结果生成新的广告创意素材	ad-creative-generation

要求

• 已安装并连接 Hyper MCP。 https://app.hyperfx.ai/mcp
• 已连接 Apify 集成，网址为 https://app.hyperfx.ai/apps — Meta 广告资料库工具通过 Apify 运行。

如果 search("meta_ad_library_ads_search") 没有找到 meta_ad_library_ads_search，请停止并告知用户启用 Hyper MCP 并连接 Apify。

如何运行此技能中的工具

此技能中的每个工具都使用其规范名称。使用当前界面提供的调用方式运行：

界面	查找工具	运行工具
MCP 客户端（Claude、Cursor、Codex、ChatGPT）	search("<what you want to do>")，然后运行 describe("<name>")	call("<name>", {...})
Hyper CLI	hyperai search "<what you want to do>"，然后运行 hyperai describe <name>	hyperai call <name> --json '{...}'

如果找不到某个工具，说明其集成尚未连接或未在工作区中启用：请停止并告知用户需要连接哪个集成。

工具概览

工具	用途
meta_ad_library_ads_search	按关键词搜索 Meta 广告资料库。返回精简结果（标题、正文、CTA、链接、主页名称、日期、平台）。每次最多 40 条。
meta_ad_library_ads_get	获取特定广告的完整详情。需要同时提供 ad_archive_id 和 page_id——两者均来自 meta_ad_library_ads_search 的结果。
meta_ad_library_ads_search_enriched	搜索并补充每条结果的主页联系信息（电子邮件、电话、网站）。速度较慢（每条结果会进行多次 API 调用）。每次最多 20 条。
meta_ad_library_pages_search	按类别和地点搜索 Facebook 主页（不能按关键词搜索）。适合从某个垂直行业中建立潜在客户名单。
meta_ad_library_pages_scrape	抓取指定 Facebook 主页 URL 的详细数据。

关键规则

1. 仅限公开数据。 Meta 广告资料库中的数据是公开的。不要试图绕过任何访问控制或抓取私密内容。
2. 不同工具的数量上限不同。 meta_ad_library_ads_search 的 count 最高为 40。meta_ad_library_ads_search_enriched 的上限为 20——超过上限会返回错误。
3. meta_ad_library_ads_get 需要两个 ID。 必须同时提供 ad_archive_id 和 page_id。每条 meta_ad_library_ads_search 结果中都会返回这两个 ID——请一并传入。
4. 补充信息搜索速度较慢。 它会为每条广告抓取一个 Facebook 主页，并可选择抓取网站。仅在需要联系信息时（潜在客户开发工作流）使用。纯粹获取广告情报时，请使用常规的 meta_ad_library_ads_search。
5. 基于 Apify 的工具有时会失败。 可能偶尔收到 "fetch failed" 响应。请稍等片刻后重试一次，再报告数据源缺失。
6. 不要过度解读单条广告。“品牌 X 正在打折”只是噪声。“此查询中排名前 10 的广告主有 5 个正在打折”才是信号。得出结论前务必先汇总。

工作流

阶段 1 — 定义查询

开始前，先确定以下事项：

1. 搜索查询 — 竞争对手会投放广告的关键词。示例："meal kit delivery"、"AI marketing tools"、"skincare for sensitive skin"。
2. 国家/地区 — ISO 代码（例如 "US"、"GB"、"AU"）。只有用户明确想要全球范围时，才默认使用 "ALL"。
3. 仅限投放中的广告，还是全部广告 — 通常应使用 active_status="active"。未投放的广告属于历史广告，噪声也更多。
4. 时间范围 — period 接受 "last24h"、"last7d"、"last14d"、"last30d" 或 "all_time"。根据用户的意图选择时间范围（每周摘要 → "last7d"，趋势研究 → "last30d"）。
5. 用途 — 用来做什么？
   • 创意趋势报告 → 使用 meta_ad_library_ads_search，总结广告开场、CTA 和格式方面的模式。
   • 头部广告主概览 → 使用 meta_ad_library_ads_search，按 page_name 分组。
   • 潜在客户列表 → 使用 meta_ad_library_ads_search_enriched，筛选出包含 contact_email 或 contact_website 的行。

阶段 2 — 获取广告

meta_ad_library_ads_search(
    query="meal kit delivery",
    country="US",
    active_status="active",
    count=40,                # max for this tool
    period="last30d"
)

每行结果均包含：ad_archive_id、page_id、page_name、is_active、start_date_formatted、end_date_formatted、title、body、cta_text、link_url、caption、ad_library_url、page_categories、publisher_platform。

超过 40 条广告时，通过再次调用并设置 offset=40、offset=80 等值进行分页。

需要包含联系信息的潜在客户数据时：

meta_ad_library_ads_search_enriched(
    query="meal kit delivery",
    country="US",
    active_status="active",
    count=20,                # max for the enriched tool
    scrape_websites=True,
    filter_spam=False
)

增强版结果还会包含：contact_email、contact_phone、contact_website、page_followers、page_rating、地址和营业时间。

阶段 3 — 获取最值得关注的广告的完整创意（可选）

meta_ad_library_ads_search 对部分广告的正文会进行截断。若要获取完整创意（包括视频 URL 和图片），请对值得深入了解的具体广告调用 meta_ad_library_ads_get：

meta_ad_library_ads_get(
    ad_archive_id="559220927273823",      # from search results
    page_id="328127803978438"             # from search results
)

两个参数均来自 meta_ad_library_ads_search 的同一行结果。仅对排名靠前的 3–5 条广告执行此操作，不要对全部 40 条都执行——每次详情调用都会单独运行一次 Apify。

阶段 4 — 呈现情报

直接在聊天中呈现调查结果。根据阶段 1 确定的用途，选择合适的格式。

头部广告主（按页面分组）：

页面	投放中的广告数	类别	值得注意的角度
Brand A	12	餐厅、套餐配送	12 条广告中有 8 条以“免去去杂货店购物”为切入点
Brand B	7	软件、订阅服务	大量采用 UGC 视频，并提供“首周 1 美元”优惠

常见 CTA 和广告开场：

模式	数量	示例
Sign up CTA	18	…
Shop now CTA	12	…
价格锚点开场（“每周 X 美元起”）	9	…
创始人故事开场	4	…

近期发布的广告（过去 7 天）：

页面	开始日期	CTA	广告开场	Library URL
Brand A	2026-04-28	Sign up	“这周不必去杂货店购物”	<ad_library_url>

潜在客户列表（仅限增强版数据）：

页面	邮箱	网站	粉丝数	投放中的广告数
Brand A	[email protected]	a.com	12K	7

阶段 5 — 定期监控（可选）

如果用户希望持续跟踪：

1. 保存查询、国家/地区和 active_status 设置。
2. 每周使用 period="last7d" 重新运行。
3. 摘要将变为差异报告，涵盖上次运行以来的新增广告、广告主发布频率的变化，以及 CTA / 优惠的变化。

此时，competitor-intel 会是更合适的技能——它能跨多个渠道进行多源差异比较，而不局限于 Meta 广告。

输出标准

• 引用具体广告时，务必附上 ad_library_url，方便用户点击核实。
• 先汇总，再引用。 不要粘贴原始广告正文；应提炼其模式，并引用 1–2 个有代表性的示例。
• 明确标注解读。 “观察：排名靠前的 10 个广告主中，有 8 个提供‘首周免费’优惠。可能的解读：……”。
• 注明时间范围。 每份摘要都应说明生成该摘要所用的搜索查询、国家/地区和日期范围。