Update to Ad Superpowers

{
  "name": "google-ads-performance-max-optimizer",
  "description": "This skill should be used when the user asks to \"set up Performance Max\", \"optimize PMax campaigns\", \"configure audience signals\", \"choose search themes\", or mentions \"PMax asset group strategy\", \"channel performance breakdown\", or \"e-commerce vs lead gen PMax\". Do NOT use for: PMax audit scoring (use pmax-audit-checklist), PMax retail-specific optimization (use pmax-retail-optimizer), PMax vs Search cannibalization (use pmax-search-cannibalization-detector).",
  "included_files": [
    {
      "relative_path": "references/decision-trees.md",
      "size_in_bytes": 5218
    },
    {
      "relative_path": "references/detailed-reference.md",
      "size_in_bytes": 12039
    }
  ],
  "skill_md_contents": "---\nname: google-ads-performance-max-optimizer\ndescription: \"This skill should be used when the user asks to \\\"set up Performance Max\\\", \\\"optimize PMax campaigns\\\", \\\"configure audience signals\\\", \\\"choose search themes\\\", or mentions \\\"PMax asset group strategy\\\", \\\"channel performance breakdown\\\", or \\\"e-commerce vs lead gen PMax\\\". Do NOT use for: PMax audit scoring (use pmax-audit-checklist), PMax retail-specific optimization (use pmax-retail-optimizer), PMax vs Search cannibalization (use pmax-search-cannibalization-detector).\"\n---\n# Performance Max Optimizer\n\nComplete guide for setting up, optimizing and scaling Google Ads Performance Max campaigns for e-commerce and lead generation.\n\n\n\nSee [decision-trees.md](references/decision-trees.md) for details.\n\n\n\n\n\nSee [detailed-reference.md](references/detailed-reference.md) for details.\n\n\n\n\n\nSee [detailed-reference.md](references/detailed-reference.md) for details.\n\n\n\n## Audience Signals\n\n### Important Nuance: Signals != Targeting\n\n```\nCRUCIAL CONCEPT\n===================\n\nAudience Signals = HINTS for Google AI\nAudience Signals != Targeting restrictions\n\nGoogle WILL advertise outside your signals if it\nexpects better results. Signals accelerate\nthe learning phase and provide direction.\n\nGood Signals -> Faster optimization\nBad Signals -> Slower learning, but not a disaster\n```\n\n### Audience Signal Strategy\n\n```\nAUDIENCE SIGNAL LAYERING\n========================\n\nLAYER 1: First-Party Data (Highest value)\n------------------------------------------\n[ ] Customer Match\n+-- All Customers (conversions)\n+-- High-Value Customers (top 20% LTV)\n+-- Recent Buyers (30 days)\n+-- Lapsed Customers (180+ days)\n\n[ ] Website Visitors\n+-- All visitors (180 days)\n+-- Product viewers (90 days)\n+-- Cart abandoners (30 days)\n+-- Converters (exclude or include)\n\nLAYER 2: Google Audiences\n--------------------------\n[ ] In-Market Segments\n+-- Select 3-5 most relevant\n+-- Based on: Real purchase intent\n+-- Example: \"Apparel & Accessories Shoppers\"\n\n[ ] Affinity Segments\n+-- Broader, more volume\n+-- Example: \"Fashionistas\", \"Bargain Hunters\"\n+-- Less specific, more reach\n\n[ ] Life Events\n+-- Very powerful for specific moments\n+-- Example: \"Recently Moved\", \"Getting Married\"\n+-- Smaller audiences, high intent\n\nLAYER 3: Custom Segments\n-------------------------\n[ ] Search Term Based\n+-- People who searched specific terms\n+-- Competitor names\n+-- Product-specific queries\n\n[ ] Website Based\n+-- Visitors of competitor sites\n+-- Review sites\n+-- Industry publications\n```\n\n## Search Themes (2024+ Feature)\n\n### What Are Search Themes?\n\n```\nSEARCH THEMES EXPLAINED\n========================\n\nSearch Themes = Keywords you give PMax\nto help it understand which search queries are relevant.\n\nDIFFERENCE FROM SEARCH CAMPAIGNS:\n+-- Search Campaign Keywords: Exact match/phrase targeting\n+-- PMax Search Themes: Hints for AI, no guarantee\n\nWHEN TO USE:\n+-- New PMax campaigns (accelerates learning)\n+-- Specific product niches\n+-- When you also run Search (alignment)\n+-- Protecting branded terms\n```\n\n### Search Themes Best Practices\n\n```\nSEARCH THEMES SETUP\n===================\n\nRECOMMENDATIONS PER ASSET GROUP:\n+-- Count: 3-7 themes per asset group\n+-- Type: Mix of broad and specific\n+-- Negative keywords: Campaign-level negatives ARE supported (v20+ feature)\n+--   Apply via google_ads_mutate with a campaign_criterion operation\n+--   marked as negative. Account-level negative lists apply to PMax too.\n\nEXAMPLE (Fashion E-commerce):\nAsset Group: Winter Jackets\n+-- Theme 1: \"winter jacket women\"\n+-- Theme 2: \"warm jacket buy\"\n+-- Theme 3: \"[brand] winter jackets\"\n+-- Theme 4: \"parka women\"\n+-- Theme 5: \"winter jacket sale\"\n\nEXAMPLE (B2B Software):\nAsset Group: CRM Software\n+-- Theme 1: \"crm software\"\n+-- Theme 2: \"customer management system\"\n+-- Theme 3: \"sales pipeline tool\"\n+-- Theme 4: \"[brand] crm\"\n\nTIPS:\n+-- Use keyword research data\n+-- Include branded terms\n+-- Check Search Terms report for ideas\n+-- Update monthly based on performance\n```\n\n\n\nSee [detailed-reference.md](references/detailed-reference.md) for details.\n\n\n\n## Channel Performance Analysis\n\n### Insights Reporting (2025+)\n\n```\nPMAX CHANNEL BREAKDOWN\n======================\n\nLocation: Campaign -> Insights -> Asset Performance\n\nAVAILABLE METRICS PER CHANNEL:\n+-- Search (incl. Shopping)\n+-- YouTube\n+-- Display\n+-- Discover\n+-- Gmail\n+-- Maps (if local is active)\n\nWHAT TO ANALYZE:\n+-- Which channel delivers the most conversions?\n+-- ROAS per channel (if visible)\n+-- Video views and engagement (YouTube)\n+-- Impression share (Search/Shopping)\n+-- Top converting asset combinations\n```\n\n### Asset Performance Optimization\n\n```\nASSET PERFORMANCE (AD STRENGTH — PMax primary signal since v22)\n================================================================\n\n⚠️ Performance labels (Best/Good/Low/Pending) were REMOVED for PMax\n   campaigns in API v22. Use Ad Strength as the primary asset quality\n   signal for PMax.\n\nAD STRENGTH RATINGS:\n+-- Excellent: Best setup, keep structure\n+-- Good: Solid, consider adding variety\n+-- Average: Add more diverse assets\n+-- Poor: Immediate overhaul needed\n\nMonitor via:\ngoogle_ads_run_gaql(query=\"\n  SELECT\n    campaign.name,\n    asset_group.name,\n    asset_group.ad_strength,\n    asset_group.status,\n    metrics.impressions,\n    metrics.clicks,\n    metrics.cost_micros,\n    metrics.conversions,\n    metrics.conversions_value\n  FROM asset_group\n  WHERE segments.date DURING LAST_30_DAYS\n  ORDER BY metrics.cost_micros DESC\n\")\n\nOPTIMIZATION WORKFLOW:\n-----------------------\nWeek 1-2: Learning phase, no changes\nWeek 3-4: Check asset ratings\n+-- Remove: Assets with \"Low\" rating >30 days\n+-- Add: New variations of \"Best\" assets\n+-- Test: New concepts\n\nMonthly:\n+-- Refresh 20% of assets\n+-- Test new headlines\n+-- Seasonal updates\n+-- Analyze performance trends\n```\n\n\n\nSee [decision-trees.md](references/decision-trees.md) for details.\n\n\n\n\n\nSee [decision-trees.md](references/decision-trees.md) for details.\n\n\n\n## Google Ads Script: PMax Performance Monitor\n\n```javascript\n/**\n * Performance Max Campaign Monitor\n *\n * This script monitors PMax campaigns and sends alerts\n * on significant performance changes.\n *\n * Setup:\n * 1. Adjust SETTINGS to your preferences\n * 2. Schedule: Daily at 9:00\n */\n\n// === SETTINGS ===\nvar SETTINGS = {\n  // Email for alerts\n  EMAIL: 'you@example.com',\n\n  // Performance thresholds\n  CPA_INCREASE_THRESHOLD: 0.25,    // Alert on 25% CPA increase\n  ROAS_DECREASE_THRESHOLD: 0.20,   // Alert on 20% ROAS decrease\n  SPEND_CHANGE_THRESHOLD: 0.30,    // Alert on 30% spend change\n\n  // Comparison period\n  COMPARE_DAYS: 7,  // Compare last 7 days with previous 7 days\n\n  // Minimum spend for analysis\n  MIN_SPEND: 100\n};\n\nfunction main() {\n  var pMaxCampaigns = AdsApp.performanceMaxCampaigns()\n    .withCondition('Status = ENABLED')\n    .get();\n\n  var alerts = [];\n\n  while (pMaxCampaigns.hasNext()) {\n    var campaign = pMaxCampaigns.next();\n    var campaignAlerts = analyzeCampaign(campaign);\n    alerts = alerts.concat(campaignAlerts);\n  }\n\n  if (alerts.length > 0) {\n    sendAlertEmail(alerts);\n  }\n\n  Logger.log('PMax Monitor completed. Alerts: ' + alerts.length);\n}\n\nfunction analyzeCampaign(campaign) {\n  var alerts = [];\n  var campaignName = campaign.getName();\n\n  // Current period\n  var currentStats = campaign.getStatsFor('LAST_' + SETTINGS.COMPARE_DAYS + '_DAYS');\n\n  // Previous period (calculate manually)\n  var today = new Date();\n  var previousEnd = new Date(today.getTime() - (SETTINGS.COMPARE_DAYS * 24 * 60 * 60 * 1000));\n  var previousStart = new Date(previousEnd.getTime() - (SETTINGS.COMPARE_DAYS * 24 * 60 * 60 * 1000));\n\n  var previousStats = campaign.getStatsFor(\n    formatDate(previousStart),\n    formatDate(previousEnd)\n  );\n\n  // Check minimum spend\n  if (currentStats.getCost() < SETTINGS.MIN_SPEND) {\n    return alerts;\n  }\n\n  // CPA Analysis\n  var currentCPA = calculateCPA(currentStats);\n  var previousCPA = calculateCPA(previousStats);\n\n  if (previousCPA > 0 && currentCPA > 0) {\n    var cpaChange = (currentCPA - previousCPA) / previousCPA;\n    if (cpaChange > SETTINGS.CPA_INCREASE_THRESHOLD) {\n      alerts.push({\n        campaign: campaignName,\n        metric: 'CPA',\n        current: currentCPA.toFixed(2),\n        previous: previousCPA.toFixed(2),\n        change: (cpaChange * 100).toFixed(1) + '%',\n        severity: cpaChange > 0.5 ? 'HIGH' : 'MEDIUM'\n      });\n    }\n  }\n\n  // ROAS Analysis\n  var currentROAS = calculateROAS(currentStats);\n  var previousROAS = calculateROAS(previousStats);\n\n  if (previousROAS > 0 && currentROAS > 0) {\n    var roasChange = (currentROAS - previousROAS) / previousROAS;\n    if (roasChange < -SETTINGS.ROAS_DECREASE_THRESHOLD) {\n      alerts.push({\n        campaign: campaignName,\n        metric: 'ROAS',\n        current: currentROAS.toFixed(2),\n        previous: previousROAS.toFixed(2),\n        change: (roasChange * 100).toFixed(1) + '%',\n        severity: roasChange < -0.4 ? 'HIGH' : 'MEDIUM'\n      });\n    }\n  }\n\n  // Spend Analysis\n  var currentSpend = currentStats.getCost();\n  var previousSpend = previousStats.getCost();\n\n  if (previousSpend > 0) {\n    var spendChange = (currentSpend - previousSpend) / previousSpend;\n    if (Math.abs(spendChange) > SETTINGS.SPEND_CHANGE_THRESHOLD) {\n      alerts.push({\n        campaign: campaignName,\n        metric: 'Spend',\n        current: '$' + currentSpend.toFixed(2),\n        previous: '$' + previousSpend.toFixed(2),\n        change: (spendChange * 100).toFixed(1) + '%',\n        severity: 'LOW'\n      });\n    }\n  }\n\n  return alerts;\n}\n\nfunction calculateCPA(stats) {\n  var conversions = stats.getConversions();\n  var cost = stats.getCost();\n  return conversions > 0 ? cost / conversions : 0;\n}\n\nfunction calculateROAS(stats) {\n  var conversionValue = stats.getConversionValue();\n  var cost = stats.getCost();\n  return cost > 0 ? conversionValue / cost : 0;\n}\n\nfunction formatDate(date) {\n  return Utilities.formatDate(date, AdsApp.currentAccount().getTimeZone(), 'yyyyMMdd');\n}\n\nfunction sendAlertEmail(alerts) {\n  var subject = 'PMax Performance Alert - ' + AdsApp.currentAccount().getName();\n\n  var body = 'Performance Max Campaign Alerts\\n';\n  body += '================================\\n\\n';\n  body += 'Account: ' + AdsApp.currentAccount().getName() + '\\n';\n  body += 'Date: ' + new Date().toDateString() + '\\n\\n';\n\n  for (var i = 0; i < alerts.length; i++) {\n    var alert = alerts[i];\n    body += '[' + alert.severity + '] ' + alert.campaign + '\\n';\n    body += '  ' + alert.metric + ': ' + alert.previous + ' -> ' + alert.current;\n    body += ' (' + alert.change + ')\\n\\n';\n  }\n\n  body += '\\n---\\nGenerated by PMax Performance Monitor Script';\n\n  MailApp.sendEmail(SETTINGS.EMAIL, subject, body);\n}\n```\n\n## PMax 2025-2026 Feature Updates\n\n```\nPMAX RECENT UPDATES (IMPORTANT FOR OPTIMIZATION)\n==================================================\n\nv20 (2024): Campaign-level negative keywords\n+-- PMax now supports negative keywords at campaign level\n+-- Apply via google_ads_mutate using a campaign_criterion operation\n+--   with the negative flag set to true (pass as part of operations list)\n+-- Account-level shared negative keyword lists also apply\n\nv21 (2025): Search term reporting + Smart Bidding Exploration\n+-- Use campaign_search_term_view (NOT search_term_view) for PMax queries\n+-- Smart Bidding Exploration: target_roas_tolerance_percent_millis\n+-- Brand guidelines default ON for new PMax campaigns\n\nv22 (2025): ad_network_type + Asset performance labels removed\n+-- Channel breakdown via segments.ad_network_type\n+-- asset_group_asset.performance_label REMOVED for PMax\n+-- url_expansion_opt_out REMOVED → use AssetAutomationType\n+-- Ad Strength is now primary asset quality signal\n\nv23 / Mar 2026: Budget forecasting, High Value Mode, demographic reporting\n+-- High Value Mode for new customer acquisition (premium bidding)\n+-- First-party audience exclusions available\n+-- Demographic reporting in Insights\n\nHOW TO CHECK PMAX SEARCH TERMS (v21+):\ngoogle_ads_run_gaql(query=\"\n  SELECT\n    campaign.name,\n    campaign_search_term_view.search_term,\n    metrics.impressions,\n    metrics.clicks,\n    metrics.cost_micros,\n    metrics.conversions\n  FROM campaign_search_term_view\n  WHERE campaign.advertising_channel_type = 'PERFORMANCE_MAX'\n    AND segments.date DURING LAST_30_DAYS\n    AND metrics.cost_micros > 0\n  ORDER BY metrics.cost_micros DESC\n  LIMIT 200\n\")\n```\n\n## PMax vs Search: Coexistence Strategy\n\n```\nPMAX + SEARCH COEXISTENCE\n==========================\n\nGOOGLE'S PRIORITIZATION:\n+-- Exact match Search keyword -> Search wins\n+-- Phrase/Broad match -> Can be either\n+-- No keyword match -> PMax wins\n+-- Shopping queries -> PMax Shopping wins\n\nRECOMMENDED SETUP:\n-------------------\n1. Search Campaign: Brand + Top non-brand exact match\n2. PMax: Everything else (let AI optimize)\n3. Monitor: Search Terms report in both\n\nBRAND PROTECTION:\n+-- Option 1: Brand keywords in Search (exact)\n+-- Option 2: Brand exclusions in PMax\n+-- Option 3: Both (maximum control)\n+-- Check: Search Themes for brand alignment\n\nMEASURING INCREMENTALITY:\n+-- Run: 2 weeks with both on\n+-- Pause: PMax for 2 weeks\n+-- Compare: Total conversions + CPA\n+-- Decide: Based on incremental lift\n```\n\n## Output: PMax Setup Checklist\n\n```markdown\n# Performance Max Setup Checklist\n\n## Pre-Launch\n[ ] Conversion tracking verified (test conversions)\n[ ] Merchant Center feed approved (e-commerce)\n[ ] Enhanced Conversions enabled\n[ ] Minimum budget allocated ($50+/day)\n\n## Campaign Setup\n[ ] Campaign type: Performance Max\n[ ] Goal: Sales / Leads (correctly selected)\n[ ] Bid strategy: [Maximize Conversions / tROAS / tCPA]\n[ ] Target: [X] (if applicable)\n[ ] Budget: $[X]/day\n\n## Asset Groups\n[ ] Asset Group 1: [Name]\n  [ ] Final URL: [URL]\n  [ ] Headlines: 5-15 items\n  [ ] Long headlines: 1-5 items\n  [ ] Descriptions: 4-5 items\n  [ ] Images: Landscape + Square + Portrait\n  [ ] Logo: Square + Landscape\n  [ ] Video: Optional but recommended\n  [ ] Audience Signals: Configured\n  [ ] Search Themes: 3-7 items\n\n## Listing Groups (E-commerce)\n[ ] Product selection correct\n[ ] Custom labels used for segmentation\n[ ] Exclusions set (out of stock, low margin)\n\n## Final Checks\n[ ] Final URL expansion: configured via AssetAutomationType.FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION\n    (Note: url_expansion_opt_out field was removed in v22 — use AssetAutomationType instead)\n[ ] Brand exclusions: [Yes/No, which]\n[ ] URL exclusions configured\n[ ] Schedule: 24/7 or custom\n\n## Post-Launch Monitoring\n[ ] Day 1: Verify delivery\n[ ] Day 3: Check asset eligibility\n[ ] Week 1: Monitor learning phase\n[ ] Week 2: First asset performance check\n[ ] Week 4: Full optimization review\n```\n"
}