Google Ads 技能

通过 API 或浏览器自动化方式管理 Google Ads 账户。

模式选择

请确认应使用哪种模式：

1. API 模式 — 若用户已配置 google-ads.yaml 文件，或设置了 GOOGLE_ADS_* 环境变量
2. 浏览器模式 — 若用户表示“我没有 API 访问权限”，或仅需快速检查

# 检查是否存在 API 配置
ls ~/.google-ads.yaml 2>/dev/null || ls google-ads.yaml 2>/dev/null

若未找到配置文件，请询问：“您是否拥有 Google Ads API 凭据？还是我应改用浏览器自动化？”

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

前提条件：用户已在浏览器中登录 ads.google.com

设置步骤

1. 用户打开 ads.google.com 并完成登录
2. 用户点击 Clawdbot Browser Relay 工具栏图标（确保徽章状态为 ON）
3. 使用 browser 工具，并指定 profile="chrome"

常见工作流

获取广告系列效果数据

1. 导航至：ads.google.com/aw/campaigns
2. 设置日期范围（右上角日期选择器）
3. 截取广告系列表格快照
4. 解析字段：广告系列名称、状态、预算、花费、转化次数、每次转化费用（Cost/Conv）

查找零转化关键词（浪费性支出）

1. 导航至：ads.google.com/aw/keywords
2. 点击“添加筛选条件” → “转化次数” → “小于” → “1”
3. 点击“添加筛选条件” → “花费” → “大于” → [阈值，例如 $500]
4. 按花费降序排列
5. 截取表格快照以供分析

暂停关键词 / 广告系列

1. 导航至关键词或广告系列视图
2. 勾选需暂停的条目复选框
3. 点击“编辑”下拉菜单 → 选择“暂停”
4. 确认操作

下载报告

1. 导航至目标视图（如广告系列、关键词等）
2. 点击表格右上角的“下载”图标
3. 选择格式（推荐 CSV）
4. 文件将自动下载至用户的 Downloads 文件夹

关于详细的浏览器选择器说明：参见 references/browser-workflows.md

API 模式（高级用户）

前提条件：Google Ads API 开发者令牌 + OAuth 凭据

设置验证

# 验证 google-ads SDK 是否可用
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 账户执行的快速健康检查：

输出格式

报告发现结果时，请统一使用表格格式：

## 广告系列效果（近 30 天）
| 广告系列 | 花费 | 转化次数 | 每次转化费用（CPA） | 状态 |
|----------|------|----------|---------------------|------|
| 品牌词   | $5K  | 50       | $100                | ✅ 正常 |
| SDK Web  | $10K | 2        | $5K                 | ❌ 暂停 |

## 建议操作
1. **暂停**：SDK Web 广告系列（CPA 高达 $5K）
2. **提升预算**：品牌词广告系列（表现强劲）

故障排查

浏览器模式问题

• 无法查看数据：请确认用户处于正确的账户（右上角账户选择器）
• 加载缓慢：Google Ads UI 较为沉重；请等待表格完全加载完成
• 会话已过期：用户需重新登录 ads.google.com

API 模式问题

• 身份验证失败：刷新 OAuth token，并检查 google-ads.yaml 配置
• 开发者令牌被拒绝：请确认该令牌已获批准（非测试模式）
• 客户 ID 错误：请使用不含短横线的 10 位数字 ID