google-ads-scripts

Google Ads Scripts Overview Guidance for developing Google Ads Scripts using the AdsApp API. Automate campaign management, bid optimisation, performance reporting, and bulk operations through JavaScript running in the Google Ads editor. When to Use This Skill Automating campaign management or bulk operations Managing keywords and adjusting bids programmatically Creating performance reports or dashboards Implementing automated rules for campaign optimisation Optimising ad spend based on ROAS or CPA targets Monitoring quality scores, budgets, or conversions Debugging Google Ads Script code or API issues Core Capabilities 1. Campaign Operations Manage campaigns programmatically - creation, modification, status changes, bulk updates. Use AdsApp.campaigns() with conditions to filter by status, budget, name patterns, or type. Apply labels for organisation. 2. Keyword & Bid Management Automate keyword targeting and bid adjustments based on performance. Filter by quality score, adjust max CPC bids based on ROAS/CPA targets, add/remove negative keywords, and implement bid optimisation algorithms. 3. Performance Reporting Generate custom reports using campaign, ad group, keyword, and ad statistics. Retrieve metrics for custom date ranges, calculate derived metrics (CTR, CPC, conversion rate), and export data to Google Sheets. 4. Budget Management Control spending and allocate budgets across campaigns. Get/set daily campaign budgets, monitor spend against thresholds, pause campaigns when limits are reached, and distribute budgets based on performance. 5. Automated Rules & Optimisation Build intelligence into campaign management with automated decision-making. Pause low-performing keywords, increase bids for high-performers, adjust budgets based on day-of-week patterns. 6. Error Handling & Resilience Implement robust error handling for API limits, quota issues, and runtime errors. Use try-catch blocks, null checks, sheet-based logging for audit trails. Be aware of the 30-minute execution limit. Quick Start The most common pattern - pause keywords with low quality scores and high spend: function pauseLowQualityKeywords ( ) { const keywords = AdsApp . keywords ( ) . withCondition ( 'keyword.status = ENABLED' ) . withCondition ( 'keyword.quality_info.quality_score < 4' ) . withCondition ( 'keyword.metrics.cost > 100000000' ) . get ( ) ; let count = 0 ; while ( keywords . hasNext ( ) ) { keywords . next ( ) . pause ( ) ; count ++ ; } Logger . log ( Paused ${ count } low-quality keywords ) ; } Best Practices Batch operations - collect entities first, then process; avoid individual API calls in loops API-level filtering - use .withCondition() instead of filtering in JavaScript Error handling - wrap operations in try-catch, log errors to sheets or email Execution limits - use .withLimit() and batch processing for large accounts (30-min timeout) Micros conversion - currency values are in micros (divide by 1,000,000 for display) Audit logging - log all changes to Google Sheets with timestamps See references/best-practices.md for detailed code examples of each practice. 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 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 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 Use Logger.log() for debugging - view logs via View > Logs in the script editor. References Load these on demand for detailed documentation: references/ads-api-reference.md - Complete AdsApp API reference including selectors, methods, conditions, statistics, and enterprise patterns references/examples.md - Detailed code examples: pause low-quality keywords, optimise bids by ROAS, export campaign performance to Sheets references/best-practices.md - Best practices with code blocks: batch operations, API filtering, error handling, micros conversion, audit logging references/patterns.md - Reusable automation patterns: conditional bid adjustment, quality score monitoring