Carbon Footprint + Offset Checkout — Vollständiger Leitfaden

Installation

Carbon Footprint + Offset Checkout ist ein Standard-WooCommerce-Plugin und wie jede andere Erweiterung installierbar.

1. Laden Sie die Datei df-carbon-offset.zip von der DataFirefly-Produktseite herunter.
2. Gehen Sie in Ihrem WordPress-Backend zu Plugins → Installieren → Plugin hochladen.
3. Wählen Sie die ZIP-Datei, klicken Sie auf Jetzt installieren, dann auf Aktivieren.
4. Ein neuer Menüpunkt Carbon Footprint erscheint in der WooCommerce-Seitenleiste.

Bei der Aktivierung werden zwei SQL-Tabellen automatisch angelegt: {prefix}dfcarbon_factors (Emissionsfaktoren) und {prefix}dfcarbon_log (Kompensationsprotokoll). Die ADEME-Datenbank wird sofort mit etwa 25 Faktoren vorbefüllt.

Erstkonfiguration

Das Plugin funktioniert direkt nach der Aktivierung ohne Konfiguration: ADEME-Faktoren sind geladen, das Badge wird auf jeder Produktseite angezeigt, die Kompensation erscheint an der Kasse. Einige initiale Anpassungen liefern aber deutlich präzisere Zahlen.

Allgemeine Einstellungen

Gehen Sie zu Carbon Footprint → Einstellungen. Vier Parameterblöcke:

• Climatiq-API — optional. Leer lassen für einen 100% lokalen Betrieb auf Basis der ADEME-Faktoren.
• Kompensation — Aktivierung des Kassenblocks, Preis pro Tonne (Standard 25 €/t, typischer Markt 15–30 €/t), angezeigter Partner (standardmäßig Gold Standard), Beschreibung für die Kundschaft.
• Transport — Aktivierung der Transportkomponente, durchschnittliche Entfernung in km (Standard 500 km), Transport-Emissionsfaktor (Standard: Straßentransport).
• Anzeige — Badge-Position auf der Produktseite (5 verfügbare Hooks), Stil (Karte, Pille, minimal), Farbe, Hook-Priorität.

Kategoriezuordnung → Faktoren

Das ist der wirkungsvollste Schritt. Gehen Sie zu Carbon Footprint → Zuordnung. Wählen Sie für jede WooCommerce-Produktkategorie den passendsten Emissionsfaktor aus der ADEME-Datenbank.

Aktivierung der Climatiq-API (optional)

Climatiq ist eine Datenbank mit über 80.000 Emissionsfaktoren, feinkörniger als die ADEME Base Empreinte in bestimmten Bereichen (detaillierte Elektronik, Kosmetik nach Komponente, Lebensmittel nach Lieferkette). Wenn Sie einen Schlüssel haben:

1. Erstellen Sie ein Konto auf climatiq.io (kostenlose Stufe für moderate Nutzung verfügbar).
2. Fügen Sie den API-Schlüssel unter Carbon Footprint → Einstellungen → Climatiq-API ein.
3. Klicken Sie auf Verbindung testen, um zu validieren.

Sobald aktiviert, wird die Climatiq-API mit Priorität 2 verwendet (nach einem eventuellen manuellen Produkt-Override) und vor der ADEME-Zuordnung. Jedes Ergebnis wird eine Woche lang zwischengespeichert — keine Zusatzkosten beim Seitenrendering.

Wie die Fußabdruckberechnung funktioniert

Berechnungsprioritäten

Für jedes Produkt bestimmt das Plugin den Fußabdruck über vier Quellen, in dieser strikten Prioritätsreihenfolge:

1. Manueller Produkt-Override — wenn Sie im Tab „Carbon“ der Produktseite einen Wert eingegeben haben (Meta _dfcarbon_kgco2e), wird dieser verwendet. Er schaltet alle anderen Quellen kurz.
2. Climatiq-API — wenn ein API-Schlüssel konfiguriert ist und das Produkt ein abfragbares Gewicht oder eine abfragbare Kategorie hat.
3. ADEME-Faktor über Zuordnung — der der Produktkategorie zugewiesene Faktor, auf das Gewicht angewendet.
4. Allgemeiner Fallback — der Faktor general (4,50 kgCO₂e/kg) auf das Gewicht angewendet, oder ein Pauschalwert, wenn kein Gewicht gesetzt ist.

Das Ergebnis wird über den WordPress-Objektcache (Gruppe dfcarbon_product) zwischengespeichert und bei jeder Produkt- oder Zuordnungsänderung automatisch invalidiert.

Transportkomponente

Wenn aktiviert, wird die Transportkomponente zum Materialfußabdruck hinzugefügt:

gesamter_fußabdruck = material_fußabdruck + (gewicht_kg × entfernung_km × transportfaktor_tkm)

Der Standard-Straßentransportfaktor beträgt 0,105 kgCO₂e pro Tonnenkilometer (ADEME-Quelle, durchschnittlicher schwerer LKW). Sie können den Transportfaktor in den Einstellungen ändern oder auf einen anderen Faktor (Seetransport, Luft usw.) umschalten, wenn Sie einen zur Datenbank hinzufügen.

Enthaltene ADEME-Emissionsfaktoren

Das Plugin wird mit etwa 25 vorab geladenen Faktoren aus der ADEME Base Empreinte (Frankreich) geliefert. Hauptabgedeckte Sektoren:

• Textil — Standard-Kleidungsstück, Baumwolle, Wolle, Synthetik, Schuhe
• Elektronik — Smartphone, Laptop, Kleingeräte, Großgeräte
• Lebensmittel — Rindfleisch, Schwein, Geflügel, Fisch, Milchprodukte, Trockenware
• Kosmetik — Körperpflege, Make-up, Parfümerie
• Wohnen — Holzmöbel, Metallmöbel, Heimtextilien
• Papier — Buch, Zeitschrift, Karton-Verpackung
• Sport — Sportgeräte, Sportbekleidung
• Schmuck — Modeschmuck, Silber, Gold
• Transport — Straßentransport, Seetransport
• Fallback — general (4,50 kgCO₂e/kg)

Sie können Ihre eigenen Faktoren unter Carbon Footprint → Faktoren ansehen, bearbeiten, löschen oder hinzufügen. Jeder Faktor hat: einen eindeutigen Slug, eine Bezeichnung, einen Wert in kgCO₂e/Einheit, eine Einheit (standardmäßig kg), eine Quelle (ADEME, Climatiq, benutzerdefiniert…) und ein Jahr.

Eine Schaltfläche ADEME-Standardwerte neu laden stellt die Originaldatenbank wieder her, ohne Ihre eigenen Einträge zu überschreiben: nur fehlende ADEME-Slugs werden neu eingefügt.

Das Produkt-Badge

Verfügbare Stile

Drei Darstellungen zur Auswahl (unter Einstellungen → Anzeige → Badge-Stil):

• Karte (ausführlich) — vollständiger Block mit Fußabdruck, Quelle, zwei pädagogischen Entsprechungen (Auto-km, Baumjahre) und Kompensationspreis.
• Inline-Pille — kompaktes Badge „🌱 5,2 kg CO₂e“ neben dem Preis.
• Minimaler Text — nur der Wert, ohne Rahmen.

Positionen

Das Badge klinkt sich in einen der Standard-WooCommerce-Hooks ein:

• after_price — direkt nach dem Preis (Standard)
• before_add_to_cart — vor dem „In den Warenkorb“-Button
• after_add_to_cart — nach dem „In den Warenkorb“-Button
• before_meta — vor den Produkt-Metadaten
• after_summary — nach der vollständigen Produktzusammenfassung

Wenn keine dieser Positionen zu Ihrem Theme passt, verwenden Sie den Shortcode [dfcarbon_badge] direkt in einem Template oder Page Builder (Elementor, Divi, Gutenberg…).

Bei bestimmten Produkten ausblenden

Aktivieren Sie im Tab Carbon jeder Produktseite die Checkbox „Badge ausblenden“. Die Fußabdruckberechnung bleibt aktiv (nützlich für Berichte und Kasse), aber die öffentliche Anzeige verschwindet. Praktisch für digitale Produkte, Geschenkgutscheine oder Dienstleistungen.

Kompensation an der Kasse

An der Kasse fügt das Plugin einen Block zwischen Bestellübersicht und Zahlungsmethode ein. Dieser Block enthält:

• Den geschätzten Warenkorb-Fußabdruck (Summe der Fußabdrücke aller Artikel × ihre Mengen)
• Die entsprechenden Kompensationskosten (Fußabdruck × Preis pro Tonne)
• Eine optionale Checkbox „Ja, ich füge X € hinzu, um die Auswirkungen meiner Bestellung zu kompensieren“
• Einen konfigurierbaren Beschreibungstext mit Erwähnung des Partners (Gold Standard, Verra…)

Wenn die Kundschaft die Checkbox anklickt, wird eine dynamische WooCommerce-Gebühr per Hook woocommerce_cart_calculate_fees zum Gesamtbetrag hinzugefügt. Der Zustand wird in der WooCommerce-Session gespeichert (dfcarbon_offset_active) und dann auf der Bestellung über die Metas _dfcarbon_cart_kgco2e, _dfcarbon_offset_active, _dfcarbon_offset_amount und _dfcarbon_offset_provider persistiert.

Dashboard und Berichte

Das Menü Carbon Footprint → Dashboard zeigt globale Indikatoren:

• Gesamtzahl der kompensierten Bestellungen
• Kumulierter, auf Bestellungen gemessener CO₂-Fußabdruck
• Effektiv kompensierter CO₂-Fußabdruck
• Gesamtbetrag, der in Kompensation investiert wurde

Das Menü Carbon Footprint → Berichte detailliert jede kompensierte Bestellung: Datum, Bestellnummer, Bestell-Fußabdruck, kompensierte kg, Betrag, Partner. Diese Tabelle fließt direkt in Ihr nichtfinanzielles CSRD-Reporting oder eine ESG-Audit-Anfrage ein.

Ein Fußabdruck-Snapshot wird auch pro Bestellposition aufbewahrt (Meta _dfcarbon_line_kgco2e): angezeigte Werte ändern sich nicht rückwirkend, wenn Sie später einen ADEME-Faktor bearbeiten.

Verfügbare Shortcodes

Drei öffentliche Shortcodes, um Elemente überall auf Ihrer Website einzubetten:

[dfcarbon_badge id="123" style="card"]

Zeigt das CO₂-Badge eines bestimmten Produkts an. id ist erforderlich, style ist optional (card als Standard, pill, minimal).

[dfcarbon_cart_summary]

Zeigt den aktuellen Warenkorb-Fußabdruck und die Kompensationskosten an. Nützlich in einer benutzerdefinierten „Mein Warenkorb“-Seite oder einem Side-Cart.

[dfcarbon_stats]

Öffentlicher Block mit aggregierten Statistiken: kompensierte Tonnen, Anzahl Bestellungen, investierter Betrag. Perfekt für eine Seite „Unser Klima-Engagement“.

Hooks & Filter für Entwickler

Das Plugin stellt einen Hauptfilter bereit, um die Fußabdruckberechnung vollständig zu überschreiben:

add_filter( 'dfcarbon_product_footprint', function( $footprint, $product_id, $context ) {
    // $footprint ist ein Array: ['kg' => 5.2, 'source' => 'ademe', 'breakdown' => [...]]
    // Geben Sie ein modifiziertes Array zurück, um zu überschreiben
    return $footprint;
}, 10, 3 );

Weitere nützliche Hooks:

• dfcarbon_daily_sync — tägliche WP-Cron-Aktion (löscht Climatiq-Transients)
• dfcarbon_before_offset_fee — Aktion vor dem Hinzufügen der Kompensationsgebühr
• dfcarbon_offset_purchased — Aktion beim Persistieren auf einer Bestellung ausgelöst

Das Plugin verwendet den PHP-Namespace DataFirefly\CarbonOffset. Um einen Faktor programmatisch aus einem mu-plugin oder Child-Theme hinzuzufügen, importieren Sie die Klasse Database:

use DataFirefly\CarbonOffset\Database;

Database::upsert_factor( [
    'slug'   => 'mein-faktor',
    'label'  => 'Mein spezifischer Sektor',
    'value'  => 2.35,
    'unit'   => 'kg',
    'source' => 'Benutzerdefiniert',
    'year'   => 2026,
] );

Mehrsprachig (Polylang / WPML)

Das Plugin ist mit Polylang Pro und WPML kompatibel. Die 5 mitgelieferten Sprachen (FR, EN, ES, DE, IT) befinden sich im Ordner languages/ mit vorkompilierten .po– und .mo-Dateien.

So passen Sie eine Übersetzung an:

1. Installieren Sie Loco Translate (kostenloses Plugin) oder verwenden Sie Poedit lokal.
2. Öffnen Sie den Katalog df-carbon-offset-de_DE.po.
3. Bearbeiten Sie die Einträge.
4. Kompilieren Sie neu zu .mo — automatisch in Loco Translate.

Um eine standardmäßig nicht mitgelieferte Sprache hinzuzufügen (Portugiesisch, Niederländisch…), duplizieren Sie eine bestehende .po, benennen Sie sie in das korrekte Locale um (df-carbon-offset-pt_PT.po, df-carbon-offset-nl_NL.po…), übersetzen und kompilieren Sie.

Deinstallation

Das Plugin räumt bei der Deinstallation gründlich auf, per uninstall.php:

• Löschen der Tabellen dfcarbon_factors und dfcarbon_log
• Löschen der Optionen dfcarbon_settings und dfcarbon_db_version
• Löschen der Postmetas _dfcarbon_* auf allen Produkten und Bestellungen
• Abmelden des Crons dfcarbon_daily_sync
• Löschen der Climatiq-Transients

FAQ

Kann ich einen bestimmten Faktor auf ein Produkt zwingen, ohne seine Kategorie zu ändern?

Ja. Wählen Sie im Tab Carbon der Produktseite einen Faktor im Dropdown „Emissionsfaktor“. Er überschreibt die Kategoriezuordnung nur für dieses Produkt.

Was passiert, wenn mein Produkt kein Gewicht hat?

Die Berechnung nutzt einen Pauschalwert für gewichtslose Produkte (behandelt als „Einheit“). Sie können auch den manuellen Override verwenden, um den Wert direkt in kg CO₂e einzugeben.

Funktioniert das Plugin mit variablen Produkten?

Ja. Der Fußabdruck wird auf Ebene des Elternprodukts berechnet (über sein Gewicht und seine Kategorie), was in den meisten Fällen konsistent ist. Für eine Kontrolle pro Variation nutzen Sie den Filter dfcarbon_product_footprint.

Wie handhabe ich herunterladbare (digitale) Produkte?

Für ein rein digitales Produkt (E-Book, Online-Kurs, Softwarelizenz) aktivieren Sie „Badge ausblenden“ und lassen Sie die Berechnung auf den allgemeinen Fallback zurückfallen (die Auswirkung wird minimal sein, wenn das Produkt kein Gewicht hat). Alternative: verwenden Sie den manuellen Override mit einem kleinen Wert (typisch 0,01 bis 0,1 kg CO₂e für ein E-Book).

Kann ich ein Produkt von der Kompensation an der Kasse ausschließen?

Die Kompensation wird auf den Warenkorb als Ganzes angewendet, nicht Produkt für Produkt. Um ein Produkt vollständig aus der Berechnung auszuschließen, nutzen Sie den Filter dfcarbon_product_footprint und geben ein Array mit ['kg' => 0] zurück.

Macht das Plugin bei jedem Seitenaufruf API-Aufrufe?

Nein. Jeder Produkt-Fußabdruck wird über den WordPress-Objektcache zwischengespeichert. Climatiq-API-Aufrufe (falls aktiviert) werden ihrerseits eine Woche lang als Transients gecacht. Eine Produktseite löst keinen externen Aufruf aus.

Kompatibel mit Caches (WP Rocket, Litespeed, W3TC)?

Ja, vollständig. Das Badge wird serverseitig gerendert. Der dynamische Teil (Kompensations-Checkbox an der Kasse) wird per AJAX gehandhabt und beeinträchtigt den Produktseiten-Cache nicht.