Handbuch

Preisrechner-Funnel für WordPress · Version 2.1.1 · Stand: 26. August 2026

1. Überblick

Ein Besucher öffnet eine Seite mit dem Shortcode [energo_rechner], klickt sich durch die Schritte und sieht laufend seinen Preis. Am Ende gibt er seine Kontaktdaten ein und sendet ab. Dann passiert Folgendes:

1. Spamprüfung — Honeypot, Mindest-Ausfüllzeit, Rate-Limit
2. Der Server rechnet den Preis neu — der Browserwert ist nur Anzeige
3. E-Mail an Sie, mit der kompletten Konfiguration
4. Projekt in HERO anlegen
5. Scheitert HERO, kommt die Anfrage trotzdem per E-Mail an, plus Warnmail

Grundsätze

Technischer Aufbau

Browser                          WordPress                      HERO
───────                          ─────────                      ────
Funnel-Engine (JS)         ←──   Funnel-Definition (JSON)
  rendert den Funnel
  rechnet den Preis              Preisberechnung (PHP)
  POST /wp-json/             ──→   rechnet nach             ──→  GraphQL
       energo/v1/lead              E-Mail raus                   oder Lead-API

Die Preisberechnung existiert zweimal: einmal im Browser für die Anzeige und einmal in PHP als maßgebliche Fassung. Beide müssen dasselbe Ergebnis liefern; die Reihenfolge der Rechenschritte ist vertraglich festgelegt.

2. Installation

Per FTP

Den Plugin-Ordner mit allen Dateien hochladen nach wp-content/plugins/. Rechte: Ordner 755, Dateien 644. Kein zweiter Ordner innerhalb des ersten — das ist der häufigste Installationsfehler.

Über das Backend

Plugins → Installieren → Plugin hochladen → ZIP wählen → Aktivieren.

Aktualisieren

Alle Dateien ersetzen. Einstellungen, gespeicherte Funnels und Designs bleiben erhalten. Vorher eine Sicherung anlegen, besonders bei einem Sprung über eine Hauptversion.

Prüfen, ob es läuft

Voraussetzungen

3. Konfiguration

Backend-Menü

Preisrechner
├── Funnel          Übersicht, anlegen, duplizieren, löschen, bearbeiten
└── Lizenz          Lizenzschlüssel und Stufe

Einstellungen
└── Preisrechner    HERO-Anbindung, Preise, Benachrichtigung

Konstanten in der wp-config.php

Konstanten haben immer Vorrang vor den Backend-Einstellungen. Ist eine gesetzt, wird das zugehörige Feld im Backend gesperrt und zeigt an, woher der Wert stammt.

define('ENERGO_HERO_TOKEN',   'ihr-hero-api-token');
define('ENERGO_HERO_MEASURE', 'KLI');
define('ENERGO_HERO_STATUS',  201);
define('ENERGO_LEAD_MAIL_TO', 'info@ihre-domain.de');

Der API-Token: wo er hingehört

Der Token wird zur Laufzeit in dieser Reihenfolge gesucht, der erste Treffer gewinnt:

Umgebungsvariable setzen — PHP-FPM (pool.d/www.conf):

env[ENERGO_HERO_TOKEN] = ihr-hero-api-token

Apache (vHost):

SetEnv ENERGO_HERO_TOKEN "ihr-hero-api-token"

Bei Plesk und cPanel gibt es dafür ein Feld „Umgebungsvariablen“ in den PHP-Einstellungen der Domain.

Was nie passieren darf

• Der Token gehört nie ins JavaScript, in ein data--Attribut oder in eine Datei unter /wp-content/uploads/. Alles dort ist per URL abrufbar.
• Nicht in einer eigenen, im Backend einsehbaren Options-Zeile ablegen.
• Nicht ins Git-Repository committen.

4. Der Funnel-Editor

Einbinden

[energo_rechner]                      erster aktiver Funnel
[energo_rechner funnel="waerme"]      bestimmter Funnel
[energo_rechner privacy="https://…"]  abweichender Datenschutz-Link
[energo_rechner email="info@…"]       abweichende Kontaktadresse

In Oxygen Builder: ein Shortcode-Element einfügen und den Shortcode eintragen. Überschrift und Einleitungstext baut man wie gewohnt darum herum — dieser Text zählt dann auch für Suchmaschinen.

Aufbau des Editors

Zweispaltig: links der Aufbau, rechts eine mitlaufende Live-Vorschau.

Funnel
└── Schritt (bis zu 12)            per Ziehen sortierbar
    └── Feld (bis zu 12)           ein Feldtyp je Feld
        └── Option (bis zu 12)     nur bei Auswahl-Feldtypen

Feldtypen

Variablen und Platzhalter

Optionen können Variablen setzen, andere Felder lesen sie. So folgt die Zahl der Raumfelder dem gewählten Paket:

Option "Multi-Split Duo"  →  vars: { rooms: 2, included_line: 25, range_max: 45 }
Feld  "Raumgrößen"        →  count: "{{rooms}}"
Feld  "Leitungsweg"       →  min: "{{included_line}}", max: "{{range_max|45}}"

Grenzen

5. Preislogik

Preiswirkungen

Jede Option und jedes preisrelevante Feld hat genau eine Wirkung:

Reihenfolge der Berechnung

1. Grundpreis aus allen wirksamen Grundpreis-Wirkungen
2. Zuschläge in Reihenfolge der Schritte und Felder
3. Prozent rechnet auf den Grundpreis, nicht auf die laufende Summe
4. Gesamt = Grundpreis + Zuschläge, gerundet auf zwei Nachkommastellen

Prüfungs-Kennzeichen

Das Kennzeichen wird gesetzt, sobald eine dieser Bedingungen zutrifft:

• eine gewählte Option hat den Schalter „löst technische Prüfung aus“
• eine Hinweis-Wirkung („Preis nach Prüfung“) ist aktiv
• eine hinterlegte Prüfbedingung trifft zu, etwa „Raum größer als 40 m²“

Es steht dann in der Betreffzeile der E-Mail und im HERO-Logbuch.

Serverseitige Nachrechnung

Ab Version 2.0.0 schickt der Browser die Funnel-Kennung und den Zustand mit. Der Server rechnet mit derselben Definition nach und verwendet seinen Wert für E-Mail und HERO. Weicht der Browserwert um mehr als einen Cent ab, steht das auffällig in der Benachrichtigungs-E-Mail. Anfragen ohne Funnel-Kennung werden wie bisher behandelt — ältere eingebettete Seiten funktionieren also weiter.

6. Design-Bereich

Der Design-Abschnitt sitzt im Funnel-Editor und wirkt je Funnel. Mehrere Funnels mit unterschiedlichem Aussehen können auf derselben Seite stehen.

Wie es technisch funktioniert

Das Frontend-Stylesheet arbeitet mit CSS-Variablen. Der Design-Bereich überschreibt sie am Wurzelelement des Funnels, nicht global:

<div class="ekr" data-ekr-funnel="klima" style="--ekr-orange:#0b6b8a; …">

Nur Abweichungen werden ausgegeben. Ein Funnel ohne eigenen Design-Block erzeugt ein leeres style-Attribut. Die Rückwärtskompatibilität ist damit keine Behauptung, sondern eine leere Zeichenkette.

Kontrastprüfung

Der Editor rechnet Farbpaare nach WCAG durch und warnt bei weniger als 4,5:1 — mit konkretem Text wie „Textfarbe auf Hintergrund: 3,1:1 — zu wenig, empfohlen sind 4,5:1“.

Schriften

Auswählbar sind vier systemeigene Stapel plus ein eigener Stapel für Schriften, die Ihr Theme ohnehin lädt. Keine externen Schriftquellen — Begründung siehe Datenschutz. Ein eigener Stapel wird verworfen, sobald er url(, @import, //, spitze Klammern, Semikolon oder geschweifte Klammern enthält. Das schützt zugleich davor, dass jemand über das Textfeld aus der CSS-Deklaration ausbricht.

7. HERO-Anbindung

Zwei Schnittstellen, unterschiedliche Fähigkeiten

Die Lead-API kennt kein Projekttyp-Feld — über sie angelegte Projekte landen immer im Standard-Projekttyp des Kontos. Nur GraphQL kann den Typ bestimmen.

Wie das Plugin entscheidet

Projekttyp-ID gesetzt?
├── nein  →  Lead-API
└── ja    →  GraphQL
             ├── Erfolg      →  fertig
             └── Fehlschlag  →  Lead-API als Rückfallebene
                                + Hinweis-Mail mit der Fehlermeldung

Der Lead geht in keinem Fall verloren. Er liegt dann nur im Standard-Projekttyp statt im gewünschten.

GraphQL-Ablauf

1. Kontakt per E-Mail suchen
2. Falls nicht vorhanden, anlegen
3. Projekt anlegen mit Projekttyp, Schritt, Gewerk, Adresse und der Konfiguration als Notiz

Selbstkonfigurierend: HERO dokumentiert weder die Eingabefelder für das Anlegen eines Kontakts noch die Filterargumente der Kontaktsuche. Das Plugin liest sie zur Laufzeit aus dem Schema Ihres Kontos und sendet nur Felder, die es wirklich gibt. Die Erkenntnisse werden einen Tag zwischengespeichert.

Einrichten

1. Einstellungen → Preisrechner öffnen
2. „Projekttypen und Gewerke laden“ — reine Leseabfrage, legt nichts an
3. Projekttyp und Gewerk aus den Auswahllisten wählen, speichern
4. „Testprojekt in HERO anlegen“ — legt ein echtes Testprojekt an
5. Testprojekt in HERO wieder löschen

Projektstatus

Die HERO-Dokumentation führt nur fünf Status als für die Lead-API zulässig. Die übrigen existieren im Konto, sind für die Schnittstelle aber nicht zugesichert — vor dem Einsatz einmal testen.

Verhalten, das man kennen sollte

• Dedupliziert wird über die E-Mail-Adresse. Existiert der Kunde schon, hängt HERO das Projekt an den bestehenden Kunden.
• Doppelte Telefonnummern blockieren nichts; HERO ergänzt nur einen Hinweis im Logbuch.
• Gesperrte E-Mail-Domains weist HERO als Fehler ab, ohne HTTP-Fehlercode. Das Plugin prüft deshalb ausdrücklich das Statusfeld der Antwort — ein reiner Statuscode-Check würde solche Leads stillschweigend verlieren.
• Der API-Schlüssel wird auf einen Mitarbeiter ausgestellt. Alle über die Schnittstelle angelegten Projekte erscheinen als von dieser Person erstellt, und das lässt sich nachträglich nicht ändern.

Feldzuordnung

PLZ und Ort sind bewusst getrennte Felder: HERO braucht die PLZ als eigenes Pflichtfeld. Straße und Hausnummer bleiben dagegen zusammen — ein Zerlegen wäre fehleranfällig ohne jeden Nutzen.

8. Sicherheit und Missbrauchsschutz

Der Lead-Endpunkt muss öffentlich erreichbar sein, sonst könnte das Formular ihn nicht aufrufen. Deshalb ist er mehrfach abgesichert:

Rate-Limiting

Das Rate-Limit läuft vor dem Honeypot. Sonst könnte ein Bot beliebig oft anklopfen, ohne Budget zu verbrauchen.

Proxy-Header werden nur ausgewertet, wenn die Proxy-Konstante gesetzt ist. Header wie X-Forwarded-For kann jeder in seiner eigenen Anfrage frei setzen. Ohne echten Proxy aktiviert, wäre das IP-Limit wirkungslos — jede Anfrage sähe aus wie eine neue IP. Umgekehrt gilt: Kommt später ein Proxy oder Cloudflare davor, muss die Konstante gesetzt werden, sonst sehen alle Besucher wie eine einzige IP aus und werden gemeinsam ausgesperrt.

Festes statt rollierendes Zeitfenster. Wer gebremst wurde, kommt nach Ablauf garantiert wieder rein; weitere Versuche verlängern die Sperre nicht. Sonst sperrt sich ein hektisch klickender Kunde selbst dauerhaft aus. Abgewiesene Anfragen bekommen einen Retry-After-Header.

Editor und REST

Alle Funnel-Routen prüfen die Administratorrechte und den REST-Nonce. Ein nicht angemeldeter Besucher kann Funnels weder lesen noch ändern. Gespeicherte Texte werden beim Ausgeben maskiert, Design-Farbwerte vor der Ausgabe validiert. Ungültige Werte werden verworfen, nicht ersetzt — ein stillschweigend eingesetztes Schwarz wäre schlimmer, weil es niemand bemerkt.

9. Datenschutz

Keine externen Schriften

Es werden keine Schriften von fremden Servern geladen. Kein Google Fonts, kein Adobe Fonts, kein CDN. Grund: Das LG München I hat am 20.01.2022 (Az. 3 O 17493/20) entschieden, dass das dynamische Einbinden von Google Fonts ohne Einwilligung gegen die DSGVO verstößt. Es folgte eine Abmahnwelle. Zulässig sind ausschließlich systemeigene Schriftstapel und selbst gehostete Schriftdateien.

Was das Plugin von außen lädt

Nichts. Alle Skripte, Styles und Schriften kommen vom eigenen Server. Die einzige ausgehende Verbindung geht an HERO — und nur serverseitig, wenn eine Anfrage abgesendet wurde.

Was gespeichert wird

Keine eigenen Datenbanktabellen. Kundendaten werden nicht im Plugin gespeichert — sie gehen per E-Mail raus und nach HERO.

Einwilligung im Formular

Das Kontaktformular enthält eine Pflicht-Checkbox mit Verweis auf Ihre Datenschutzerklärung. Da die Daten automatisch nach HERO fließen, sollte diese die Weitergabe an den Auftragsverarbeiter abdecken.

10. Technische Referenz

REST-Endpunkte

Alle unter dem Namensraum energo/v1.

Nutzlast des Lead-Endpunkts

{
  "funnelId": "klima",
  "state": { "package": "multi2", "line_length": 30, "pump": true },
  "name": "…", "email": "…", "phone": "…",
  "address": "…", "postalCode": "…", "city": "…", "note": "…",
  "website": "", "formStartedAt": 1787170930000,
  "totalValue": 8672.92,
  "pageUrl": "…", "utmSource": "…", "utmMedium": "…", "utmCampaign": "…"
}

website ist der Honeypot und muss leer sein. totalValue ist nur Anzeige — maßgeblich ist, was der Server aus funnelId und state errechnet.

JavaScript-Schnittstellen

window.EnergoFunnel = {
  render(mountElement, definition, options),   // {endpoint, privacyUrl, email, preview}
  calculate(definition, state),                // {base, surcharges[], total, needsReview}
  summaryLines(definition, state),
  boot()
}

window.EnergoDesign = {
  DEFAULTS, PRESETS,
  vars(design),          // nur die Abweichungen von der Vorgabe
  apply(element, design) // setzt und raeumt Inline-Variablen
}

calculate() funktioniert ohne DOM — dadurch lässt sich die Preislogik unabhängig von der Anzeige prüfen.

Ladereihenfolge

Die Plugin-Bausteine werden in fester Reihenfolge geladen: Vorgaben → Datenhaltung → Design → Mehrfunnel-Betrieb → REST → Editor → Design-Oberfläche → Lizenz. Jede Datei wird abgesichert geladen; fehlt ein Baustein, läuft der Lead-Endpunkt auf dem einfachen Weg weiter.

11. Fehlersuche

„Diese Plugindatei existiert nicht“

Meist ein doppelter Ordner — der Plugin-Ordner liegt noch einmal in sich selbst. Per FTP prüfen und den inneren Ordner eine Ebene hochziehen. Zweite Ursache: ein veralteter Aktivierungs-Link aus dem Browserverlauf. Die Plugin-Seite frisch über das Menü aufrufen, nicht die Fehlerseite neu laden — ein Reload schickt dieselbe fehlerhafte Anfrage erneut.

Der Rechner erscheint unformatiert

Das Stylesheet wird zu spät ausgeliefert. Ab Version 1.5.1 meldet das Plugin CSS und JavaScript bereits beim Seitenaufbau an, inklusive Erkennung für Oxygen, das Seiteninhalte in eigenen Meta-Feldern ablegt. Kommt es trotzdem vor: Cache leeren und einmal hart neu laden.

Gewerk steht auf „UNB“

Es fehlt die numerische Gewerk-ID. Das Kürzel allein nutzt nur die Lead-API; GraphQL braucht die Zahl. In den Einstellungen „Projekttypen und Gewerke laden“ und das Gewerk aus der Auswahlliste wählen — das setzt beides gleichzeitig.

Projekt landet im falschen Projekttyp

Die Anlage lief über die Lead-API, nicht über GraphQL. Entweder ist keine Projekttyp-ID gesetzt, oder GraphQL ist gescheitert. Im zweiten Fall liegt eine Hinweis-Mail mit der genauen Fehlermeldung im Postfach.

Kein HERO-Projekt, aber E-Mail kam an

Genau so ist es gedacht. Die Warn-Mail nennt den Grund. Häufig: falsche IDs, fehlende GraphQL-Rechte am Token, oder eine gesperrte E-Mail-Domain.

Design bleibt nach Vorlagenwechsel stehen

Behoben in 2.1.1 — die gesetzten Variablen werden beim Wechsel abgeräumt.

Preis in der E-Mail weicht vom Rechner ab

Genau dafür gibt es die Meldung. Der Server hat mit derselben Definition nachgerechnet und ein anderes Ergebnis bekommen. Beide Zahlen melden.

Diagnose-Werkzeuge im Backend

12. Versionen