什么是 Meta Ads 采集器技能？

Meta Ads 采集器技能是一种专门的技术集成，旨在直接与 Meta 广告库 API 交互。它使使用 Openclaw Skills 的开发人员和营销团队能够以编程方式检索有关品牌在 Face@book 和 In@stagram 上当前广告足迹的关键情报。通过扫描 Meta Graph API，此技能可以识别活跃的营销活动、对创意类型进行分类并测量现有广告组的持续时间。

此技能是自动化营销审计的基础组件。它将原始 API 响应转化为可操作的数据，例如确定视频与静态图片资产的分布情况，并识别运行时间最长的成功创意。这允许进行高水平的战略分析，而无需通过 Meta 广告库界面进行手动搜索。

下载入口:https://github.com/openclaw/skills/tree/main/skills/adarshvmore/meta-ads-collector

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Meta Ads 采集器技能 应用场景

• 通过坚控特定竞争对手活跃广告的数量和类型来自动进行竞争研究。
• 填充综合营销审计流程中的付费广告策略部分。
• 识别品牌使用的高效创意格式，如轮播或视频。
• 通过计算最旧的活跃广告的存续时间来衡量品牌稳定性。

1. 该技能接受品牌名称和可选域名以聚焦搜索参数。
2. 它使用提供的访问令牌和应用程序凭据通过 Meta Graph API 进行身份验证。
3. 向 ads_archive 端点发送请求，以获取符合搜索条件的当前活跃广告。
4. 如果提供了域名，采集器会通过检查广告链接和描述应用二级过滤，以确保结果属于目标品牌。
5. 该技能处理创意负载，将格式分类为图片、视频或轮播。
6. 它通过将投放开始时间与当前系统日期进行比较，计算运行时间最长的广告的投放天数。
7. 返回一个结构化的 JSON 对象，其中包含所有指标，确保与 Openclaw Skills 工作流兼容。

Meta Ads 采集器技能 配置指南

要部署 Meta Ads 采集器技能，您必须使用有效的 Face@book 应用凭据配置环境。使用以下 bash 命令设置环境变量：

export META_ACCESS_TOKEN='your_meta_access_token'
export META_APP_ID='your_app_id'
export META_APP_SECRET='your_app_secret'

确保您的 Face@book 应用已获得访问广告库 API 的权限。对于生产环境，这通常需要 Meta 应用审查流程。

Meta Ads 采集器技能 数据架构与分类体系

该技能将其提取的数据组织成结构化接口，以便于使用。以下是使用的元数据分类：

Meta Ads Collector Skill

Purpose

Scans the Meta Ad Library API to find active advertisements for a given brand. Extracts the number of active ads, ad formats used, ad types, and the longest-running ad duration. This collector feeds into the Marketing Audit Pipeline to populate the Paid Ads Strategy section of the final report.

Input Schema

// Function signature
collectMetaAds(brandName: string, domain?: string): Promise

// brandName: The brand name to search for in the Ad Library (e.g. "Gymshark")
// domain: Optional domain to refine search (e.g. "gymshark.com"). Used to filter
// results and improve relevance when the brand name is ambiguous.

Output Schema

interface MetaAdsData {
 activeAds: number; // Total count of currently active ads
 formatsUsed: string[]; // e.g. ["image", "video", "carousel"]
 longestRunningAdDays: number; // Days the longest-running active ad has been live
 adTypes: string[]; // e.g. ["POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "OTHER"]
 estimatedSpend?: string; // e.g. "$10,000 - $50,000" (if available from API)
 error?: string; // Present only when collector fails
}

API Dependencies

• API Name: Meta Ad Library API
• Endpoint: https://graph.facebook.com/v19.0/ads_archive
• Auth: META_ACCESS_TOKEN environment variable (requires a Face@book App with Ad Library API access)
• Additional env vars: META_APP_ID, META_APP_SECRET (used for token generation if needed)
• Cost estimate: Free (no per-request charge)
• Rate limits: Subject to Meta's standard Graph API rate limits (~200 calls/hour)

Implementation Pattern

Data Flow

1. Receive brandName and optional domain from the pipeline
2. Call metaAdsService.getMetaAds(brandName, domain) which queries the Ad Library API
3. Process the returned ads array to extract metrics
4. Map processed data to the MetaAdsData interface

API Query Parameters

{
 access_token: process.env.META_ACCESS_TOKEN,
 search_terms: brandName,
 ad_reached_countries: "['US']", // Default to US; can be expanded
 ad_active_status: "ACTIVE", // Only fetch currently active ads
 ad_type: "ALL", // Include all ad types
 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 // Max results per page
}

Metrics Calculation

Active Ads Count:

• Count the total number of ads returned from the API response

Formats Detection:

• Analyze ad_snapshot_url or creative fields to classify format
• Categories: "image", "video", "carousel", "dynamic", "collection"
• Deduplicate into a unique list

Longest Running Ad:

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 Types:

• Extract unique ad_type values from the response
• Common types: "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "CREDIT_ADS", "EMPLOYMENT_ADS", general/uncategorized

Estimated Spend:

• Only available for political/issue ads (Meta requirement)
• For other ad types, this field will be undefined
• If available, format as a range string: "$10,000 - $50,000"

Domain Filtering

When domain is provided:

• Filter results to only include ads where the creative body, link caption, or link title references the domain
• This improves accuracy for brands with common names

Error Handling

• Entire function wrapped in try/catch
• On failure, return EMPTY_META_ADS_DATA with error field set:

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

• Never throw -- always return a valid MetaAdsData object
• Log errors with Winston logger including brandName and error details:

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

• Common failure scenarios:
• Access token invalid, expired, or lacking Ad Library permissions
• Brand name returns zero results (not necessarily an error -- return zeroed data without error flag)
• Rate limit exceeded (Meta Graph API throttling)
• Network timeout

Example Usage

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

// Successful collection
const data = await collectMetaAds('Gymshark', 'gymshark.com');
// Returns:
// {
// activeAds: 47,
// formatsUsed: ["image", "video", "carousel"],
// longestRunningAdDays: 182,
// adTypes: ["OTHER"],
// estimatedSpend: undefined,
// }

// No ads found (not an error)
const noAds = await collectMetaAds('TinyLocalShop');
// Returns:
// {
// activeAds: 0,
// formatsUsed: [],
// longestRunningAdDays: 0,
// adTypes: [],
// }

// Failed collection (graceful degradation)
const failedData = await collectMetaAds('Gymshark');
// Returns:
// {
// activeAds: 0,
// formatsUsed: [],
// longestRunningAdDays: 0,
// adTypes: [],
// error: "Meta Ads data unavailable: Access token expired"
// }

Notes

• The collector depends on metaAdsService.ts for the actual API communication. The collector handles only data aggregation and metric calculation.
• Meta Ad Library API requires a Face@book App registered with Ad Library access. The app must be reviewed and approved by Meta for production use.
• The API only returns publicly available ad data. Spend data is only available for political/issue ads as mandated by Meta's transparency policies.
• Zero active ads is a valid result (small or new brands may not run Meta ads) and should be returned without an error flag.
• The EMPTY_META_ADS_DATA constant is defined in src/types/audit.types.ts and should be imported for fallback returns.
• This collector must never block the pipeline. Even a complete failure returns valid typed data with an error flag.
• Pagination: the Meta API returns a maximum of 100 results per page. For brands with many ads, pagination via the after cursor may be needed. For audit purposes, the first page (100 ads) is sufficient.