google-ads-scripts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Ads Scripts

Overview

概述

This skill provides comprehensive guidance for developing Google Ads Scripts using the AdsApp API. Google Ads Scripts enable automation of campaign management, bid optimization, performance reporting, and bulk operations through JavaScript code that runs directly in the Google Ads editor.

本技能提供使用AdsApp API开发Google Ads Script的全面指南。Google Ads Script允许通过直接在Google Ads编辑器中运行的JavaScript代码，实现广告系列管理、出价优化、效果报告及批量操作的自动化。

When to Use This Skill

适用场景

Invoke this skill when:

Automating Google Ads campaign management operations
Managing keywords and adjusting bids programmatically
Creating performance reports and dashboards
Implementing automated rules for campaign optimization
Optimizing ad spend based on ROAS or CPA targets
Working with campaign budgets and spend limits
Monitoring quality scores and pausing low-performers
Tracking conversions and adjusting strategies
Building bulk operations for large-scale account management
Implementing time-based or performance-based automation
Debugging Google Ads Script code or API issues

在以下场景中调用本技能：

自动化Google Ads广告系列管理操作
程序化管理关键词并调整出价
创建效果报告与数据看板
实施广告系列优化的自动化规则
基于ROAS或CPA目标优化广告支出
管理广告系列预算与支出限额
监测质量得分并暂停低效果对象
追踪转化数据并调整策略
构建大规模账户管理的批量操作
实现基于时间或效果的自动化逻辑
调试Google Ads Script代码或API相关问题

Core Capabilities

核心功能

1. Campaign Operations

1. 广告系列操作

Manage campaigns programmatically including creation, modification, status changes, and bulk updates. The AdsApp.campaigns() selector provides filtering and iteration patterns.

Common operations:

Get campaigns with conditions (status, budget, name patterns)
Modify campaign properties (name, budget, dates, status)
Apply labels for organization
Pause/enable campaigns based on performance criteria

程序化管理广告系列，包括创建、修改、状态变更及批量更新。AdsApp.campaigns()选择器提供筛选与遍历模式。

常见操作：

根据条件（状态、预算、名称模式）获取广告系列
修改广告系列属性（名称、预算、日期、状态）
应用标签进行分类管理
根据效果指标暂停/启用广告系列

2. Keyword & Bid Management

2. 关键词与出价管理

Automate keyword targeting and bid adjustments based on performance metrics.

Common operations:

Get keywords with quality score filtering
Adjust max CPC bids based on ROAS/CPA targets
Add/remove negative keywords
Monitor keyword-level conversions
Implement bid optimization algorithms

基于效果指标自动化关键词定向与出价调整。

常见操作：

按质量得分筛选关键词
根据ROAS/CPA目标调整最高CPC出价
添加/移除否定关键词
监测关键词层级的转化数据
实现出价优化算法

3. Performance Reporting

3. 效果报告

Generate custom reports using campaign, ad group, keyword, and ad statistics.

Common operations:

Retrieve metrics for custom date ranges
Calculate derived metrics (CTR, CPC, conversion rate)
Export data to Google Sheets
Create automated dashboards
Monitor KPIs and trigger alerts

利用广告系列、广告组、关键词及广告的统计数据生成自定义报告。

常见操作：

获取自定义时间范围的指标数据
计算衍生指标（点击率CTR、平均点击成本CPC、转化率）
将数据导出至Google Sheets
创建自动化数据看板
监测关键绩效指标（KPI）并触发告警

4. Budget Management

4. 预算管理

Control spending and allocate budgets across campaigns.

Common operations:

Get/set daily campaign budgets
Monitor spend against thresholds
Pause campaigns when budget limits reached
Distribute budgets based on performance

控制支出并在广告系列间分配预算。

常见操作：

获取/设置广告系列每日预算
监测支出是否超过阈值
预算限额达标时暂停广告系列
根据效果分配预算

5. Automated Rules & Optimization

5. 自动化规则与优化

Build intelligence into campaign management with automated decision-making.

Common operations:

Pause low-performing keywords (low QS, high CPC, no conversions)
Increase bids for high-performers
Adjust budgets based on day-of-week patterns
Implement custom bidding strategies

为广告系列管理加入智能自动化决策逻辑。

常见操作：

暂停低效果关键词（低质量得分、高CPC、无转化）
为高效果对象提高出价
根据周度模式调整预算
实现自定义出价策略

6. Error Handling & Resilience

6. 错误处理与韧性保障

Implement robust error handling to manage API limits, quota issues, and runtime errors.

Key patterns:

Try-catch blocks for error handling
Null checks for optional properties
Logging to sheets for audit trails
Rate limiting awareness (30-minute execution limit)

实现健壮的错误处理机制，以管理API限制、配额问题及运行时错误。

核心模式：

使用try-catch块处理错误
对可选属性进行空值检查
将日志记录到Sheets作为审计轨迹
关注速率限制（30分钟执行时限）

Quick Start Examples

快速入门示例

Example 1: Pause Low-Quality Keywords

示例1：暂停低质量关键词

javascript

function pauseLowQualityKeywords() {
  const keywords = AdsApp.keywords()
    .withCondition('keyword.status = ENABLED')
    .withCondition('keyword.quality_info.quality_score < 4')
    .withCondition('keyword.metrics.cost > 100000000')  // >100 spend
    .get();

  let count = 0;
  while (keywords.hasNext()) {
    const keyword = keywords.next();
    keyword.pause();
    count++;
  }

  Logger.log(`Paused ${count} low-quality keywords`);
}

javascript

function pauseLowQualityKeywords() {
  const keywords = AdsApp.keywords()
    .withCondition('keyword.status = ENABLED')
    .withCondition('keyword.quality_info.quality_score < 4')
    .withCondition('keyword.metrics.cost > 100000000')  // >100 spend
    .get();

  let count = 0;
  while (keywords.hasNext()) {
    const keyword = keywords.next();
    keyword.pause();
    count++;
  }

  Logger.log(`Paused ${count} low-quality keywords`);
}

Example 2: Optimize Bids Based on ROAS

示例2：基于ROAS优化出价

javascript

function optimizeBidsByROAS() {
  const TARGET_ROAS = 3.0;  // 300%

  const keywords = AdsApp.keywords()
    .withCondition('keyword.status = ENABLED')
    .withCondition('keyword.metrics.conversions > 5')  // Min conversions
    .get();

  while (keywords.hasNext()) {
    const keyword = keywords.next();
    const stats = keyword.getStatsFor('LAST_30_DAYS');
    const roas = stats.getReturnOnAdSpend();
    const currentBid = keyword.getMaxCpc();

    if (roas > TARGET_ROAS) {
      // Increase bid by 10%
      keyword.setMaxCpc(Math.floor(currentBid * 1.1));
    } else if (roas < TARGET_ROAS * 0.7) {
      // Decrease bid by 5%
      keyword.setMaxCpc(Math.floor(currentBid * 0.95));
    }
  }
}

javascript

function optimizeBidsByROAS() {
  const TARGET_ROAS = 3.0;  // 300%

  const keywords = AdsApp.keywords()
    .withCondition('keyword.status = ENABLED')
    .withCondition('keyword.metrics.conversions > 5')  // Min conversions
    .get();

  while (keywords.hasNext()) {
    const keyword = keywords.next();
    const stats = keyword.getStatsFor('LAST_30_DAYS');
    const roas = stats.getReturnOnAdSpend();
    const currentBid = keyword.getMaxCpc();

    if (roas > TARGET_ROAS) {
      // Increase bid by 10%
      keyword.setMaxCpc(Math.floor(currentBid * 1.1));
    } else if (roas < TARGET_ROAS * 0.7) {
      // Decrease bid by 5%
      keyword.setMaxCpc(Math.floor(currentBid * 0.95));
    }
  }
}

Example 3: Export Campaign Performance to Sheets

示例3：导出广告系列效果至Sheets

javascript

function exportCampaignPerformance() {
  const campaigns = AdsApp.campaigns()
    .withCondition('campaign.status = ENABLED')
    .orderBy('campaign.metrics.cost DESC')
    .get();

  const report = [['Campaign', 'Clicks', 'Cost', 'Conversions', 'CPC', 'ROAS']];

  while (campaigns.hasNext()) {
    const campaign = campaigns.next();
    const stats = campaign.getStatsFor('LAST_30_DAYS');

    report.push([
      campaign.getName(),
      stats.getClicks(),
      stats.getCost() / 1000000,  // Convert from micros
      stats.getConversions(),
      stats.getAverageCpc() / 1000000,
      stats.getReturnOnAdSpend()
    ]);
  }

  // Write to Google Sheets
  const ss = SpreadsheetApp.openById('YOUR_SHEET_ID');
  const sheet = ss.getSheetByName('Campaign Report') || ss.insertSheet('Campaign Report');
  sheet.clear();
  sheet.getRange(1, 1, report.length, report[0].length).setValues(report);
}

javascript

function exportCampaignPerformance() {
  const campaigns = AdsApp.campaigns()
    .withCondition('campaign.status = ENABLED')
    .orderBy('campaign.metrics.cost DESC')
    .get();

  const report = [['Campaign', 'Clicks', 'Cost', 'Conversions', 'CPC', 'ROAS']];

  while (campaigns.hasNext()) {
    const campaign = campaigns.next();
    const stats = campaign.getStatsFor('LAST_30_DAYS');

    report.push([
      campaign.getName(),
      stats.getClicks(),
      stats.getCost() / 1000000,  // Convert from micros
      stats.getConversions(),
      stats.getAverageCpc() / 1000000,
      stats.getReturnOnAdSpend()
    ]);
  }

  // Write to Google Sheets
  const ss = SpreadsheetApp.openById('YOUR_SHEET_ID');
  const sheet = ss.getSheetByName('Campaign Report') || ss.insertSheet('Campaign Report');
  sheet.clear();
  sheet.getRange(1, 1, report.length, report[0].length).setValues(report);
}

Working with References

参考文档使用

For comprehensive API documentation, code patterns, and detailed examples, see:

references/ads-api-reference.md - Complete AdsApp API reference including all selectors, methods, conditions, statistics, and enterprise patterns

The reference file contains:

Complete API hierarchy and object model
All selector patterns and conditions
Statistics methods and date ranges
Campaign, ad group, keyword, and ad operations
Bidding strategy implementation details
Performance reporting patterns
Budget management techniques
Advanced targeting options
Error handling patterns
Performance optimization strategies
Quotas and limits reference

如需完整的API文档、代码模式及详细示例，请参阅：

references/ads-api-reference.md - 完整的AdsApp API参考，包含所有选择器、方法、条件、统计指标及企业级实现模式

该参考文档包含：

完整的API层级与对象模型
所有选择器模式与条件
统计指标方法与时间范围
广告系列、广告组、关键词及广告操作
出价策略实现细节
效果报告模式
预算管理技巧
高级定向选项
错误处理模式
性能优化策略
配额与限制参考

Best Practices

最佳实践

1. Use Batch Operations

1. 使用批量操作

Avoid individual API calls in loops. Instead, collect entities and perform batch operations:

javascript

// ✅ Good - Batch collection
const keywords = AdsApp.keywords()
  .withCondition('keyword.quality_info.quality_score < 5')
  .get();

const toUpdate = [];
while (keywords.hasNext()) {
  toUpdate.push(keywords.next());
}

toUpdate.forEach(keyword => keyword.setMaxCpc(50000));

避免在循环中发起单个API调用，应先收集实体再执行批量操作：

javascript

// ✅ Good - Batch collection
const keywords = AdsApp.keywords()
  .withCondition('keyword.quality_info.quality_score < 5')
  .get();

const toUpdate = [];
while (keywords.hasNext()) {
  toUpdate.push(keywords.next());
}

toUpdate.forEach(keyword => keyword.setMaxCpc(50000));

2. Filter with Conditions

2. 使用条件筛选

Use

.withCondition()

to filter at the API level rather than in JavaScript:

javascript

// ✅ Good - API-level filtering
const campaigns = AdsApp.campaigns()
  .withCondition('campaign.status = ENABLED')
  .withCondition('campaign.budget_information.budget_amount > 100000000')
  .get();

使用

.withCondition()

在API层面进行筛选，而非在JavaScript中处理：

javascript

// ✅ Good - API-level filtering
const campaigns = AdsApp.campaigns()
  .withCondition('campaign.status = ENABLED')
  .withCondition('campaign.budget_information.budget_amount > 100000000')
  .get();

3. Handle Errors Gracefully

3. 优雅处理错误

Always wrap operations in try-catch blocks and log errors:

javascript

function safeOperation() {
  try {
    // Operation code
  } catch (error) {
    Logger.log('Error: ' + error.message);
    Logger.log('Stack: ' + error.stack);

    // Optionally email alert
    MailApp.sendEmail(
      Session.getEffectiveUser().getEmail(),
      'Ads Script Error',
      error.message
    );
  }
}

始终将操作包裹在try-catch块中并记录错误：

javascript

function safeOperation() {
  try {
    // Operation code
  } catch (error) {
    Logger.log('Error: ' + error.message);
    Logger.log('Stack: ' + error.stack);

    // Optionally email alert
    MailApp.sendEmail(
      Session.getEffectiveUser().getEmail(),
      'Ads Script Error',
      error.message
    );
  }
}

4. Respect Execution Limits

4. 遵守执行限制

Scripts have a 30-minute execution timeout. For large accounts:

Limit result sets with
```
.withLimit()
```
Process in batches
Use early termination when needed

脚本存在30分钟的执行超时限制。对于大型账户：

使用
```
.withLimit()
```
限制结果集
分批处理数据
必要时提前终止执行

5. Convert Micros Correctly

5. 正确转换微货币单位

Google Ads API uses micros (1/1,000,000) for currency values:

javascript

const costMicros = stats.getCost();
const costCurrency = costMicros / 1000000;  // Convert to dollars/local currency

const bidCurrency = 5.00;  // $5.00
const bidMicros = bidCurrency * 1000000;  // 5000000 micros

Google Ads API使用微单位（1/1,000,000）表示货币值：

javascript

const costMicros = stats.getCost();
const costCurrency = costMicros / 1000000;  // Convert to dollars/local currency

const bidCurrency = 5.00;  // $5.00
const bidMicros = bidCurrency * 1000000;  // 5000000 micros

6. Log Operations for Auditing

6. 记录操作用于审计

Maintain audit trails by logging changes to Google Sheets:

javascript

function logChange(operation, entity, details) {
  const ss = SpreadsheetApp.openById('LOG_SHEET_ID');
  const sheet = ss.getSheetByName('Audit Log');
  sheet.appendRow([
    new Date(),
    operation,
    entity,
    JSON.stringify(details)
  ]);
}

通过将变更记录到Google Sheets来维护审计轨迹：

javascript

function logChange(operation, entity, details) {
  const ss = SpreadsheetApp.openById('LOG_SHEET_ID');
  const sheet = ss.getSheetByName('Audit Log');
  sheet.appendRow([
    new Date(),
    operation,
    entity,
    JSON.stringify(details)
  ]);
}

Integration with Other Skills

与其他技能集成

google-apps-script - Use for Google Sheets reporting, Gmail notifications, Drive file management, and trigger setup
ga4-measurement-protocol - Combine with GA4 for tracking script-triggered events
gtm-api - Coordinate with GTM configurations for holistic tracking

google-apps-script - 用于Google Sheets报告、Gmail通知、Drive文件管理及触发器设置
ga4-measurement-protocol - 与GA4集成以追踪脚本触发的事件
gtm-api - 与GTM配置协同实现全链路追踪

Common Patterns

常见模式

Pattern: Conditional Bid Adjustment

模式：条件式出价调整

javascript

function adjustBidsBasedOnDayOfWeek() {
  const today = new Date().getDay();  // 0 = Sunday, 6 = Saturday
  const isWeekend = today === 0 || today === 6;

  const campaigns = AdsApp.campaigns()
    .withCondition('campaign.status = ENABLED')
    .get();

  while (campaigns.hasNext()) {
    const campaign = campaigns.next();
    const budget = campaign.getBudget().getAmount();

    if (isWeekend) {
      campaign.getBudget().setAmount(budget * 1.2);  // +20% on weekends
    }
  }
}

javascript

function adjustBidsBasedOnDayOfWeek() {
  const today = new Date().getDay();  // 0 = Sunday, 6 = Saturday
  const isWeekend = today === 0 || today === 6;

  const campaigns = AdsApp.campaigns()
    .withCondition('campaign.status = ENABLED')
    .get();

  while (campaigns.hasNext()) {
    const campaign = campaigns.next();
    const budget = campaign.getBudget().getAmount();

    if (isWeekend) {
      campaign.getBudget().setAmount(budget * 1.2);  // +20% on weekends
    }
  }
}

Pattern: Quality Score Monitoring

模式：质量得分监测

javascript

function monitorQualityScores() {
  const threshold = 5;

  const lowQualityKeywords = AdsApp.keywords()
    .withCondition(`keyword.quality_info.quality_score < ${threshold}`)
    .withCondition('keyword.status = ENABLED')
    .orderBy('keyword.metrics.cost DESC')  // Most expensive first
    .withLimit(100)
    .get();

  const alerts = [];
  while (lowQualityKeywords.hasNext()) {
    const keyword = lowQualityKeywords.next();
    alerts.push({
      keyword: keyword.getText(),
      qualityScore: keyword.getQualityScore(),
      cost: keyword.getStatsFor('LAST_7_DAYS').getCost() / 1000000
    });
  }

  if (alerts.length > 0) {
    // Send email or log to sheet
    Logger.log(`${alerts.length} keywords with QS < ${threshold}`);
  }
}

javascript

function monitorQualityScores() {
  const threshold = 5;

  const lowQualityKeywords = AdsApp.keywords()
    .withCondition(`keyword.quality_info.quality_score < ${threshold}`)
    .withCondition('keyword.status = ENABLED')
    .orderBy('keyword.metrics.cost DESC')  // Most expensive first
    .withLimit(100)
    .get();

  const alerts = [];
  while (lowQualityKeywords.hasNext()) {
    const keyword = lowQualityKeywords.next();
    alerts.push({
      keyword: keyword.getText(),
      qualityScore: keyword.getQualityScore(),
      cost: keyword.getStatsFor('LAST_7_DAYS').getCost() / 1000000
    });
  }

  if (alerts.length > 0) {
    // Send email or log to sheet
    Logger.log(`${alerts.length} keywords with QS < ${threshold}`);
  }
}

Validation & Testing

验证与测试

Use the validation scripts in

scripts/

for pre-deployment checks:

scripts/validators.py - Validate campaign data, bid values, budget amounts before applying changes

使用

scripts/

目录下的验证脚本进行部署前检查：

scripts/validators.py - 在应用变更前验证广告系列数据、出价数值、预算金额

Troubleshooting

故障排除

Common Issues:

Execution timeout - Reduce scope with
```
.withLimit()
```
or process in batches
Quota exceeded - Reduce API call frequency, use cached data
Type errors - Remember micros conversion for currency values
Null values - Always check for null before accessing properties

Debug with Logger:

javascript

Logger.log('Debug info: ' + JSON.stringify(data));
// View logs: View > Logs in script editor

This skill provides production-ready patterns for Google Ads automation. Consult the comprehensive API reference for detailed method signatures and advanced use cases.

常见问题：

执行超时 - 使用
```
.withLimit()
```
缩小范围或分批处理
配额超限 - 降低API调用频率，使用缓存数据
类型错误 - 记住货币值的微单位转换
空值问题 - 访问属性前始终检查是否为空

使用Logger调试：

javascript

Logger.log('Debug info: ' + JSON.stringify(data));
// View logs: View > Logs in script editor

本技能提供可用于生产环境的Google Ads自动化模式。如需详细的方法签名及高级用例，请查阅完整的API参考文档。