名称： meta-ad-creatives
版本： 1.0.0
描述： 追踪多个账户中 Meta（Facebook/Instagram）广告创意的表现和达标率。当被问及创意胜率、哪些广告达到基准、CPT/CPI/ROAS 分析，或跨账户和跨时间段比较创意表现时使用。支持多种基准指标（CPT、CPI、IPM、ROAS）和货币转换。

Meta 广告创意分析

追踪多个 Meta 广告账户中创意的表现和达标率。

功能概述

• 计算达标率（符合表现基准的创意百分比）
• 追踪多种指标：CPT（单次试用成本）、CPI（单次安装成本）、IPM（每千次展示安装数）、ROAS（广告支出回报率）
• 跨多个账户比较表现
• 存储历史数据用于趋势分析
• 识别优胜创意与表现不佳者
• 为国际账户支持货币转换

设置

1. 环境变量

FACEBOOK_ACCESS_TOKEN=你的令牌
FACEBOOK_APP_ID=你的应用ID
FACEBOOK_APP_SECRET=你的应用密钥

2. 账户配置

创建 accounts_config.json 文件：

{
  "accounts": {
    "客户名称": {
      "account_id": "123456789",
      "filter": "广告系列名称过滤器",
      "geo_filter": "美国",
      "benchmark_value": 100,
      "benchmark_display": "CPT < $100",
      "active": true
    }
  }
}

配置字段说明：
- account_id: Meta 广告账户 ID（无需 act_ 前缀）
- filter: 广告系列名称过滤器（可选）
- geo_filter: 地理过滤器，如 "US"（可选）
- benchmark_value: 判定“优胜”创意的 CPT 阈值
- benchmark_display: 人类可读的基准描述

使用方法

获取本月达标率

from scripts.meta_ad_creatives import get_all_hit_rates

data = get_all_hit_rates(month_offset=0)
print(f"总体达标率: {data['totals']['hit_rate']}%")
for account in data['accounts']:
    print(f"  {account['account_name']}: {account['hit_rate']}%")

获取历史月份达标率

# 上个月
data = get_all_hit_rates(month_offset=-1)

# 上上个月
data = get_all_hit_rates(month_offset=-2)

获取累计（所有时间）聚合数据

data = get_all_hit_rates(all_time=True)

获取单个广告表现详情

from scripts.meta_ad_creatives import get_individual_ads

# 获取某账户的所有广告
ads = get_individual_ads(account_name="客户名称", month_key="2026-01")

# 仅获取优胜广告
winners = get_individual_ads(account_name="客户名称", hit_only=True)

# 按 CPT 排序
ads = get_individual_ads(sort_by="cpt")

月度对比

from scripts.meta_ad_creatives import get_monthly_comparison

# 比较最近3个月
months = get_monthly_comparison(num_months=3)
for month in months:
    print(f"{month['month_label']}: {month['totals']['hit_rate']}%")

关键指标

达标率计算逻辑

一个创意被判定为“达标”需满足以下条件：
1. 花费 > $0
2. 试用次数 > 0
3. CPT < benchmark_value（例如 $100）

达标率 = (达到基准的广告数 / 有花费的广告数) × 100

数据存储

本技能存储历史数据以支持趋势分析：
- Firestore（云端部署的默认选项）
- SQLite（本地备用选项）

在本地环境中，可设置 USE_FIRESTORE=false 来使用 SQLite。

可解答的常见问题

• “我们本月的创意达标率是多少？”
• “[客户] 有哪些优胜创意？”
• “本月与上月相比表现如何？”
• “展示所有达到基准的广告”
• “我们的累计达标率是多少？”