Der Conversion-Wert-Wächter für dein Konto.

/**
 * CONVERSION-WERT-WAECHTER — Google Ads Script
 * Version 1.0.0 · Stand 2026-08-30
 * https://visnakovs.de/google-ads-scripts/conversion-wert-waechter/
 *
 * Sucht den Defekt, den zaehlende Pruefungen nie finden: die Conversion feuert
 * weiter, aber der Umsatz, den sie meldet, ist weg. Die Anzahl bleibt gruen,
 * der ROAS im Konto wird zur Erfindung, und die Gebotsstrategie optimiert
 * monatelang auf eine Zahl, die es nicht mehr gibt.
 *
 * Der Vergleichswert ist bewusst NICHT der Vormonat. Ein Bruch, der alt genug
 * ist, hat sein eigenes Vergleichsfenster schon vergiftet und liest sich dann
 * als gerade Linie. Verglichen wird gegen den Median der drei besten
 * Wert-je-Conversion-Monate im gesamten Zeitraum.
 *
 * ⛔ GARANTIE — Dieses Skript verändert nichts in deinem Konto: Es liest, es
 * protokolliert, es schreibt nicht. Jede Abfrage darin ist ein SELECT. Es gibt
 * keinen Aufruf, der eine Conversion-Aktion, eine Gebotsstrategie oder eine
 * Kampagne anfassen koennte.
 *
 * Getestet gegen Google Ads Scripts, Stand 08/2026.
 *
 * Umlaute stehen in diesem Code bewusst als ae/oe/ue: der Script-Editor zeigt
 * kopierte Dateien je nach Browser in wechselnder Kodierung an, und ein
 * kaputtes Sonderzeichen im Protokoll oder in einer Bedingung faellt still aus.
 */

// ---------------------------------------------------------------------------
// CONFIG
// ---------------------------------------------------------------------------
var CONFIG = {
  // E-Mail-Zusammenfassung. Bewusst AUS - erst lesen, dann einschalten.
  EMAIL_SENDEN: false,
  EMPFAENGER: 'dein.name@beispiel.de',
  BETREFF: 'Google Ads: Conversion-Werte auffaellig',

  // Nur bei diesen Stufen mailen. HINWEIS-Funde sind Einordnung, kein Alarm.
  EMAIL_AB_STUFE: 'WARNUNG', // 'KRITISCH' | 'WARNUNG' | 'HINWEIS'

  // Rueckblick in Monaten. Muss eine gesunde Phase mit abdecken - sonst
  // versteckt sich ein alter Bruch hinter lauter kaputten Monaten.
  MONATE: 24,

  // Unter dieser Zahl schwankt der Wert je Conversion an einzelnen Verkaeufen.
  MIN_CONVERSIONS: 5,

  // Wert je Conversion muss unter diesen Anteil seines gesunden Niveaus fallen.
  WERT_EINBRUCH_ANTEIL: 0.30,

  // ... waehrend die Anzahl mindestens diesen Anteil haelt. Genau das
  // unterscheidet einen Tracking-Bruch von einem echten Umsatzrueckgang.
  ANZAHL_HAELT_ANTEIL: 0.50,

  // Aelter als so viele Monate: Historie, kein laufender Vorfall.
  VERALTET_AB_MONATEN: 2
};

// Gebotsstrategien, die auf den Conversion-WERT optimieren. Genau hier wird
// aus einem Messfehler eine falsche Budgetverteilung.
var WERT_GEBOTE = ['TARGET_ROAS', 'MAXIMIZE_CONVERSION_VALUE'];

var STUFEN_RANG = { 'KRITISCH': 3, 'WARNUNG': 2, 'HINWEIS': 1, 'OK': 0 };

// ---------------------------------------------------------------------------

function main() {
  var heute = new Date();
  var jetztIndex = heute.getFullYear() * 12 + (heute.getMonth() + 1);
  var bereich = zeitraum(CONFIG.MONATE);

  Logger.log('Conversion-Wert-Waechter 1.0.0 — Konto ' + AdsApp.currentAccount().getCustomerId());
  Logger.log('Zeitraum: ' + bereich.start + ' bis ' + bereich.ende + ' (' + CONFIG.MONATE + ' Monate)');
  Logger.log('Waehrung laut Konto: ' + AdsApp.currentAccount().getCurrencyCode());
  Logger.log('Dieses Skript liest nur. Es schreibt nichts ins Konto.');
  Logger.log('');

  var reihen = holeReihenJeAktion(bereich);
  var ebene = 'Conversion-Aktion';
  if (reihen === null) {
    Logger.log('HINWEIS: Die Auswertung je Conversion-Aktion war in diesem Konto nicht');
    Logger.log('abrufbar. Das Skript weicht auf die Kampagnen-Ebene aus. Damit sieht es');
    Logger.log('einen Wertbruch nur noch, wenn er eine ganze Kampagne betrifft - eine');
    Logger.log('einzelne kaputte Conversion-Aktion neben gesunden geht darin unter.');
    Logger.log('');
    reihen = holeReihenJeKampagne(bereich);
    ebene = 'Kampagne';
  }

  var stammdaten = holeStammdaten();
  var wertBietendeKampagnen = holeWertBietendeKampagnen();

  var funde = auswerten(reihen, stammdaten, wertBietendeKampagnen, jetztIndex, ebene);
  berichte(funde, reihen, ebene, stammdaten, bereich);
}

// --- Konto lesen -----------------------------------------------------------

/**
 * Wert und Anzahl je Conversion-Aktion und Monat.
 *
 * Die Abfrage laeuft FROM customer und segmentiert nach
 * segments.conversion_action_name. Der Umweg ist noetig, weil
 * metrics.conversions FROM conversion_action verboten ist.
 *
 * Gibt null zurueck, wenn das Konto die Abfrage nicht zulaesst - dann faellt
 * main() auf die Kampagnen-Ebene zurueck und sagt das im Protokoll.
 */
function holeReihenJeAktion(bereich) {
  var abfrage =
    'SELECT segments.month, segments.conversion_action_name, ' +
    'metrics.all_conversions, metrics.all_conversions_value ' +
    'FROM customer ' +
    "WHERE segments.date BETWEEN '" + bereich.start + "' AND '" + bereich.ende + "'";
  try {
    var reihen = {};
    var lauf = AdsApp.search(abfrage);
    while (lauf.hasNext()) {
      var reihe = lauf.next();
      var name = pfad(reihe, ['segments', 'conversionActionName']);
      if (!name) continue;
      sammle(reihen, name, monatVon(reihe), reihe);
    }
    return reihen;
  } catch (fehler) {
    Logger.log('Abfrage je Conversion-Aktion fehlgeschlagen: ' + fehler);
    return null;
  }
}

/** Rueckfallebene: Wert und Anzahl je Kampagne und Monat. */
function holeReihenJeKampagne(bereich) {
  var abfrage =
    'SELECT segments.month, campaign.name, ' +
    'metrics.all_conversions, metrics.all_conversions_value ' +
    'FROM campaign ' +
    "WHERE segments.date BETWEEN '" + bereich.start + "' AND '" + bereich.ende + "' " +
    "AND campaign.status != 'REMOVED'";
  var reihen = {};
  var lauf = AdsApp.search(abfrage);
  while (lauf.hasNext()) {
    var reihe = lauf.next();
    var name = pfad(reihe, ['campaign', 'name']);
    if (!name) continue;
    sammle(reihen, name, monatVon(reihe), reihe);
  }
  return reihen;
}

function sammle(reihen, name, monat, reihe) {
  if (!monat) return;
  if (!reihen[name]) reihen[name] = {};
  if (!reihen[name][monat]) reihen[name][monat] = { anzahl: 0, wert: 0 };
  reihen[name][monat].anzahl += zahl(pfad(reihe, ['metrics', 'allConversions']));
  reihen[name][monat].wert += zahl(pfad(reihe, ['metrics', 'allConversionsValue']));
}

/**
 * Einstellungen je Conversion-Aktion. Das entscheidende Feld ist
 * always_use_default_value: steht es, war der "Umsatz" nie Umsatz, sondern ein
 * fester Platzhalter - eine Aenderung daran ist eine Einstellung, kein Verlust.
 * Ohne dieses Feld meldet ein Waechter reihenweise Fehlalarme.
 */
function holeStammdaten() {
  var abfrage =
    'SELECT conversion_action.name, conversion_action.status, ' +
    'conversion_action.primary_for_goal, ' +
    'conversion_action.include_in_conversions_metric, ' +
    'conversion_action.value_settings.default_value, ' +
    'conversion_action.value_settings.always_use_default_value ' +
    'FROM conversion_action';
  var daten = { verfuegbar: false, nach_name: {} };
  try {
    var lauf = AdsApp.search(abfrage);
    while (lauf.hasNext()) {
      var reihe = lauf.next();
      var aktion = reihe.conversionAction || {};
      var werte = aktion.valueSettings || {};
      daten.nach_name[aktion.name] = {
        status: aktion.status || 'UNKNOWN',
        primaer: aktion.primaryForGoal === true,
        // Fehlt das Feld in der Antwort, ist es false - die API laesst
        // Standardwerte im JSON schlicht weg.
        gezaehlt: aktion.includeInConversionsMetric === true,
        standardwert: zahl(werte.defaultValue),
        immer_standardwert: werte.alwaysUseDefaultValue === true
      };
    }
    daten.verfuegbar = true;
  } catch (fehler) {
    Logger.log('Stammdaten der Conversion-Aktionen nicht abrufbar: ' + fehler);
    Logger.log('Ohne sie kann das Skript einen festen Platzhalterwert nicht von echtem');
    Logger.log('Umsatz unterscheiden. Es faellt auf die Faustregel zurueck: ein Wert je');
    Logger.log('Conversion, der ueber alle Monate exakt gleich war, gilt als Platzhalter.');
  }
  return daten;
}

/** Aktive Kampagnen, die auf den Conversion-Wert bieten. */
function holeWertBietendeKampagnen() {
  var namen = [];
  try {
    var lauf = AdsApp.search(
      'SELECT campaign.name, campaign.bidding_strategy_type FROM campaign ' +
      "WHERE campaign.status = 'ENABLED'"
    );
    while (lauf.hasNext()) {
      var reihe = lauf.next();
      var art = pfad(reihe, ['campaign', 'biddingStrategyType']);
      for (var i = 0; i < WERT_GEBOTE.length; i++) {
        if (art === WERT_GEBOTE[i]) { namen.push(pfad(reihe, ['campaign', 'name'])); break; }
      }
    }
  } catch (fehler) {
    Logger.log('Gebotsstrategien nicht abrufbar: ' + fehler);
  }
  return namen;
}

// --- Auswertung ------------------------------------------------------------

function auswerten(reihen, stammdaten, wertBietende, jetztIndex, ebene) {
  var funde = [];
  var bietetAufKaputtes = false;

  for (var name in reihen) {
    if (!reihen.hasOwnProperty(name)) continue;
    var info = stammdaten.nach_name[name] || {};
    if (info.status === 'REMOVED') continue; // Entferntes kann nichts brechen

    // Der laufende Kalendermonat ist immer unvollstaendig und fliegt raus -
    // und zwar der Kalendermonat, nicht einfach der letzte Monat mit Daten.
    // Bei einer duennen Aktion sind das zwei verschiedene Dinge, und der
    // letzte Monat mit Daten ist der aussagekraeftigste von allen.
    var monate = [];
    for (var monat in reihen[name]) {
      if (!reihen[name].hasOwnProperty(monat)) continue;
      if (monatIndex(monat) === jetztIndex) continue;
      monate.push(monat);
    }
    monate.sort();
    if (monate.length < 5) continue;

    var letzter = monate[monate.length - 1];
    var veraltet = (jetztIndex - monatIndex(letzter)) > CONFIG.VERALTET_AB_MONATEN;
    var letzteAnzahl = reihen[name][letzter].anzahl;
    var letzterWert = reihen[name][letzter].wert;

    var anzahlen = [];
    for (var a = 0; a < monate.length; a++) anzahlen.push(reihen[name][monate[a]].anzahl);
    var typischeAnzahl = median(anzahlen);
    if (typischeAnzahl < CONFIG.MIN_CONVERSIONS) continue;

    if (letzteAnzahl === 0) {
      funde.push({
        art: veraltet ? 'RUHT' : 'ANZAHL_GESTOPPT',
        stufe: veraltet ? 'HINWEIS' : 'WARNUNG',
        name: name,
        monat: letzter,
        gezaehlt: info.gezaehlt === true,
        detail: 'feuert nicht mehr (typisch ' + runde(typischeAnzahl, 0) + '/Monat)'
      });
      continue;
    }

    // Wert je Conversion, nur aus Monaten mit belastbarer Anzahl.
    var jeConversion = {};
    var werteListe = [];
    var alleGleich = true;
    var ersterWert = null;
    for (var b = 0; b < monate.length; b++) {
      var m = monate[b];
      if (reihen[name][m].anzahl < CONFIG.MIN_CONVERSIONS) continue;
      var v = reihen[name][m].wert / reihen[name][m].anzahl;
      jeConversion[m] = v;
      werteListe.push(v);
      if (ersterWert === null) ersterWert = v;
      else if (Math.abs(v - ersterWert) > 0.005) alleGleich = false;
    }
    if (werteListe.length < 4) continue;

    var sortiert = werteListe.slice(0).sort(function (x, y) { return y - x; });
    var gesund = median(sortiert.slice(0, 3));
    if (gesund <= 0) continue;
    var letztesJeConversion = letzterWert / letzteAnzahl;

    // Ohne Stammdaten: ein ueber alle Monate exakt konstanter Wert ist ein
    // Platzhalter, kein Umsatz. Grobe Regel, aber ehrlicher als Schweigen.
    var festerStandardwert = info.immer_standardwert === true ||
      (!stammdaten.verfuegbar && alleGleich);

    // Die Anzahl-haelt-Pruefung trennt Tracking-Bruch von Nachfragerueckgang.
    // Fuer exakt 0,00 Umsatz auf einer echten Geld-Aktion ist sie die falsche
    // Pruefung: kein Rueckgang der Welt erzeugt 48 Kaeufe fuer 0,00.
    var harteNull = (letzterWert === 0 && letzteAnzahl >= CONFIG.MIN_CONVERSIONS && !festerStandardwert);
    var eingebrochen = (letzteAnzahl >= typischeAnzahl * CONFIG.ANZAHL_HAELT_ANTEIL &&
      letztesJeConversion < gesund * CONFIG.WERT_EINBRUCH_ANTEIL);
    if (!harteNull && !eingebrochen) continue;

    var seit = ersterKaputterMonat(monate, jeConversion, gesund) || letzter;
    var detail = 'Wert je Conversion ' + runde(letztesJeConversion, 2) + ' statt gesund ' +
      runde(gesund, 2) + '; Anzahl haelt (' + runde(letzteAnzahl, 0) + ' statt typisch ' +
      runde(typischeAnzahl, 0) + '); aendert sich ab ' + seit;

    var art, stufe;
    if (festerStandardwert) {
      art = 'STANDARDWERT_GEAENDERT';
      stufe = 'HINWEIS';
    } else if (veraltet) {
      art = 'RUHT';
      stufe = 'HINWEIS';
    } else if (letzterWert === 0) {
      art = 'WERT_NULL';
      stufe = 'WARNUNG';
    } else {
      art = 'WERT_EINGEBROCHEN';
      stufe = 'WARNUNG';
    }
    if ((art === 'WERT_NULL' || art === 'WERT_EINGEBROCHEN') && info.gezaehlt === true) {
      bietetAufKaputtes = true;
    }

    funde.push({
      art: art, stufe: stufe, name: name, monat: letzter, seit: seit,
      gezaehlt: info.gezaehlt === true, primaer: info.primaer === true, detail: detail
    });
  }

  if (wertBietende.length > 0) {
    if (bietetAufKaputtes) {
      funde.push({
        art: 'GEBOT_IN_GEFAHR', stufe: 'KRITISCH', name: '-', monat: '-', gezaehlt: true,
        detail: 'Wertbasierte Gebote laufen auf: ' + wertBietende.slice(0, 4).join(', ')
      });
    } else if (stammdaten.verfuegbar) {
      var gezaehlteAktionen = [];
      var alleFest = true;
      for (var n in stammdaten.nach_name) {
        if (!stammdaten.nach_name.hasOwnProperty(n)) continue;
        var s = stammdaten.nach_name[n];
        if (s.gezaehlt !== true || s.status !== 'ENABLED') continue;
        gezaehlteAktionen.push(n);
        if (s.immer_standardwert !== true) alleFest = false;
      }
      if (gezaehlteAktionen.length > 0 && alleFest) {
        funde.push({
          art: 'PLATZHALTER_WERT', stufe: 'HINWEIS', name: '-', monat: '-', gezaehlt: true,
          detail: 'Wertbasierte Gebote auf lauter festen Standardwerten (' +
            gezaehlteAktionen.slice(0, 3).join(', ') +
            '). Der ROAS dieses Kontos ist eine Punktzahl, kein Euro-Betrag.'
        });
      }
    }
  }

  if (ebene === 'Kampagne') {
    for (var f = 0; f < funde.length; f++) funde[f].name = 'Kampagne: ' + funde[f].name;
  }
  return funde;
}

/** Erster Monat, ab dem der Wert dauerhaft unten blieb. */
function ersterKaputterMonat(monate, jeConversion, gesund) {
  var grenze = gesund * CONFIG.WERT_EINBRUCH_ANTEIL;
  for (var i = 0; i < monate.length; i++) {
    var m = monate[i];
    if (!(m in jeConversion) || jeConversion[m] >= grenze) continue;
    var bleibtUnten = true;
    for (var j = i; j < monate.length; j++) {
      var spaeter = monate[j];
      if ((spaeter in jeConversion) && jeConversion[spaeter] >= grenze) { bleibtUnten = false; break; }
    }
    if (bleibtUnten) return m;
  }
  return null;
}

function hoechsteStufe(funde) {
  var beste = 'OK';
  for (var i = 0; i < funde.length; i++) {
    if (STUFEN_RANG[funde[i].stufe] > STUFEN_RANG[beste]) beste = funde[i].stufe;
  }
  return beste;
}

// --- Ausgabe ---------------------------------------------------------------

function berichte(funde, reihen, ebene, stammdaten, bereich) {
  var geprueft = 0;
  for (var k in reihen) if (reihen.hasOwnProperty(k)) geprueft++;

  Logger.log('Ausgewertet auf Ebene: ' + ebene + ' (' + geprueft + ' Reihen).');
  if (!stammdaten.verfuegbar) {
    Logger.log('Ohne Stammdaten - Platzhalterwerte wurden ueber die Faustregel erkannt.');
  }

  if (funde.length === 0) {
    Logger.log('Ergebnis: keine Auffaelligkeit.');
    Logger.log('Das heisst: kein Wertbruch, den diese Regeln beweisen koennen. Es heisst');
    Logger.log('nicht, dass richtig gemessen wird - eine Aktion, die noch nie einen Wert');
    Logger.log('geliefert hat, hat auch kein gesundes Niveau, gegen das man sie haelt.');
  } else {
    Logger.log('Ergebnis: ' + funde.length + ' Auffaelligkeit(en), hoechste Stufe ' +
      hoechsteStufe(funde) + '.');
    Logger.log('');
    var rang = { 'KRITISCH': 0, 'WARNUNG': 1, 'HINWEIS': 2 };
    funde.sort(function (a, b) { return (rang[a.stufe] || 9) - (rang[b.stufe] || 9); });
    for (var i = 0; i < funde.length; i++) {
      var f = funde[i];
      Logger.log('[' + f.stufe + '] ' + f.art + ' — ' + f.name);
      Logger.log('    ' + f.detail);
      if (f.gezaehlt) Logger.log('    zaehlt in die Conversions-Spalte, steuert also Gebote mit');
    }
  }

  Logger.log('');
  Logger.log('Lauf beendet: Zeitraum ' + bereich.start + '..' + bereich.ende + ' · ' +
    funde.length + ' Fund(e).');
  vielleichtMailen(funde, ebene, bereich);
}

function vielleichtMailen(funde, ebene, bereich) {
  if (!CONFIG.EMAIL_SENDEN) return;
  var stufe = hoechsteStufe(funde);
  var schwelle = STUFEN_RANG[CONFIG.EMAIL_AB_STUFE] || 2;
  if (STUFEN_RANG[stufe] < schwelle) return;
  if (!CONFIG.EMPFAENGER || CONFIG.EMPFAENGER.indexOf('@') === -1) {
    Logger.log('E-Mail uebersprungen: EMPFAENGER ist keine Adresse.');
    return;
  }

  var zeilen = [];
  zeilen.push('Konto: ' + AdsApp.currentAccount().getCustomerId());
  zeilen.push('Zeitraum: ' + bereich.start + ' bis ' + bereich.ende);
  zeilen.push('Ebene: ' + ebene);
  zeilen.push('Hoechste Stufe: ' + stufe);
  zeilen.push('');
  for (var i = 0; i < funde.length; i++) {
    zeilen.push('[' + funde[i].stufe + '] ' + funde[i].art + ' — ' + funde[i].name);
    zeilen.push('  ' + funde[i].detail);
    zeilen.push('');
  }
  zeilen.push('Dieses Skript liest nur. Es hat nichts im Konto veraendert.');

  MailApp.sendEmail(CONFIG.EMPFAENGER, CONFIG.BETREFF + ' (' + stufe + ')', zeilen.join('\n'));
  Logger.log('E-Mail an ' + CONFIG.EMPFAENGER + ' verschickt.');
}

// --- Kleinkram -------------------------------------------------------------

/** Erster Tag des Monats vor n Monaten bis heute, als JJJJ-MM-TT. */
function zeitraum(monate) {
  var heute = new Date();
  var jahr = heute.getFullYear();
  var monat = heute.getMonth() + 1 - monate;
  while (monat <= 0) { monat += 12; jahr -= 1; }
  return {
    start: jahr + '-' + zweistellig(monat) + '-01',
    ende: heute.getFullYear() + '-' + zweistellig(heute.getMonth() + 1) + '-' + zweistellig(heute.getDate())
  };
}

function monatVon(reihe) {
  var roh = pfad(reihe, ['segments', 'month']);
  return roh ? String(roh).substring(0, 7) : null;
}

function monatIndex(monat) {
  var teile = String(monat).split('-');
  return parseInt(teile[0], 10) * 12 + parseInt(teile[1], 10);
}

/**
 * Feldzugriff, der ein fehlendes Zwischenobjekt aushaelt. Die API laesst
 * Felder mit Standardwert (0, false, "") in der Antwort einfach weg - ein
 * direkter reihe.metrics.allConversionsValue faellt dann auf die Nase.
 */
function pfad(objekt, teile) {
  var aktuell = objekt;
  for (var i = 0; i < teile.length; i++) {
    if (aktuell === null || aktuell === undefined) return null;
    aktuell = aktuell[teile[i]];
  }
  return (aktuell === undefined) ? null : aktuell;
}

function zahl(wert) {
  var n = Number(wert);
  return isNaN(n) ? 0 : n;
}

function median(liste) {
  if (!liste.length) return 0;
  var sortiert = liste.slice(0).sort(function (a, b) { return a - b; });
  var mitte = Math.floor(sortiert.length / 2);
  if (sortiert.length % 2 === 1) return sortiert[mitte];
  return (sortiert[mitte - 1] + sortiert[mitte]) / 2;
}

function runde(wert, stellen) {
  var faktor = Math.pow(10, stellen);
  return String(Math.round(wert * faktor) / faktor);
}

function zweistellig(zahlWert) {
  return zahlWert < 10 ? '0' + zahlWert : String(zahlWert);
}

In die Zwischenablage kopiert.