Google Ads 技能

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

模式选择

检查应使用哪种模式：

1. API 模式- 如果用户已配置`google-ads.yaml`或`GOOGLE_ADS_*`环境变量
2. 浏览器模式- 如果用户表示“我没有 API 访问权限”或只想进行快速检查

# Check for API config
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 工具栏图标（徽章需为开启状态）
3. 使用`browser`工具与profile="chrome"

常见工作流程

获取广告系列效果

1. Navigate to: ads.google.com/aw/campaigns
2. Set date range (top right date picker)
3. Snapshot the campaigns table
4. Parse: Campaign, Status, Budget, Cost, Conversions, Cost/Conv

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

1. Navigate to: ads.google.com/aw/keywords
2. Click "Add filter" → Conversions → Less than → 1
3. Click "Add filter" → Cost → Greater than → [threshold, e.g., $500]
4. Sort by Cost descending
5. Snapshot table for analysis

暂停关键词/广告系列

1. Navigate to keywords or campaigns view
2. Check boxes for items to pause
3. Click "Edit" dropdown → "Pause"
4. Confirm action

下载报告

1. Navigate to desired view (campaigns, keywords, etc.)
2. Click "Download" icon (top right of table)
3. Select format (CSV recommended)
4. File downloads to user's Downloads folder

如需详细的浏览器选择器：参见references/browser-workflows.md

API 模式（高级用户）

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

设置检查

# Verify google-ads SDK
python -c "from google.ads.googleads.client import GoogleAdsClient; print('OK')"

# Check config
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 账户的快速健康检查：

输出格式

报告发现时，请使用表格：

## 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 界面加载负担重；需等待表格完全加载
• 会话过期：用户需要重新登录 ads.google.com

API 模式问题

• 认证失败：刷新 OAuth 令牌，检查google-ads.yaml 配置文件
• 开发者令牌被拒绝：确保令牌已获批准（非测试模式）
• 客户 ID 错误：使用 10 位数字 ID，无需连字符