apify-ads-intelligence

广告情报集群

通过将问题路由到合适的 Apify Actor 并综合整理答案，回答有关广告、广告资料库和竞争对手广告活动的自然语言问题。

CLI 规则： 始终传入 --user-agent apify-awesome-skills/apify-ads-intelligence、--json（或在 datasets get-items 中使用相应的 --format 标志）以及 2>/dev/null。--user-agent 标志对遥测至关重要，绝不能省略。

关于平台覆盖范围的说明

• Meta、Google、TikTok、LinkedIn：拥有丰富数据（创意素材、定向、日期，以及公开时的覆盖人数）的真实公开广告资料库。
• X (Twitter)：没有公开广告资料库。覆盖范围采用尽力而为的变通方案，通过抓取品牌推文，并将 card 字段非空或 source 包含 "Ads" 的条目标记为可能推广的内容。综合结果中务必注明这一限制。

关于与 apify-ecommerce 重叠的说明

该技能包含一个 ads-intelligence 意图，会将浅层 Meta 广告查询路由到 apify/facebook-ads-scraper。本技能则深入覆盖全部五个平台。如果你只需要在电商问题中顺带了解 Meta 广告，请使用 apify-ecommerce。如果广告是主要任务，请使用本技能。

先决条件

（无需预先检查）

• Apify CLI v1.5.0+（npm install -g apify-cli）
• jq（建议用于解析和筛选响应；macOS 上使用 brew install jq，Linux 上使用 apt install jq）
• 通过以下任一方式进行身份验证：
  • apify login（OAuth，会打开浏览器）
  • APIFY_TOKEN 环境变量（例如 export APIFY_TOKEN=... 或 .env 文件）
  • 从 Apify 控制台 → 设置 → 集成 获取令牌

验证身份验证：apify info --user-agent apify-awesome-skills/apify-ads-intelligence — 应显示用户名和 userId。

工作流

复制此清单并跟踪进度：

Task Progress:
- [ ] Step 1: Detect intent and select Actor(s)
- [ ] Step 2: Fetch Actor schema
- [ ] Step 3: Ask user preferences (output format, result count, country)
- [ ] Step 4: Run the Actor (or Actors in parallel for cross-platform-audit) and fetch results
- [ ] Step 5: Synthesize a direct answer (not a data dump)

第 1 步：识别意图并选择 Actor

将用户的消息归类为一种意图，然后选择合适的 Actor。

意图信号：

用户消息中的信号	意图
"what ads is X running", "competitor [brand] ads", "[brand] FB/Google/TikTok/LinkedIn/X/Twitter ads", "show ads from [page]", "promoted tweets from [brand]"	competitor-ads
"ads about [topic]", "find [keyword] ads", "ads for [vertical]", "fitness/fintech/saas ads"	keyword-ads
"trending ads", "winning ads", "top ads", "best performing", "long-running ads", "creative inspiration"	top-creatives
"where do these ads go", "landing pages from ads", "click destinations", "ad funnels"	landing-page-audit
"compare X's ads across platforms", "all ads from [brand]", "cross-platform ad audit"	cross-platform-audit

如果检测到多个意图，请询问：“你想选择 [意图 A] 还是 [意图 B]？”

Actor 路由——始终先尝试 Primary，仅当其失败或返回 0 条结果时才切换到 Fallback：

意图	平台	Primary Actor	Fallback Actor
competitor-ads	Meta (FB/IG)	apify/facebook-ads-scraper	brilliant_gum/facebook-ads-library-scraper
competitor-ads	Google	dz_omar/google-ads-scraper	solidcode/ads-transparency-scraper
competitor-ads	TikTok	brilliant_gum/tiktok-ads-library-scraper (source: library)	silva95gustavo/tiktok-ads-scraper
competitor-ads	LinkedIn	silva95gustavo/linkedin-ad-library-scraper	dz_omar/linkedin-ads-scraper
competitor-ads	X（变通方案）	apidojo/twitter-scraper-lite (twitterHandles: [<brand>]) + 启发式过滤	apidojo/tweet-scraper
keyword-ads	Meta	brilliant_gum/facebook-ads-library-scraper	apify/facebook-ads-scraper
keyword-ads	Google	apify/google-search-scraper (focusOnPaidAds: true)	—
keyword-ads	TikTok	brilliant_gum/tiktok-ads-library-scraper	—
keyword-ads	LinkedIn	silva95gustavo/linkedin-ad-library-scraper	—
keyword-ads	X（变通方案）	apidojo/twitter-scraper-lite (searchTerms: [<keyword>]) + 启发式过滤	apidojo/tweet-scraper
top-creatives	Meta	brilliant_gum/facebook-ads-library-scraper（按 daysRunning 排序）	—
top-creatives	TikTok	burbn/tiktok-top-ads-spy（按 CTR / 展示次数 / 点赞数排序）	brilliant_gum/tiktok-ads-library-scraper (source: creative_center)
top-creatives	Google	不适用——回退到 competitor-ads 路由，并筛选仍在投放的广告	—
top-creatives	LinkedIn	不适用——回退到 competitor-ads 路由，并按 impressionsPerCountry 覆盖范围排序	—
top-creatives	X	v1 中不适用——各时间线中没有可靠的推广内容信号	—
landing-page-audit	Meta	brilliant_gum/facebook-ads-library-scraper (resolveSnapshotUrls: true)	—
landing-page-audit	Google	apify/google-search-scraper (focusOnPaidAds: true, directUrl)	dz_omar/google-ads-scraper (destinationUrl)
landing-page-audit	X	v1 中不适用——启发式方法对提取落地页的可靠性不足	—
cross-platform-audit	全部五个平台	并行运行 Meta、Google、TikTok 和 LinkedIn 的 Primary；X 的变通方案单独运行，并附带说明。按广告主合并结果。	—

X (Twitter) 启发式过滤——抓取完成后，如果满足以下任意条件，就将推文标记为可能是推广内容：

• card 字段非空（推广推文通常会附带网站卡片 / CTA）
• source 字段包含 "Ads"（例如 "Twitter Ads"）

展示结果时明确说明：“X 没有公开广告库；以下结果是品牌自身时间线中符合推广内容启发式条件的推文。其他用户信息流中仅对推广受众展示的广告不会出现在结果中。”

第 2 步：获取 Actor 架构

获取 Actor 摘要、输入架构和 README：

# Summary (title, description, pricing, stats)
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null

# Input schema (required and optional parameters; schema lives in
# .taggedBuilds.latest.build.inputSchema as an escaped JSON string)
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --input --json 2>/dev/null

# README (capabilities, examples, gotchas)
apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ads-intelligence --readme 2>/dev/null

将 ACTOR_ID 替换为选定的 Actor（例如，apify/facebook-ads-scraper）。

第 3 步：询问用户偏好

运行前，询问：

1. 输出格式：

   • 快速回答（默认）——在聊天中综合作答，不保存文件
   • CSV ——将完整导出内容保存到磁盘
   • JSON ——将完整导出内容保存到磁盘

2. 结果数量 ——根据意图使用以下默认值：

   意图	默认数量
   competitor-ads	30
   keyword-ads	30
   top-creatives	20
   landing-page-audit	50
   cross-platform-audit	每个平台 15 条

3. 国家/地区 ——默认为 US。对于 TikTok 广告资料库，默认为 DE（仅限欧盟），并提醒用户；对于全球 TikTok，使用 source: creative_center。X 路由依据账号名称/关键词面向全球，不需要国家/地区参数。

成本安全：始终在 Actor 输入中设置合理的结果上限（例如，maxResults、resultsLimit，或 Actor 架构中对应的字段）。运行会抓取 500 条或更多广告时，先提醒用户——apify/facebook-ads-scraper 按广告收费，X 主力 Actor 按推文收费。

第 4 步：运行 Actor 并获取结果

分两步：运行 Actor（会一直阻塞，直到完成），然后按所需格式获取数据集条目。

运行 Actor ——以 JSON 格式返回运行元数据；提取 defaultDatasetId 以用于下一步：

apify actors call "ACTOR_ID" -i 'JSON_INPUT' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null

从输出中使用 .id（运行 ID）、.status（应为 SUCCEEDED）和 .defaultDatasetId。

获取结果 ——根据用户偏好选择相应的变体：

# Quick answer: total count + fields + top 5 in chat (no file)
apify datasets info DATASET_ID --json \
  --user-agent apify-awesome-skills/apify-ads-intelligence 2>/dev/null \
  | jq '{itemCount, fields, consoleUrl}'
apify datasets get-items DATASET_ID --limit 5 \
  --user-agent apify-awesome-skills/apify-ads-intelligence --format json 2>/dev/null

# CSV file
apify datasets get-items DATASET_ID \
  --user-agent apify-awesome-skills/apify-ads-intelligence --format csv 2>/dev/null > YYYY-MM-DD_filename.csv

# JSON file
apify datasets get-items DATASET_ID \
  --user-agent apify-awesome-skills/apify-ads-intelligence --format json 2>/dev/null > YYYY-MM-DD_filename.json

其他 --format 选项：jsonl、xlsx、xml、rss、html。使用 --offset N 对大型数据集进行分页。

提示： 对于不只是快速查看的任务，先将数据集保存到本地文件（使用 > file.json / > file.csv），再从磁盘进行后续分析。apify datasets get-items 始终通过网络传输数据，因此直接将其管道传给 jq 会在每次迭代时重新下载全部内容。

跨平台审计（并行运行）： 对于 cross-platform-audit，通过在后台运行每个 apify actors call ... 调用（加上 &），并在获取结果前调用 wait，并行启动 Meta、Google、TikTok 和 LinkedIn 主力 Actor。示例：

apify actors call "apify/facebook-ads-scraper" -i '<META_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > meta_run.json &
apify actors call "dz_omar/google-ads-scraper" -i '<GOOGLE_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > google_run.json &
apify actors call "brilliant_gum/tiktok-ads-library-scraper" -i '<TIKTOK_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > tiktok_run.json &
apify actors call "silva95gustavo/linkedin-ad-library-scraper" -i '<LINKEDIN_INPUT>' \
  --user-agent apify-awesome-skills/apify-ads-intelligence --json 2>/dev/null > linkedin_run.json &
wait
# Then extract each .defaultDatasetId and fetch items per platform; X workaround runs separately with caveat.

结合 jq 快速提取：

将 jq 作为 apify datasets get-items 的补充，而非替代方案：服务端的 --limit / --offset / --format 能减少成本和带宽消耗。在样本条目或已保存的文件上使用 jq。

# Discover real field names from one sample item (Actor outputs vary —
# use this before composing further jq queries)
apify datasets get-items DATASET_ID --limit 1 --format json \
  --user-agent apify-awesome-skills/apify-ads-intelligence 2>/dev/null \
  | jq '.[0]'

# X heuristic filter on a saved tweets file: keep items with non-empty card
# or source containing "Ads"
jq '[.[] | select((.card != null and .card != "") or (.source != null and (.source | contains("Ads"))))]' \
  YYYY-MM-DD_x_tweets.json

第 5 步：分析结果并给出答案

综合归纳，不要照搬数据。不同意图应呈现的内容：

意图	综合归纳应呈现的内容
competitor-ads	找到的广告总数、活跃与非活跃广告的数量分布、热门创意形式、排名前 5 的广告文案片段、唯一落地页域名列表。针对 X：抓取的推文总数、标记为可能推广内容的数量，以及排名前 5 的已标记推文，并说明检测结果基于启发式判断。
keyword-ads	使用该关键词投放广告的排名前 5 的广告主、广告总数、国家分布
top-creatives	按 daysRunning（Meta）或 CTR（TikTok）排名前 5 的创意，附创意摘要和 Ad Library 条目链接
landing-page-audit	唯一落地页 URL 列表，按域名分组，并标明指向各页面的广告数量
cross-platform-audit	各平台的广告数量和语气摘要，然后推断“他们在哪个平台投放最多”

建议的后续操作——根据刚执行的意图提供建议：

如果用户刚执行了……	建议下一步
competitor-ads（Meta）	结合 apify-competitor-intelligence，补充其 FB Page 帖子、IG 个人资料和 Google Maps 评论
landing-page-audit（任意平台）	结合 apify-ecommerce（tech-stack 意图），检测落地页背后的平台；或结合 apify-lead-generation，补充目标域名的联系信息
top-creatives（TikTok / Meta）	如果有创意是与网红合作制作的，结合 apify-influencer-discovery
keyword-ads（Google / Meta）	结合 apify-trend-analysis，查看该关键词在 Google Trends / Instagram / TikTok 上的热度是上升还是下降
cross-platform-audit	结合 apify-content-analytics，了解该品牌的自然内容情况；综合呈现付费与自然内容

注意事项

• TikTok 关键词搜索的范围较宽。 搜索 “Nike” 可能会返回无关广告主的广告（我们的测试中有 Interactive Brokers 和 Shopify）。务必根据 advertiserName 筛选，与用户指定的品牌匹配；如果筛选后没有结果，请提醒用户。
• TikTok Ads Library 仅覆盖 EU/EEA/UK。 library 来源需要 EU 国家代码（DE / FR / IT / ES / NL / PL / SE 等）。如需覆盖美国或全球范围，请切换到 creative_center 来源——字段有所不同（CTR、展示次数范围，不含定向数据）。
• dz_omar/google-ads-scraper 要求 resultsPerQuery >= 10。 设置更小的值会导致验证失败。即使意图范围较小，也务必设置为 10 以上。
• apify/facebook-ads-scraper 接受 URL，而非关键词。 对于 competitor-ads：根据品牌名称构造 https://www.facebook.com/<PageName>。对于 keyword-ads：构造包含 q=<keyword>&country=<XX> 的 Meta Ad Library URL。
• apify/google-search-scraper 的付费广告模式在未找到付费结果时会内置重试（最多 3 次）——有时确实不存在符合查询条件的付费结果。请将空的 paidResults 视为有效答案，而非错误。
• LinkedIn Ad Library URL 构造： 公司 URL https://www.linkedin.com/company/<slug>/ 可以使用，但速度较慢且会忽略筛选条件。对于 competitor-ads，使用 https://www.linkedin.com/ad-library/search?accountOwner=<slug>&countries=<XX>。对于 keyword-ads，使用 ?keyword=<term>&countries=<XX>。
• X 没有公开的广告库。 覆盖范围仅基于启发式判断。该路由使用 apidojo/twitter-scraper-lite 抓取品牌自己的推文（或关键词搜索结果），然后将 card 字段非空或 source 包含 "Ads" 的条目标记为可能推广内容。此方法会漏掉那些只作为推广内容出现、从未出现在品牌自身时间线中的推文。
• X 对会话状态敏感。 如果主要 X Actor 只返回 noResults 哨兵值，请改用备用方案，再判定结果为零。
• 费用。 在我们的定价档位中，大多数主要工具均免费；apify/facebook-ads-scraper 按广告收费（$0.001 - $0.0058）；X 主要工具按推文收费（约 $0.0004 / 1k）。默认数量（30 / 20 / 50）的费用可以忽略不计。运行 500 条以上广告的任务前，请先提醒用户。

错误处理

• 认证错误 → 运行 apify login，或设置 APIFY_TOKEN 环境变量
• Actor not found → 根据路由表检查 Actor ID
• 运行状态为 FAILED → 打开控制台 URL（运行元数据中的 .consoleUrl）查看日志
• 超时／运行时间过长 → 为 apify actors call 传入 --timeout <seconds>，或减少结果数量
• 结果为 0 → 切换到备用 Actor；如果仍为 0，尝试其他国家代码
• TikTok 库：未提供欧盟国家 → 默认使用 DE 并警告用户
• dz_omar/google-ads-scraper：resultsPerQuery 验证错误 → 将值提高到 10 或更高
• X 抓取工具：仅返回 noResults 占位值 → 切换到备用 X Actor
• proxy is required 错误 → 在输入中添加 "proxy": {"useApifyProxy": true}