介绍
# Google Ads Skill
通过 API 或浏览器自动化管理 Google Ads 账户。
## 模式选择
**检查使用哪种模式：**
1. **API 模式** - 如果用户配置了 `google-ads.yaml` 或设置了 `GOOGLE_ADS_*` 环境变量 2. **浏览器模式** - 如果用户说“我没有 API 访问权限”或只想进行快速检查
```bash # 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 工具栏图标（徽章为 ON） 3. 使用带有 `profile="chrome"` 的 `browser` 工具
### 常见工作流
#### 获取广告系列效果 ``` 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 凭证
### 设置检查 ```bash # Verify google-ads SDK python -c "from google.ads.googleads.client import GoogleAdsClient; print('OK')"
# Check config cat ~/.google-ads.yaml ```
### 常见操作
#### 查询广告系列效果 ```python 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) ```
#### 查找零转化关键词 ```python 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 """ ```
#### 暂停关键词 ```python 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 page (top right) | 低于 70% = 需要采取措施 | | 转化跟踪 | Tools → Conversions | 未激活/无近期数据 |
---
## 输出格式
报告发现时，请使用表格：
```markdown ## 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` - **开发者令牌被拒绝**：确保令牌已获批准（非测试模式） - **客户 ID 错误**：使用不带连字符的 10 位数字 ID