Multi-Campaign Google Ads Budget Pacing & Governance System

Generated Artifacts Preview

/**
 * ============================================================================
 * Google Ads Governance Automation: Monthly Budget Pacing & Overspend Shield
 * Strategy: google-ads-budget-pacing-governance
 * Author: Gordon Geraghty - Head of Performance Media (https://gordongeraghty.com)
 * Generated: 
 * ============================================================================
 */

const CONFIG = {
  ACCOUNT_ID: "123-456-7890",
  WEBHOOK_CHANNEL: "slack",
  WEBHOOK_URL: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
  NOTIFICATION_EMAIL: "{{EMAIL_ADDRESS}}",
  DRY_RUN: false,
  ANOMALY_MULTIPLIER: 2.5,
  MONTHLY_BUDGET_LIMIT: 15000,
  URL_BATCH_SIZE: 50,
  GAQL_QUERY: "SELECT campaign_budget.id, campaign_budget.name, campaign_budget.amount_micros, metrics.cost_micros FROM campaign_budget WHERE campaign_budget.status = 'ENABLED' AND segments.date DURING THIS_MONTH"
};

function main() {
  Logger.log('Starting Google Ads Governance Script: ' + 'Monthly Budget Pacing & Overspend Shield');
  Logger.log('Account ID: ' + CONFIG.ACCOUNT_ID + ' | Dry Run: ' + CONFIG.DRY_RUN);

  try {
    const report = AdsApp.report(CONFIG.GAQL_QUERY);
    const rows = report.rows();
    const alertFindings = [];

    while (rows.hasNext()) {
      const row = rows.next();
      if (evaluateRowCondition(row)) {
        alertFindings.push(formatFinding(row));
      }
    }

    Logger.log('Total issues / anomalies detected: ' + alertFindings.length);

    if (alertFindings.length > 0) {
      dispatchAlert(alertFindings);
    } else {
      Logger.log('All checks passed within normal thresholds.');
    }
  } catch (err) {
    Logger.log('Error executing governance script: ' + err.toString());
  }
}

function evaluateRowCondition(row) {
  const cost = parseFloat(row['metrics.cost_micros'] || 0) / 1000000;
  return cost > (CONFIG.MONTHLY_BUDGET_LIMIT * 0.9);
}

function formatFinding(row) {
  return {
    campaign: row['campaign.name'] || 'Unknown Campaign',
    detail: JSON.stringify(row),
    timestamp: new Date().toISOString()
  };
}

function dispatchAlert(findings) {
  if (CONFIG.DRY_RUN) {
    Logger.log('[DRY-RUN MODE] Alerts logged to console only (no webhook dispatched).');
    Logger.log(JSON.stringify(findings, null, 2));
    return;
  }

  const payload = buildWebhookPayload(findings);

  if (CONFIG.WEBHOOK_CHANNEL === 'email') {
    MailApp.sendEmail({
      to: CONFIG.NOTIFICATION_EMAIL,
      subject: '[ALERT] Google Ads Governance: ' + 'Monthly Budget Pacing & Overspend Shield',
      body: 'Issues detected:

' + JSON.stringify(findings, null, 2)
    });
    Logger.log('Dispatched alert email to: ' + CONFIG.NOTIFICATION_EMAIL);
    return;
  }

  if (CONFIG.WEBHOOK_URL && CONFIG.WEBHOOK_URL.startsWith('http')) {
    const options = {
      method: 'post',
      contentType: 'application/json',
      payload: JSON.stringify(payload),
      muteHttpExceptions: true
    };
    const response = UrlFetchApp.fetch(CONFIG.WEBHOOK_URL, options);
    Logger.log('Webhook dispatched to ' + CONFIG.WEBHOOK_CHANNEL + '. Status: ' + response.getResponseCode());
  } else {
    Logger.log('Warning: No valid WEBHOOK_URL configured.');
  }
}

function buildWebhookPayload(findings) {
  return {
  "text": "*Budget Pacing Alert: Campaign High-Volume Shopping* [CRITICAL]",
  "attachments": [
    {
      "color": "#e01e5a",
      "title": "Budget Pacing Alert: Campaign High-Volume Shopping",
      "text": "Campaign is projected to exceed its monthly cap of $15000 before month end.",
      "fields": [
        {
          "title": "Month-to-Date Spend ($)",
          "value": "11250.0",
          "short": true
        },
        {
          "title": "Monthly Cap ($)",
          "value": "15000",
          "short": true
        },
        {
          "title": "Projected Overspend (%)",
          "value": "18.4",
          "short": true
        },
        {
          "title": "Account ID",
          "value": "123-456-7890",
          "short": true
        }
      ],
      "footer": "Gordon Geraghty Ads Governance Automation",
      "ts": 1748736000
    }
  ]
};
}