HeroMatrix Setup Guide: Profit Modes & Configuration

Follow this guide to choose your profit evaluation mode, connect your Google Sheets supplemental feed, and deploy HeroMatrix in your Google Ads account.

---

📁 Script Architecture

HeroMatrix is split into four clean files in the Google Ads Scripts editor so you never have to dig through core code to adjust your targets:

• Info.gs: Quick-start instructions, version info, and MIT license header.
• Const.gs: One-time installation settings, evaluation mode selectors, and Google Sheet URLs.
• Config.gs: Optimization thresholds, lookback windows, and custom label names.
• Code.gs: Core execution engine, GAQL queries, and Google Sheets dashboard builder.

---

🎛️ Choosing Your Profit Evaluation Mode

In Const.gs, set EVALUATION_MODE to choose how HeroMatrix grades converting sellers and caps spend on non-converting products:

Breakdown of the 4 Evaluation Modes

1. ROAS Mode (No Margin Data Required)

• How it works: Grades products strictly on Google Ads conversion value and ad spend. Skips margin lookups for fast, zero-maintenance execution.
• Sellers: Demoted to Anti-Hero if ROAS falls below your target threshold.
• Non-Sellers: Flagged as Villain if spend exceeds a flat dollar limit (default $50).

2. FLAT_MARGIN Mode (Fastest Profit Setup)

• How it works: Queries live product prices directly from Google Ads and multiplies them by your global margin rate (e.g., 40%) to calculate unit margin on the fly—no margin spreadsheet required.
• Sellers: Graded by comparing CPA against unit margin (e.g., 1.0x for break-even on Heroes, or 1.2x on high-volume Superheroes).
• Non-Sellers: Flagged as Villain when ad spend exceeds a set percentage of the item’s unit margin.

3. VARIABLE_MARGIN Mode (Per-Product COGS / Margin Sheet)

• How it works: Reads exact per-product margins from a Google Sheet using dollar margin, percentage margin, or Price minus COGS.
• Cross-Sell / Basket Safeguard: Automatically protects converting items from Anti-Hero demotion if their overall ROAS exceeds your safeguard threshold (default 2.0x), accounting for multi-item cart value.
• Smart Fallback: If a product is missing from your margin sheet, HeroMatrix automatically falls back to your flat margin rate or default ROAS/spend limits.

4. HYBRID_MARGIN Mode (ROAS Sellers + Margin Bleeder Protection)

• How it works: Evaluates converting sellers using standard target ROAS rules, but caps spend on 0-sale products using each item’s unit margin so expensive items get enough testing room while cheap items are cut early.

---

⚙️ Configuration Reference

1. Installation Settings (Const.gs)

Configure your evaluation mode and Google Sheet links in Const.gs:

const CONSTANTS = {
  // 'ROAS' | 'FLAT_MARGIN' | 'VARIABLE_MARGIN' | 'HYBRID_MARGIN'
  EVALUATION_MODE: 'ROAS',

  // Optional: Filter conversions by a specific numeric Conversion Action ID (e.g. '123456789')
  CONVERSION_ACTION_ID: null,

  // Optional: Regex pattern & replacement to clean product IDs
  PRODUCT_ID_REPLACE: {
    PATTERN: null,
    REPLACEMENT: ''
  },

  OUTPUT_SHEET: {
    URL: 'YOUR_OUTPUT_SPREADSHEET_URL',
    TAB_NAME: 'Products',
    OVERVIEW_TAB_NAME: 'Overview',
    TRENDS_TAB_NAME: 'Label Trends',
    ENABLE_TRENDS_LOG: true,
    LOGS_TAB_NAME: 'Logs',
    LABEL_COLUMN: 'custom_label_3'
  },

  MARGIN_SHEET: {
    URL: '',
    TAB_NAME: 'Products',
    MARGIN_TYPE: 'ABSOLUTE', // 'ABSOLUTE' ($ per unit) or 'PERCENTAGE' (% of price)
    COLUMNS: {
      ID: 'id',
      MARGIN: 'margin',
      PRICE: 'price',
      COGS: 'cost_of_goods_sold'
    }
  },

  PERMANENT_VILLAINS_SHEET: {
    USE_PERMANENT_LIST: true,
    URL: '',
    TAB_NAME: 'Villains',
    COLUMNS: {
      ID: 'id',
      LABEL: 'custom_label_3'
    }
  }
};

2. Optimization Thresholds (Config.gs)

Adjust your lookback window, dry-run toggle, and tier thresholds in Config.gs:

const CONFIG = {
  GENERAL: {
    DRY_RUN: false,
    DAYS_BACK: 90,
    DAYS_BACK_OFFSET: 0,
    MIN_SALES_FOR_CPA: 0.5
  },

  LABELS: {
    SUPERHERO: { name: 'superhero', desc: 'Top performing, highly profitable products with strong sales.' },
    HERO:      { name: 'hero',      desc: 'Consistent performers with healthy margins/profitability.' },
    SIDEKICK:  { name: 'sidekick',  desc: 'Products being tested, low volume, or low fractional assists (< min_sales).' },
    ANTI_HERO: { name: 'anti_hero', desc: 'Products with sales that are losing money or have unprofitable CPA/ROAS.' },
    VILLAIN:   { name: 'villain',   desc: 'Products with zero sales that exceed the allowable spend threshold.' },
    GHOST:     { name: 'ghost',     desc: 'Products with zero sales, zero clicks, and impressions below the visibility threshold.' }
  },

  MODES: {
    ROAS: {
      SUPERHERO: { min_sales: 2, min_roas: 1.20 },
      HERO:      { min_sales: 0.75, min_roas: 1.25 },
      VILLAIN:   { max_spend: 50.0 },
      GHOST:     { max_impressions: 30 }
    },
    FLAT_MARGIN: {
      DEFAULT_MARGIN_RATE: 0.40,
      SUPERHERO: { min_sales: 2, max_cpa_to_margin_ratio: 1.20 },
      HERO:      { min_sales: 0.75, max_cpa_to_margin_ratio: 1.00 },
      ANTI_HERO: { roas_safeguard: 2.0, fallback_min_roas: 1.0 },
      VILLAIN:   { max_cost_to_margin_ratio: 0.40, fallback_max_spend: 50.0 },
      GHOST:     { max_impressions: 30 }
    },
    VARIABLE_MARGIN: {
      DEFAULT_MARGIN_RATE: null,
      SUPERHERO: { min_sales: 2, max_cpa_to_margin_ratio: 1.20 },
      HERO:      { min_sales: 0.75, max_cpa_to_margin_ratio: 1.00 },
      ANTI_HERO: { roas_safeguard: 2.0, fallback_min_roas: 1.0 },
      VILLAIN:   { max_cost_to_margin_ratio: 0.40, fallback_max_spend: 50.0 },
      GHOST:     { max_impressions: 30 }
    },
    HYBRID_MARGIN: {
      DEFAULT_MARGIN_RATE: null,
      SUPERHERO: { min_sales: 2, min_roas: 1.20 },
      HERO:      { min_sales: 0.75, min_roas: 1.25 },
      VILLAIN:   { max_cost_to_margin_ratio: 0.40, fallback_max_spend: 50.0 },
      GHOST:     { max_impressions: 30 }
    }
  }
};

---

📑 Supplemental Feed Output Columns

The Products tab in your output Google Sheet can be linked directly to Google Merchant Center as a supplemental feed. All diagnostic columns start with an underscore (_) so Merchant Center ignores them while giving your team full performance visibility: