Meta Ads Collector 技能

用途

调用 Meta 广告库 API（Meta Ad Library API），检索指定品牌当前投放的活跃广告。提取活跃广告总数、所使用的广告格式、广告类型，以及持续时间最长的活跃广告已上线天数。该采集器为营销审计流水线（Marketing Audit Pipeline）提供数据，用于填充最终报告中“付费广告策略”（Paid Ads Strategy）章节。

输入 Schema

// 函数签名
collectMetaAds(brandName: string, domain?: string): Promise

// brandName：在广告库中搜索的品牌名称（例如 "Gymshark"）
// domain：可选的域名，用于细化搜索（例如 "gymshark.com"）。当品牌名称存在歧义时，
// 该参数可用于过滤结果并提升相关性。

输出 Schema

interface MetaAdsData {
 activeAds: number; // 当前活跃广告总数
 formatsUsed: string[]; // 例如 ["image", "video", "carousel"]
 longestRunningAdDays: number; // 持续时间最长的活跃广告已上线天数
 adTypes: string[]; // 例如 ["POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "OTHER"]
 estimatedSpend?: string; // 例如 "$10,000 - $50,000"（若 API 返回该字段）
 error?: string; // 仅在采集器执行失败时存在
}

API 依赖项

• API 名称：Meta Ad Library API
• Endpoint：https://graph.facebook.com/v19.0/ads_archive
• 认证方式：META_ACCESS_TOKEN 环境变量（需注册具备 Ad Library API 访问权限的 Facebook App）
• 其他必需环境变量：META_APP_ID、META_APP_SECRET（必要时用于生成访问令牌）
• 费用预估：免费（无单次请求费用）
• 速率限制：受 Meta 标准 Graph API 限流策略约束（约 200 次请求/小时）

实现模式

数据流

1. 从流水线接收 brandName 及可选的 domain
2. 调用 metaAdsService.getMetaAds(brandName, domain)，该方法向广告库 API 发起查询
3. 对返回的广告数组进行处理，提取各项指标
4. 将处理后的数据映射至 MetaAdsData 接口结构

API 查询参数

{
 access_token: process.env.META_ACCESS_TOKEN,
 search_terms: brandName,
 ad_reached_countries: "['US']", // 默认限定为美国；后续可扩展
 ad_active_status: "ACTIVE", // 仅获取当前活跃广告
 ad_type: "ALL", // 包含所有广告类型
 fields: "id,ad_creation_time,ad_creative_bodies,ad_creative_link_captions,ad_creative_link_titles,ad_delivery_start_time,ad_snapshot_url,page_name",
 limit: 100 // 每页最多返回 100 条结果
}

指标计算逻辑

活跃广告数量：

• 统计 API 响应中返回的广告总数

广告格式识别：

• 通过分析 ad_snapshot_url 或创意字段（creative fields）判断广告格式
• 支持类别："image"、"video"、"carousel"、"dynamic"、"collection"
• 去重后返回唯一值列表

持续时间最长的广告：

const now = new Date();
const longestRunningAdDays = Math.max(
 ...ads.map(ad => {
 const startDate = new Date(ad.ad_delivery_start_time);
 return Math.floor((now.getTime() - startDate.getTime()) / (1000 * 60 * 60 * 24));
 })
);

广告类型：

• 从响应中提取唯一的 ad_type 值
• 常见类型包括："POLITICAL_AND_ISSUE_ADS"、"HOUSING_ADS"、"CREDIT_ADS"、"EMPLOYMENT_ADS"，以及通用/未分类类型（"OTHER"）

预估花费（Estimated Spend）：

• 仅政治类/议题类广告（political/issue ads）支持该字段（Meta 政策要求）
• 其他广告类型下该字段为 undefined
• 若可用，格式化为区间字符串，例如："$10,000 - $50,000"

域名过滤逻辑

当提供 domain 参数时：

• 仅保留广告创意正文（ad_creative_bodies）、链接标题（ad_creative_link_titles）或链接描述（ad_creative_link_captions）中包含该域名的广告
• 该机制可显著提升品牌名称常见（如 “Apple”、“Starbucks”）时的匹配准确率

错误处理

• 整个函数使用 try/catch 包裹
• 发生异常时，返回 EMPTY_META_ADS_DATA 并设置 error 字段：

return { ...EMPTY_META_ADS_DATA, error: 'Meta Ads data unavailable: ' };

• 永不抛出异常 —— 始终返回一个符合 MetaAdsData 类型定义的有效对象
• 使用 Winston 日志器记录错误详情，包含 brandName 和完整错误信息：

logger.error('Meta Ads collector failed', { brandName, domain, err });

• 常见失败场景包括：
• 访问令牌无效、已过期，或缺少 Ad Library 权限
• 品牌名称未返回任何结果（非错误情形 —— 应返回全零数据且不设 error 标志）
• 触发速率限制（Meta Graph API 流控）
• 网络超时

示例用法

import { collectMetaAds } from '../collectors/metaAdsCollector';

// 成功采集
const data = await collectMetaAds('Gymshark', 'gymshark.com');
// 返回：
// {
// activeAds: 47,
// formatsUsed: ["image", "video", "carousel"],
// longestRunningAdDays: 182,
// adTypes: ["OTHER"],
// estimatedSpend: undefined,
// }

// 未找到广告（非错误）
const noAds = await collectMetaAds('TinyLocalShop');
// 返回：
// {
// activeAds: 0,
// formatsUsed: [],
// longestRunningAdDays: 0,
// adTypes: [],
// }

// 采集失败（优雅降级）
const failedData = await collectMetaAds('Gymshark');
// 返回：
// {
// activeAds: 0,
// formatsUsed: [],
// longestRunningAdDays: 0,
// adTypes: [],
// error: "Meta Ads data unavailable: Access token expired"
// }

注意事项

• 本采集器依赖 metaAdsService.ts 执行实际 API 通信，自身仅负责数据聚合与指标计算。
• Meta Ad Library API 要求注册具备 Ad Library 权限的 Facebook App；该 App 需经 Meta 审核批准后方可投入生产环境使用。
• API 仅返回公开可查的广告数据；根据 Meta 的透明度政策，花费数据仅对政治类/议题类广告开放。
• “活跃广告数为 0” 是合法结果（小型或新兴品牌可能尚未投放 Meta 广告），此时不应设置 error 标志。
• EMPTY_META_ADS_DATA 常量定义于 src/types/audit.types.ts，应在降级返回时导入使用。
• 本采集器绝不可阻塞流水线执行；即使完全失败，也必须返回带 error 标志的合法类型化数据。
• 分页说明：Meta API 每页最多返回 100 条结果。对于广告数量庞大的品牌，可通过 after 游标实现分页；但出于审计目的，首页（100 条）结果已足够。