google-ads

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Ads Skill

Google Ads 技能

Manage Google Ads accounts via API or browser automation.

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

Mode Selection

模式选择

Check which mode to use:

API Mode - If user has
```
google-ads.yaml
```
configured or
```
GOOGLE_ADS_*
```
env vars
Browser Mode - If user says "I don't have API access" or just wants quick checks

bash

undefined

检查应使用的模式：

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

bash

undefined

Check for API config

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


If no config found, ask: "Do you have Google Ads API credentials, or should I use browser automation?"

---

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


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

---

Browser Automation Mode (Universal)

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

Requirements: User logged into ads.google.com in browser

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

Setup

设置步骤

User opens ads.google.com and logs in
User clicks Clawdbot Browser Relay toolbar icon (badge ON)
Use
```
browser
```
tool with
```
profile="chrome"
```

用户打开ads.google.com并登录
用户点击Clawdbot Browser Relay工具栏图标（标记为开启状态）
使用
```
browser
```
工具，设置
```
profile="chrome"
```

Common Workflows

常见工作流程

Get Campaign Performance

获取广告系列效果数据

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. 导航至：ads.google.com/aw/campaigns
2. 设置日期范围（右上角日期选择器）
3. 对广告系列表格进行快照
4. 解析内容：广告系列、状态、预算、花费、转化次数、单次转化成本

Find Zero-Conversion Keywords (Wasted Spend)

查找无转化关键词（无效支出）

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. 导航至：ads.google.com/aw/keywords
2. 点击“添加筛选条件” → 转化次数 → 小于 → 1
3. 点击“添加筛选条件” → 花费 → 大于 → [阈值，例如$500]
4. 按花费从高到低排序
5. 对表格进行快照以分析

Pause Keywords/Campaigns

暂停关键词/广告系列

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

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

Download Reports

下载报告

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

For detailed browser selectors: See

references/browser-workflows.md

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

如需详细的浏览器选择器： 请查看

references/browser-workflows.md

API Mode (Power Users)

API模式（高级用户）

Requirements: Google Ads API developer token + OAuth credentials

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

Setup Check

设置检查

bash

undefined

bash

undefined

Verify google-ads SDK

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

Check config

cat ~/.google-ads.yaml

undefined

cat ~/.google-ads.yaml

undefined

Common Operations

常见操作

Query Campaign Performance

查询广告系列效果数据

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

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)

Find Zero-Conversion Keywords

查找无转化关键词

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

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
"""

Pause Keywords

暂停关键词

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)

For full API reference: See

references/api-setup.md

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

Audit Checklist

审计检查清单

Quick health check for any Google Ads account:

Check	Browser Path	What to Look For
Zero-conv keywords	Keywords → Filter: Conv<1, Cost>$500	Wasted spend
Empty ad groups	Ad Groups → Filter: Ads=0	No creative running
Policy violations	Campaigns → Status column	Yellow warning icons
Optimization Score	Overview page (top right)	Below 70% = action needed
Conversion tracking	Tools → Conversions	Inactive/no recent data

针对任意Google Ads账户的快速健康检查：

检查项	浏览器路径	检查要点
无转化关键词	关键词 → 筛选条件：转化次数<1，花费>$500	无效支出
空广告组	广告组 → 筛选条件：广告数量=0	无创意在投
政策违规	广告系列 → 状态列	黄色警告图标
优化得分	概览页面（右上角）	低于70% = 需要采取行动
转化追踪	工具 → 转化	未激活/无近期数据

Output Formats

输出格式

When reporting findings, use tables:

markdown

undefined

报告结果时，请使用表格：

markdown

undefined

Campaign Performance (Last 30 Days)

广告系列效果数据（过去30天）

Campaign	Cost	Conv	CPA	Status
Branded	$5K	50	$100	✅ Good
SDK Web	$10K	2	$5K	❌ Pause

广告系列	花费	转化次数	单次转化成本	状态
品牌广告系列	$5000	50	$100	✅ 表现良好
SDK推广广告系列	$10000	2	$5000	❌ 建议暂停

Recommended Actions

建议操作

PAUSE: SDK Web campaign ($5K CPA)
INCREASE: Branded budget (strong performer)

---

暂停：SDK推广广告系列（单次转化成本$5000）
增加预算：品牌广告系列（表现优异）

---

Troubleshooting

故障排除

Browser Mode Issues

浏览器模式问题

Can't see data: Check user is on correct account (top right account selector)
Slow loading: Google Ads UI is heavy; wait for tables to fully load
Session expired: User needs to re-login to ads.google.com

无法查看数据：检查用户是否处于正确的账户（右上角账户选择器）
加载缓慢：Google Ads界面较复杂；等待表格完全加载
会话过期：用户需要重新登录ads.google.com

API Mode Issues

API模式问题

Authentication failed: Refresh OAuth token, check
```
google-ads.yaml
```
Developer token rejected: Ensure token is approved (not test mode)
Customer ID error: Use 10-digit ID without dashes
proto-plus CopyFrom errors: Assign directly (e.g.,
```
operation.create = obj
```
) instead of
```
CopyFrom
```
on create fields
contains_eu_political_advertising required: Set to integer
```
0/1
```
(not boolean)
RSA text too long: Descriptions must be ≤ 90 chars

认证失败：刷新OAuth令牌，检查
```
google-ads.yaml
```
配置
开发者令牌被拒绝：确保令牌已获批（非测试模式）
客户ID错误：使用不带连字符的10位ID
proto-plus CopyFrom错误：直接赋值（例如
```
operation.create = obj
```
），而非在创建字段上使用
```
CopyFrom
```
需要设置contains_eu_political_advertising：设置为整数
```
0/1
```
（而非布尔值）
RSA文本过长：描述内容必须≤90个字符