Ads Data Get

广告平台数据查询工具，支持 Facebook、TikTok 平台。

支持平台

| 平台 | 功能 | 环境变量 | |------|------|----------| | Facebook | 余额、消耗、多层级分析、国家维度 | facebook_access_token | | TikTok | 余额、消耗、多层级分析、国家维度 | tiktok_access_token, tiktok_app_id |

---

TikTok 广告数据分析

1. 快速汇总报告

# 获取所有账号余额/消耗汇总
python scripts/tiktok_ads.py

# JSON 格式输出
python scripts/tiktok_ads.py --json

2. 单账号全方位分析

# 分析指定账号（最近 7 天）
python scripts/tiktok_ads.py --analyze --account <advertiser_id>

# 指定时间范围
python scripts/tiktok_ads.py --analyze --account <advertiser_id> --since 2026-03-01 --until 2026-03-13

# 分析最近 30 天
python scripts/tiktok_ads.py --analyze --account <advertiser_id> --days 30

3. 单层级数据查询

# Campaign 级别数据
python scripts/tiktok_ads.py --account <advertiser_id> --level campaign --json

# AdGroup 级别数据
python scripts/tiktok_ads.py --account <advertiser_id> --level adgroup --json

# Ad 级别数据
python scripts/tiktok_ads.py --account <advertiser_id> --level ad --json

# 按国家分组
python scripts/tiktok_ads.py --account <advertiser_id> --level account --breakdown country --json

---

Facebook 广告数据分析

1. 快速汇总报告

# 获取所有账号余额/消耗汇总
python scripts/facebook_ads.py

# JSON 格式输出
python scripts/facebook_ads.py --json

2. 单账号全方位分析

# 分析指定账号（最近 7 天）
python scripts/facebook_ads.py --analyze --account act_586806297825353

# 指定时间范围
python scripts/facebook_ads.py --analyze --account act_586806297825353 --since 2026-03-01 --until 2026-03-13

# 分析最近 30 天
python scripts/facebook_ads.py --analyze --account act_586806297825353 --days 30

3. 单层级数据查询

# Campaign 级别数据
python scripts/facebook_ads.py --account act_586806297825353 --level campaign --json

# AdSet 级别数据
python scripts/facebook_ads.py --account act_586806297825353 --level adset --json

# Ad 级别数据
python scripts/facebook_ads.py --account act_586806297825353 --level ad --json

# 按国家分组
python scripts/facebook_ads.py --account act_586806297825353 --level account --breakdown country --json

---

命令行参数

| 参数 | 说明 | 示例 | |------|------|------| | --analyze | 执行全方位分析 | --analyze | | --account, -a | 指定账号 ID | --account act_123456 | | --level, -l | 数据层级: account/campaign/adset/ad | --level campaign | | --breakdown, -b | 分组维度 (可多次使用) | --breakdown country | | --since | 开始日期 | --since 2026-03-01 | | --until | 结束日期 | --until 2026-03-13 | | --days | 最近 N 天 | --days 30 | | --top | 显示 Top N 结果 | --top 20 | | --json, -j | JSON 格式输出 | --json |

---

Python 调用示例

TikTok

from scripts.tiktok_ads import (
    get_summary,
    analyze_account,
    get_insights
)

# 获取所有账号汇总
summary = get_summary()
print(f"总可用额度: ${summary['total_available']:,.2f}")
print(f"昨日总消耗: ${summary['total_yesterday_spend']:,.2f}")

# 全方位账号分析
analysis = analyze_account(
    "<advertiser_id>",
    date_range={"start_date": "2026-03-01", "end_date": "2026-03-13"},
    include_country_breakdown=True
)

Facebook

from scripts.facebook_ads import (
    get_summary, 
    analyze_account,
    get_insights,
    get_account_benchmarks
)

# 获取所有账号汇总
summary = get_summary()
print(f"总可用额度: ${summary['total_available']:,.2f}")
print(f"昨日总消耗: ${summary['total_yesterday_spend']:,.2f}")

# 全方位账号分析
analysis = analyze_account(
    "act_586806297825353",
    date_range={"since": "2026-03-01", "until": "2026-03-13"},
    include_country_breakdown=True
)

---

环境变量配置

在 ~/.openclaw/openclaw.json 的 env 中配置：

{
  "env": {
    "facebook_access_token": "EAAC...",
    "tiktok_access_token": "...",
    "tiktok_app_id": "..."
  }
}

---

注意事项

• Facebook Access Token 有过期时间，长期使用需要定期刷新
• TikTok 需要 Access Token 和 App ID
• 金额单位为美元 (USD)
• API 有调用频率限制，建议合理控制请求频率