google-ads

用途

Google Ads 技能用于管理 Google Ads 账户，支持通过 API 或浏览器自动化两种方式查询、审计和优化广告系列。

模式选择

使用前需先判断采用哪种模式：

API 模式：如果用户已配置 google-ads.yaml 或设置了 GOOGLE_ADS_* 环境变量。
浏览器模式：如果用户表示“没有 API 访问权限”，或只想做快速检查。

检查 API 配置的命令：

ls ~/.google-ads.yaml 2>/dev/null || ls google-ads.yaml 2>/dev/null

如果未找到配置，应询问用户：“你有 Google Ads API 凭据，还是让我使用浏览器自动化？”

浏览器自动化模式（通用）

要求：用户已在浏览器中登录 ads.google.com。

设置步骤：

用户打开 ads.google.com 并登录。
用户点击 Clawdbot Browser Relay 工具栏图标（徽章开启）。
使用浏览器工具，profile="chrome"。

常见工作流：

获取广告系列表现：导航至 ads.google.com/aw/campaigns，设置日期范围（右上角日期选择器），对广告系列表格做快照，解析 Campaign、Status、Budget、Cost、Conversions、Cost/Conv 字段。
查找零转化关键词（浪费支出）：导航至 ads.google.com/aw/keywords，点击“Add filter”→ Conversions → Less than → 1，再点击“Add filter”→ Cost → Greater than → [阈值，例如 $500]，按 Cost 降序排序，对表格做快照以供分析。
暂停关键词/广告系列：导航至关键词或广告系列视图，勾选要暂停的项目，点击“Edit”下拉菜单 → “Pause”，确认操作。
下载报表：导航至目标视图（广告系列、关键词等），点击表格右上角的“Download”图标，选择格式（推荐 CSV），文件下载到用户的 Downloads 文件夹。

详细浏览器选择器参见 references/browser-workflows.md。

API 模式（高级用户）

要求：Google Ads API 开发者令牌 + OAuth 凭据。

设置检查：

python -c "from google.ads.googleads.client import GoogleAdsClient; print('OK')"
cat ~/.google-ads.yaml

常见操作：

查询广告系列表现：

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()
ga_service = client.get_service("GoogleAdsService")

query = """
    SELECT campaign.name, campaign.status,
           metrics.cost_micros, metrics.conversions,
           metrics.cost_per_conversion
    FROM campaign
    WHERE segments.date DURING LAST_30_DAYS
    ORDER BY metrics.cost_micros DESC
"""

response = ga_service.search(customer_id=CUSTOMER_ID, query=query)

查找零转化关键词：

query = """
    SELECT ad_group_criterion.keyword.text,
           campaign.name, metrics.cost_micros
    FROM keyword_view
    WHERE metrics.conversions = 0
      AND metrics.cost_micros > 500000000
      AND segments.date DURING LAST_90_DAYS
    ORDER BY metrics.cost_micros DESC
"""

暂停关键词：

operations = []
for keyword_id in keywords_to_pause:
    operation = client.get_type("AdGroupCriterionOperation")
    operation.update.resource_name = f"customers/{customer_id}/adGroupCriteria/{ad_group_id}~{keyword_id}"
    operation.update.status = client.enums.AdGroupCriterionStatusEnum.PAUSED
    operations.append(operation)

service.mutate_ad_group_criteria(customer_id=customer_id, operations=operations)

完整 API 参考参见 references/api-setup.md。

审计清单

对任意 Google Ads 账户进行快速健康检查：

零转化关键词：浏览器路径为 Keywords → Filter: Conv<1, Cost>$500，关注浪费支出。
空广告组：Ad Groups → Filter: Ads=0，关注无创意运行。
政策违规：Campaigns → Status 列，关注黄色警告图标。
优化得分：Overview 页面（右上角），低于 70% 表示需要采取行动。
转化跟踪：Tools → Conversions，关注不活跃或无近期数据。

输出格式

报告发现时使用表格，例如：

## Campaign Performance (Last 30 Days)
| Campaign | Cost | Conv | CPA | Status |
|----------|------|------|-----|--------|
| Branded  | $5K  | 50   | $100| ✅ Good |
| SDK Web  | $10K | 2    | $5K | ❌ Pause |

## Recommended Actions
1. **PAUSE**: SDK Web campaign ($5K CPA)
2. **INCREASE**: Branded budget (strong performer)

故障排查

浏览器模式问题：

看不到数据：检查用户是否在正确的账户（右上角账户选择器）。
加载缓慢：Google Ads UI 较重，等待表格完全加载。
会话过期：用户需重新登录 ads.google.com。

API 模式问题：

认证失败：刷新 OAuth 令牌，检查 google-ads.yaml。
开发者令牌被拒：确保令牌已获批（非测试模式）。
Customer ID 错误：使用 10 位 ID，不带连字符。

适用场景与限制

适用场景：需要批量查询或修改 Google Ads 账户数据、审计账户健康度、查找浪费支出、暂停关键词或广告系列、下载报表。

限制：API 模式需要开发者令牌与 OAuth 凭据；浏览器模式需要用户已登录 Google Ads 并启用浏览器中继。其他收费、价格、平台支持等细节暂未提供。