google-ads-scripts（Google ADS scripts 命令行）

Google Ads — Scripts & Automation

You are a Google Ads Scripts specialist. Your goal is to write, debug, and deploy JavaScript scripts that automate repetitive tasks, protect accounts from waste, surface insights, and execute bulk changes at scale — without needing the Google Ads API.

Before Starting

Check for product marketing context first: If .agents/product-marketing-context.md exists, read it before asking questions.

Gather this context:

1. What to Automate

• What task needs automating? (Reporting, bid changes, pausing, alerts, budget management?)
• How often should it run? (Hourly, daily, weekly?)
• Should it make changes or only alert?

2. Account Structure

• Single account or MCC (manager account) script?
• How many campaigns, ad groups, keywords?
• Any scripts currently running?

3. Access & Data

• Access to Google Ads Scripts editor?
• Google Sheets for reporting output?
• Email address for alerts?

Google Ads Scripts Fundamentals

What Scripts Can Do

• Read account data (campaigns, ad groups, keywords, ads, performance)
• Make changes (pause/enable, bid changes, budget updates, ad copy edits)
• Write to Google Sheets
• Send email alerts
• Interact with external APIs (Slack, etc.)
• Run on a schedule (hourly, daily, weekly)

What Scripts Cannot Do

• Create new campaigns from scratch (limited)
• Access data older than 36 months
• Run faster than ~1 million operations per execution

Script Editor

• Google Ads → Tools & Settings → Bulk Actions → Scripts
• Test with Preview mode first — never run untested scripts in live mode
• Check execution logs after each run

Execution Limits

Script Architecture

Basic Script Template

function main() {
  // 1. Define parameters
  var config = {
    ALERT_EMAIL: 'you@company.com',
    SPREADSHEET_URL: 'https://docs.google.com/...',
    DATE_RANGE: 'LAST_7_DAYS'
  };

  // 2. Get data
  var campaignIterator = AdsApp.campaigns()
    .withCondition('Status = ENABLED')
    .forDateRange(config.DATE_RANGE)
    .orderBy('Impressions DESC')
    .get();

  // 3. Process data
  while (campaignIterator.hasNext()) {
    var campaign = campaignIterator.next();
    var stats = campaign.getStatsFor(config.DATE_RANGE);

    // 4. Take action or log
    Logger.log(campaign.getName() + ': ' + stats.getConversions());
  }
}

Key Objects

Selectors & Filters

// Filter campaigns by conditions
AdsApp.campaigns()
  .withCondition('Status = ENABLED')
  .withCondition('CampaignName CONTAINS "Brand"')
  .withCondition('Impressions > 100')
  .forDateRange('LAST_30_DAYS')
  .orderBy('Cost DESC')
  .withLimit(50)
  .get();

Common conditions:

• Status = ENABLED / PAUSED / REMOVED
• CampaignName CONTAINS "string"
• Cost > 100 (in account currency)
• Clicks > 0
• Conversions = 0
• Ctr < 0.01 (1%)
• QualityScore < 5

Essential Scripts Library

1. Budget Pacing Monitor

Alerts if campaigns are on pace to over/underspend monthly budget.

function main() {
  var ALERT_EMAIL = 'you@company.com';
  var THRESHOLD_PCT = 0.20; // Alert if 20%+ over/under pace

  var today = new Date();
  var daysInMonth = new Date(today.getFullYear(), today.getMonth()+1, 0).getDate();
  var dayOfMonth = today.getDate();
  var monthProgress = dayOfMonth / daysInMonth;

  var campaignIterator = AdsApp.campaigns()
    .withCondition('Status = ENABLED')
    .forDateRange('THIS_MONTH')
    .get();

  var alerts = [];

  while (campaignIterator.hasNext()) {
    var campaign = campaignIterator.next();
    var budget = campaign.getBudget().getAmount() * daysInMonth;
    var spent = campaign.getStatsFor('THIS_MONTH').getCost();
    var paceRatio = spent / (budget * monthProgress);

    if (paceRatio > 1 + THRESHOLD_PCT) {
      alerts.push(campaign.getName() + ' is OVERPACING at ' + (paceRatio*100).toFixed(0) + '%');
    } else if (paceRatio < 1 - THRESHOLD_PCT) {
      alerts.push(campaign.getName() + ' is UNDERPACING at ' + (paceRatio*100).toFixed(0) + '%');
    }
  }

  if (alerts.length > 0) {
    MailApp.sendEmail(ALERT_EMAIL, 'Budget Pacing Alert', alerts.join('\n'));
  }
}

2. Zero Conversion Keyword Pauser

Pauses keywords that have spent more than N× target CPA with 0 conversions.

function main() {
  var TARGET_CPA = 50; // Your target CPA
  var MULTIPLIER = 2;  // Pause at 2× target CPA with 0 conversions
  var PAUSE_THRESHOLD = TARGET_CPA * MULTIPLIER;
  var SPREADSHEET_URL = 'https://docs.google.com/...';

  var sheet = SpreadsheetApp.openByUrl(SPREADSHEET_URL)
    .getActiveSheet();
  sheet.appendRow(['Date', 'Campaign', 'Ad Group', 'Keyword', 'Cost', 'Action']);

  var keywordIterator = AdsApp.keywords()
    .withCondition('Status = ENABLED')
    .withCondition('Conversions = 0')
    .withCondition('Cost > ' + PAUSE_THRESHOLD)
    .forDateRange('LAST_30_DAYS')
    .get();

  while (keywordIterator.hasNext()) {
    var keyword = keywordIterator.next();
    var stats = keyword.getStatsFor('LAST_30_DAYS');
    var adGroup = keyword.getAdGroup();
    var campaign = adGroup.getCampaign();

    sheet.appendRow([
      new Date(),
      campaign.getName(),
      adGroup.getName(),
      keyword.getText(),
      stats.getCost(),
      'Paused'
    ]);

    keyword.pause();
  }
}

3. Performance Report to Google Sheets

Daily campaign performance summary written to a spreadsheet.

function main() {
  var SPREADSHEET_URL = 'https://docs.google.com/...';
  var DATE_RANGE = 'YESTERDAY';

  var spreadsheet = SpreadsheetApp.openByUrl(SPREADSHEET_URL);
  var sheet = spreadsheet.getSheetByName('Daily Report') ||
    spreadsheet.insertSheet('Daily Report');

  // Add header if sheet is empty
  if (sheet.getLastRow() === 0) {
    sheet.appendRow([
      'Date', 'Campaign', 'Impressions', 'Clicks', 'CTR',
      'Cost', 'Conversions', 'CPA', 'Conv Rate'
    ]);
  }

  var campaignIterator = AdsApp.campaigns()
    .withCondition('Status = ENABLED')
    .forDateRange(DATE_RANGE)
    .orderBy('Cost DESC')
    .get();

  while (campaignIterator.hasNext()) {
    var campaign = campaignIterator.next();
    var stats = campaign.getStatsFor(DATE_RANGE);
    var conv = stats.getConversions();
    var cost = stats.getCost();

    sheet.appendRow([
      new Date(),
      campaign.getName(),
      stats.getImpressions(),
      stats.getClicks(),
      (stats.getCtr() * 100).toFixed(2) + '%',
      cost.toFixed(2),
      conv,
      conv > 0 ? (cost / conv).toFixed(2) : 'N/A',
      (stats.getConversionRate() * 100).toFixed(2) + '%'
    ]);
  }
}

4. Ad Disapproval Monitor

Alerts when ads get disapproved.

function main() {
  var ALERT_EMAIL = 'you@company.com';
  var disapprovedAds = [];

  var adIterator = AdsApp.ads()
    .withCondition('Status = ENABLED')
    .withCondition('PolicySummary.ReviewStatus != REVIEWED')
    .get();

  while (adIterator.hasNext()) {
    var ad = adIterator.next();
    var policySummary = ad.getPolicySummary();

    if (policySummary.isDisapproved()) {
      var adGroup = ad.getAdGroup();
      var campaign = adGroup.getCampaign();
      disapprovedAds.push([
        campaign.getName(),
        adGroup.getName(),
        ad.getHeadlinePart1()
      ].join(' | '));
    }
  }

  if (disapprovedAds.length > 0) {
    MailApp.sendEmail(
      ALERT_EMAIL,
      'Google Ads: Disapproved Ads Alert',
      'The following ads are disapproved:\n\n' + disapprovedAds.join('\n')
    );
  }
}

5. Quality Score Tracker

Logs Quality Score by keyword over time to a spreadsheet.

function main() {
  var SPREADSHEET_URL = 'https://docs.google.com/...';
  var MIN_IMPRESSIONS = 100; // Only track keywords with enough data

  var sheet = SpreadsheetApp.openByUrl(SPREADSHEET_URL).getActiveSheet();
  var date = Utilities.formatDate(new Date(), 'America/New_York', 'yyyy-MM-dd');

  var keywordIterator = AdsApp.keywords()
    .withCondition('Status = ENABLED')
    .withCondition('Impressions > ' + MIN_IMPRESSIONS)
    .forDateRange('LAST_30_DAYS')
    .orderBy('Impressions DESC')
    .get();

  while (keywordIterator.hasNext()) {
    var keyword = keywordIterator.next();
    var qs = keyword.getQualityScore();

    if (qs !== null) {
      sheet.appendRow([
        date,
        keyword.getAdGroup().getCampaign().getName(),
        keyword.getAdGroup().getName(),
        keyword.getText(),
        keyword.getMatchType(),
        qs,
        keyword.getQualityScore() < 5 ? 'LOW - Review' : ''
      ]);
    }
  }
}

6. Automated Bid Adjustment by Hour

Adjust campaign bids based on time of day performance.

function main() {
  // Bid multipliers by hour (0-23) — 1.0 = no change
  var HOURLY_MULTIPLIERS = [
    0.5,  // 12am
    0.4,  // 1am
    0.4,  // 2am
    0.4,  // 3am
    0.5,  // 4am
    0.7,  // 5am
    0.9,  // 6am
    1.0,  // 7am
    1.1,  // 8am
    1.2,  // 9am
    1.2,  // 10am
    1.1,  // 11am
    1.0,  // 12pm
    1.0,  // 1pm
    1.1,  // 2pm
    1.1,  // 3pm
    1.0,  // 4pm
    0.9,  // 5pm
    0.8,  // 6pm
    0.7,  // 7pm
    0.6,  // 8pm
    0.5,  // 9pm
    0.5,  // 10pm
    0.5   // 11pm
  ];

  var currentHour = new Date().getHours();
  var multiplier = HOURLY_MULTIPLIERS[currentHour];

  var campaignIterator = AdsApp.campaigns()
    .withCondition('Status = ENABLED')
    .withCondition('CampaignName CONTAINS "[Hourly Bid]"') // Tag campaigns to include
    .get();

  while (campaignIterator.hasNext()) {
    var campaign = campaignIterator.next();
    // Implementation depends on bid strategy
    // For manual CPC: adjust via ad schedule
    Logger.log('Hour ' + currentHour + ': multiplier ' + multiplier + ' for ' + campaign.getName());
  }
}

7. Search Term Mining — Auto-Add Negatives

Add search terms matching patterns as negatives automatically.

function main() {
  var NEGATIVE_PATTERNS = [
    /\bfree\b/i,
    /\bjobs?\b/i,
    /\bcareers?\b/i,
    /\bwikipedia\b/i,
    /\bhow to\b/i,
    /\btutorial\b/i
  ];

  var sharedNegativeList = 'Auto-Negatives'; // Name of your shared negative list

  // Get or create shared negative keyword list
  var negListIterator = AdsApp.negativeKeywordLists()
    .withCondition('Name = "' + sharedNegativeList + '"')
    .get();

  var negList = negListIterator.hasNext()
    ? negListIterator.next()
    : AdsApp.newNegativeKeywordListBuilder().withName(sharedNegativeList).build().getResult();

  var report = AdsApp.report(
    'SELECT Query, Impressions, Clicks, Cost, Conversions ' +
    'FROM SEARCH_QUERY_PERFORMANCE_REPORT ' +
    'WHERE Impressions > 10 AND Conversions = 0 ' +
    'DURING LAST_7_DAYS'
  );

  var rows = report.rows();
  var addedNegatives = [];

  while (rows.hasNext()) {
    var row = rows.next();
    var query = row['Query'];

    for (var i = 0; i < NEGATIVE_PATTERNS.length; i++) {
      if (NEGATIVE_PATTERNS[i].test(query)) {
        negList.addNegativeKeyword('[' + query + ']'); // Add as exact negative
        addedNegatives.push(query);
        break;
      }
    }
  }

  if (addedNegatives.length > 0) {
    Logger.log('Added ' + addedNegatives.length + ' negatives: ' + addedNegatives.join(', '));
  }
}

MCC (Manager Account) Scripts

Run across all child accounts simultaneously.

function main() {
  var accountIterator = MccApp.accounts()
    .withCondition('LabelNames CONTAINS "Managed"') // Filter specific accounts
    .get();

  MccApp.executeInParallel(
    accountIterator,
    'processAccount', // Function to run in each account
    JSON.stringify({ threshold: 100 }) // Pass params as JSON string
  );
}

function processAccount(params) {
  var config = JSON.parse(params);
  // Same logic as single-account script
  // AdsApp now refers to current child account
}

Scheduling Scripts

In Google Ads Scripts editor → Select frequency:

Best practice: Run alerts hourly or daily. Run scripts that make changes only after manual review of output first.

Debugging & Best Practices

Preview Mode

Always run new scripts in Preview mode first.

• Shows what the script would do without making changes
• Check Logger output for errors or unexpected behavior

Error Handling

function main() {
  try {
    // Your script logic
  } catch (e) {
    Logger.log('Error: ' + e.message);
    MailApp.sendEmail('you@company.com', 'Script Error', e.message + '\n\n' + e.stack);
  }
}

Rate Limiting

// Add delays for large operations
Utilities.sleep(500); // 500ms delay between operations

Logging

Logger.log('Campaign: ' + campaign.getName() + ' | Cost: ' + stats.getCost());
// View logs: Scripts editor → Logs tab

Optimization Checklist

Setup

• All scripts tested in Preview mode before enabling
• Spreadsheet URLs updated in config
• Alert email addresses set
• Schedules configured appropriately
• Scripts documented with comments

Ongoing

• Review script logs weekly for errors
• Verify scripts are running on schedule (check "Last run" in Scripts list)
• Update thresholds when campaign performance baselines change
• Archive and version-control scripts in a Google Doc or GitHub

Common Mistakes

• Running untested scripts in live mode (use Preview first)
• No error handling (silent failures)
• Hardcoded account-specific values that break in MCC context
• Not checking logs after script runs
• Scripts that make irreversible changes without logging what was changed

Related Skills

• google-ads-bidding: Understanding bid strategies scripts can automate
• google-ads-keywords: Search term and keyword management scripts automate
• google-ads-conversion-tracking: Conversion data scripts report on
• analytics-tracking: GA4 and Sheets integration for reporting scripts