Möchten Sie wissen, welche Kampagnen tatsächlich Spenden generieren? Das Google Analytics Add-on verbindet Ihre Charitable Spendenformulare mit Google Analytics 4, erfasst jedes Spendenereignis und zeigt Ihnen genau, woher Ihre Unterstützer kommen. Es verfolgt sowohl Browser-seitige als auch Server-seitige Conversions, sodass Sie keine Spenden durch PayPal-Weiterleitungen, per Webhook bestätigte Zahlungen oder vom Administrator bestätigte Offline-Spenden verlieren.

Diese Anleitung führt Sie durch die Schritte, um Ihre Charitable-Website mit GA4 zu verbinden, serverseitiges Tracking zu aktivieren, Datenschutzeinstellungen zu konfigurieren und die von Charitable erfassten Daten für jede Spende zu überprüfen.

Hinweis: 
Voraussetzungen: Charitable Pro 1.8.13+
Das Google Analytics Add-on erfordert den Pro-Plan oder höher.

Stellen Sie vor Beginn sicher, dass Charitable Pro auf Ihrer Website installiert und aktiviert ist. Sie benötigen außerdem eine Google Analytics 4-Property mit mindestens einem für Ihre Website konfigurierten Datenstream.

In dieser Anleitung

• Einrichtung des Google Analytics Add-ons
• Aktivierung des serverseitigen Trackings
• Konfiguration von Zustimmung und Datenschutz
• Ausschluss von internem Traffic
• Testen Ihrer Verbindung
• Überprüfung von Spenderquellen-Daten in WordPress
• Verständnis der von Charitable getrackten Ereignisse
• Anzeigen Ihrer Daten in GA4
• Testen der Funktion
• Fehlerbehebung
• Filter
• Aktionen
• Spenden-Metaschlüssel
• Cookie-Namen
• Einstellungsoptionsschlüssel
• Konstanten
• Häufige Rezepte
• Reihenfolge der Hook-Auslösung
• Häufig gestellte Fragen

Einrichtung des Google Analytics Add-ons

Nachdem Sie das Add-on installiert und aktiviert haben, werden die GA4-Einstellungen zum erweiterten Einstellungsbereich von Charitable hinzugefügt. Um sie zu öffnen, gehen Sie zu Charitable » Einstellungen » Erweitert in Ihrem WordPress-Adminbereich.

Sie benötigen Ihre GA4-Mess-ID, die mit G- beginnt, gefolgt von einer Zeichenkette aus Buchstaben und Zahlen. Um sie zu finden, melden Sie sich bei Ihrem Google Analytics -Konto an, öffnen Sie Admin » Datenstreams und wählen Sie Ihren Webstream aus. Die Mess-ID wird in der oberen rechten Ecke der Detailseite des Streams angezeigt.

Zurück in Ihrem WordPress-Adminbereich fügen Sie die Mess-ID in das Feld Google Analytics ein und klicken Sie dann unten auf der Seite auf Änderungen speichern.

Hinweis: Das Add-on prüft, ob die Mess-ID mit G- beginnt. Wenn Sie versehentlich eine Google Tag Manager-Container-ID (die mit GTM- beginnt) oder eine ältere Universal Analytics-Property-ID (UA-) einfügen, funktioniert das Tracking nicht. Das aktuelle GA4-Format ist das einzige unterstützte.

Aktivierung des serverseitigen Trackings

Browser-seitiges Tracking mit gtag.js funktioniert gut, wenn Spender die Zahlung auf Ihrer Website abschließen und die Spendenquittungsseite erreichen. Aber viele Spenden werden an Orten abgeschlossen, die der Browser nicht sehen kann: eine PayPal-Standard-Weiterleitung, bei der der Spender den Tab schließt, ein Stripe-Webhook, der die Zahlung Stunden später bestätigt, oder ein Administrator, der eine Offline-Spende manuell als bezahlt markiert. Ohne serverseitiges Tracking erreichen diese Spenden niemals Google Analytics.

Charitables serverseitiges Tracking sendet ein bestätigtes purchase -Ereignis an GA4 in dem Moment, in dem sich der Spendenstatus zu Bezahlt ändert, unabhängig davon, ob der Browser des Spenders beteiligt ist. Derselbe Pfad löst auch ein refund -Ereignis aus, wenn eine Spende zurückerstattet wird.

Um serverseitiges Tracking zu aktivieren, benötigen Sie ein Measurement Protocol API-Geheimnis von Ihrer GA4-Property. Um eines zu erstellen, melden Sie sich bei Google Analytics an, öffnen Sie Admin » Datenströme, wählen Sie Ihren Webstream aus, scrollen Sie nach unten zu Measurement Protocol API-Geheimnisse und klicken Sie auf Erstellen. Geben Sie dem Geheimnis einen Spitznamen, damit Sie es später identifizieren können.

Sobald Sie das Geheimnis haben, kopieren Sie seinen Wert, kehren Sie zu Charitable » Einstellungen » Erweitert zurück und fügen Sie es in das Feld GA4 Measurement Protocol API Secret ein. Speichern Sie Ihre Änderungen.

Hinweis: Das API-Geheimnis ist optional. Wenn Sie es leer lassen, verfolgt Charitable weiterhin On-Site-Spenden über den Browser. Der serverseitige Pfad wird nur aktiviert, wenn sowohl die Mess-ID als auch das API-Geheimnis festgelegt sind.

Serverseitiges und browserseitiges Tracking teilen sich ein Idempotenz-Flag, sodass eine Spende, die On-Site abgeschlossen und per Webhook bestätigt wird, nur ein purchase -Ereignis in GA4 auslöst – niemals zwei. Der erste Pfad, der ausgelöst wird, gewinnt.

Konfiguration von Zustimmung und Datenschutz

Das Addon bietet vollständige Unterstützung für Google Consent Mode v2, was für den Datenverkehr aus dem Europäischen Wirtschaftsraum gemäß den Durchsetzungsregeln von Google vom März 2024 erforderlich ist. Ohne diese verschwinden Spender, die der Analysezustimmung verweigern, vollständig aus GA4. Mit dieser Funktion empfängt GA4 weiterhin modellierte Conversions und cookielose Pings.

Der Zustimmungsstatus wird im Seitenkopf gesendet, bevor gtag.js geladen wird, mit allen vier erforderlichen Signalen: analytics_storage, ad_storage, ad_user_data und ad_personalization. Die Werte stammen von der Consent-Management-Plattform, die Sie installiert haben.

Zustimmungsintegrationseinstellung

Im erweiterten Einstellungsbereich sehen Sie unter dem Feld für das API-Geheimnis ein Kontrollkästchen Zustimmungsintegration. Diese Einstellung steuert, wie das Addon über das WP Consent API -Framework mit Ihrem CMP kommuniziert, das von Cookiebot, CookieYes, Complianz, Iubenda, OneTrust und den meisten anderen wichtigen Zustimmungs-Plugins unterstützt wird.

• Aktiviert (Standard) – das Addon prüft zum Zeitpunkt der Spende wp_has_consent('statistics') und löst nur dann serverseitige Ereignisse für Spender aus, die der Analysezustimmung zugestimmt haben. Wählen Sie diese Option, wenn Sie ein CMP installiert haben und möchten, dass serverseitige Ereignisse die Zustimmung des Spenders berücksichtigen.
• Deaktiviert – das Addon ignoriert den Zustand der WP Consent API und löst für jede abgeschlossene Spende serverseitige Ereignisse aus. Wählen Sie diese Option nur, wenn Sie kein CMP haben oder wenn Ihr Rechtsteam bestätigt hat, dass Spenderdaten ohne Analysezustimmung an Google gesendet werden können.

Der Einwilligungsstatus wird in dem Moment erfasst, in dem die Spende erstellt wird, und im Spenden-Datensatz gespeichert. Das bedeutet, dass ein Spender, der später seine Meinung in Ihrem CMP ändert, keine Ereignisse für bereits getätigte Spenden rückwirkend blockiert – der Schnappschuss zum Zeitpunkt der Spende ist für diese Spende maßgeblich.

IP-Anonymisierung

IP-Adressen von Spendern werden immer anonymisiert, bevor sie an Google gesendet werden. Charitable kürzt IPv4-Adressen auf /24 (die letzte Oktett wird auf Null gesetzt) und IPv6-Adressen auf /48 (die letzten 80 Bits werden auf Null gesetzt), bevor sie als ip_override -Parameter an GA4 übergeben werden.

Das Ergebnis: Google kann Spender auf Länder- und Regionsebene lokalisieren – nützlich für die Spenden-Attribution –, aber niemals die genaue IP eines Spenders sehen. Die vollständige IP wird auch nie in Ihrer WordPress-Datenbank gespeichert.

Ausschluss von internem Traffic

Wenn Ihr Team sich anmeldet, um Kampagnen zu testen oder Spenden zu verwalten, möchten Sie wahrscheinlich nicht, dass deren Browsing-Aktivitäten in GA4 neben echten Spenderdaten angezeigt werden. Das Feld Tracking für Rollen ausschließen ermöglicht es Ihnen, das Tracking für angemeldete Benutzer mit bestimmten Rollen vollständig zu überspringen.

Suchen Sie in den erweiterten Einstellungen nach Tracking für Rollen ausschließen und aktivieren Sie die Kontrollkästchen für alle Rollen, die Sie ausschließen möchten. Gängige Optionen sind Administrator und Redakteur für ein kleines Team oder nur Administrator, wenn Spendenmitarbeiter getrackt werden sollen. Speichern Sie Ihre Änderungen.

Für ausgeschlossene Benutzer lädt das Add-on gtag.js nicht im Frontend und löst keine Ereignisse aus. Abgemeldete Besucher und Benutzer in nicht ausgewählten Rollen werden normal getrackt.

Testen Ihrer Verbindung

Die größte Quelle der Verwirrung bei jeder Analyseintegration ist: „Habe ich das richtig konfiguriert?“ Das Add-on enthält einen Ein-Klick-Test, der ein echtes Ereignis an GA4 mit aktiviertem Debug-Modus sendet und dann das Ergebnis inline meldet.

Scrollen Sie in Charitable » Einstellungen » Erweitert zum Abschnitt GA4-Verbindung testen und klicken Sie auf Testereignis an GA4 senden.

Die Schaltfläche führt nacheinander zwei Dinge aus. Erstens sendet sie Ihre Nutzdaten an den Debug-Endpunkt von GA4, der die Struktur validiert und ungültige Mess-IDs oder API-Schlüssel mit einer aussagekräftigen Fehlermeldung ablehnt. Zweitens sendet sie dasselbe Ereignis mit aktiviertem debug_mode an den Live-Endpunkt von GA4, sodass das Ereignis innerhalb weniger Sekunden in GA4 » Admin » DebugView erscheint.

Wenn der Test erfolgreich ist, sehen Sie ein grünes Häkchen mit einer Bestätigungsnachricht, die das Testereignis benennt (charitable_test_event). Wenn er fehlschlägt, teilt Ihnen die Nachricht mit, warum – die häufigsten Ursachen sind ein ungültiger API-Schlüssel, ein Tippfehler in der Mess-ID oder ein Netzwerkverbindungsproblem zwischen Ihrem Server und Google.

Das Testereignis ist harmlos. Es verwendet eine synthetische Client-ID, sodass es in Ihren Standardberichten nicht neben echten Spenderdaten angezeigt wird.

Überprüfung von Spenderquellen-Daten in WordPress

Jede Spende in Ihrem Charitable-Admin zeigt ein Google Analytics -Panel in der rechten Seitenleiste des Bearbeitungsbildschirms für Spenden an. Das Panel wird nur angezeigt, wenn Daten für diese Spende erfasst wurden. Ältere Spenden von vor der Installation des Add-ons zeigen es daher nicht an.

Das Panel gruppiert die erfassten Daten in vier Abschnitte:

• Quelle (UTM) – zeigt die Werte utm_source, utm_medium, utm_campaign, utm_term, utm_content und utm_id aus der URL an, über die der Spender Ihre Website erreicht hat. Angezeigt werden nur Felder mit erfassten Werten.
• GA4-Sitzung – zeigt die GA4-Client-ID und die Sitzungs-ID des Spenders an, die aus dem _ga -Cookie zum Zeitpunkt der Spende ausgelesen wurden. Diese ermöglichen es Ihnen, die Spende in GA4-Berichten abzugleichen, wenn Sie eine bestimmte Transaktion untersuchen müssen.
• Zustimmung bei Eingabe – zeigt den Zustand der WP Consent API des Spenders für die Kategorien statistics und marketing zum Zeitpunkt der Spende an. Nützlich für Compliance-Audits.
• Ausgelöste GA4-Ereignisse – zeigt den Zeitstempel an, zu dem die Ereignisse purchase und (falls zutreffend) refund an GA4 gesendet wurden. Wenn eine Spende keinen purchase -Zeitstempel hat, bedeutet dies, dass das Ereignis noch nicht gesendet wurde (noch ausstehend) oder durch Ihre Einstellungen für Zustimmung oder Rollenausschluss unterdrückt wurde.

Das Panel wird standardmäßig zusammengeklappt geladen, um den Bearbeitungsbildschirm für Spenden übersichtlich zu halten. Klicken Sie auf die Titelleiste von Google Analytics , um es zu erweitern. WordPress merkt sich Ihre Präferenz pro Benutzer.

UTM-Tagging Ihrer Kampagnen

Damit der Abschnitt Quelle (UTM) Daten erfassen kann, muss der Spender über eine URL, die UTM-Parameter enthält, auf Ihre Website gelangen. Eine typische Kampagnen-URL könnte so aussehen:

https://example.org/donate/?utm_source=email&utm_medium=newsletter&utm_campaign=spring-2026

Sie würden diesen Link in Ihrer Spenden-E-Mail anstelle der reinen URL der Spendenseite senden. Wenn der Spender darauf klickt, speichert Charitable diese UTM-Werte in einem First-Party-Cookie, das 30 Tage lang gültig ist. Wann immer er innerhalb dieses Zeitfensters spendet, werden die UTM-Werte dem Spenden-Datensatz zugeordnet und als source -, medium - und campaign -Ereignisparameter an GA4 weitergeleitet.

Standardmäßig verwendet das Add-on Last-Touch-Attribution: Wenn der Spender mit einem Satz von UTMs besucht, dann später mit einem anderen Satz, gewinnt der aktuellste Satz. Entwickler können mit dem Filter charitable_google_analytics_utm_first_touch zu First-Touch-Attribution wechseln.

Verständnis der von Charitable getrackten Ereignisse

Charitable löst zu verschiedenen Zeitpunkten im Spendenlebenszyklus die folgenden GA4-Ereignisse aus. Alle erscheinen automatisch in Ihren GA4-Berichten – es ist keine benutzerdefinierte Ereigniskonfiguration auf der GA4-Seite erforderlich.

• purchase – wird ausgelöst, wenn eine Spende als bezahlt bestätigt wird. Sendet Standard-GA4-E-Commerce-Felder: transaction_id (die Spenden-ID), value, currency und ein items[] -Array mit der Kampagne als einzelnem Artikel, kategorisiert als Recurring (wiederkehrend) oder One-Time (einmalig).
• refund – wird ausgelöst, wenn eine Spende als erstattet markiert wird. Stimmt mit der transaction_id des ursprünglichen purchase -Events überein, sodass GA4 die beiden automatisch verknüpft. Der Nettoumsatz in Ihren GA4-Berichten bleibt korrekt.
• sign_up – wird ausgelöst, wenn ein Spender ein WordPress-Benutzerkonto auf Ihrer Website erstellt. Das Event enthält eine gehashte Kennung, sodass spätere Spenden desselben Spenders über verschiedene Browser und Geräte hinweg derselben Person zugeordnet werden.
• login – wird ausgelöst, wenn sich ein wiederkehrender Spender anmeldet. Nützlich für die Berichterstattung zur Kundenbindung in GA4.
• donation_button_click und donate_now_click – Klick-Events nur im Browser für ein Signal am Anfang des Funnels. Sie werden ausgelöst, wenn ein Spender auf eine Spenden-Schaltfläche klickt, bevor das Formular abgeschickt wurde.

Spenden, die im Testmodus von Charitable getätigt werden, werden mit test_mode: true in den Event-Parametern gekennzeichnet, sodass Sie sie aus Ihren Berichten herausfiltern können. Um dies in GA4 zu tun, erstellen Sie einen Vergleich oder eine Zielgruppe, die Events ausschließt, bei denen test_mode gleich true ist.

Anzeigen Ihrer Daten in GA4

Sobald Sie eine Testspende getätigt haben (oder eine echte erhalten haben), gibt es in Google Analytics drei Stellen, an denen Sie die Daten überprüfen können.

Echtzeit

Der schnellste Weg, um zu bestätigen, dass das Tracking funktioniert. Öffnen Sie in Ihrer GA4-Property Berichte » Echtzeit. Innerhalb von etwa 30 Sekunden nach Abschluss einer Spende sehen Sie das purchase -Event in der Karte Ereignisanzahl nach Ereignisname auf der rechten Seite. Klicken Sie auf einen beliebigen Ereignisnamen, um seine Parameter zu untersuchen.

DebugView

Für eine schrittweise Überprüfung eines bestimmten Events öffnen Sie Admin » DebugView. Mit debug_mode gekennzeichnete Events werden hier in Echtzeit mit vollständigen Parameterdetails angezeigt. Die Schaltfläche Testverbindung kennzeichnet ihre Events automatisch für DebugView, und Sie können den Debug-Modus auch website-weit aktivieren, indem Sie define('CHARITABLE_DEBUG', true); zu Ihrer wp-config.php hinzufügen.

Standardberichte

Für die Umsatzanalyse ist der nützlichste Bericht Berichte » Monetarisierung » E-Commerce-Käufe. Dieser Bericht aggregiert Ihre purchase -Events zu Umsatzzahlen, aufgeschlüsselt nach Kampagne (dem item_name), Kategorie (wiederkehrend vs. einmalig) und Datum. Rückerstattungen werden dank der Transaktions-ID-Übereinstimmung von GA4 automatisch abgezogen. Standardberichte werden innerhalb von 24 bis 48 Stunden gefüllt.

Für die Analyse der Traffic-Quelle sehen Sie unter Berichte » Akquisition » Traffic-Akquisition nach. Ihre mit UTM getaggten Kampagnen werden als separate Zeilen angezeigt, mit Umsatz, Conversion-Rate und Engagement-Metriken für jede.

Testen der Funktion

Der schnellste End-to-End-Test ist eine echte Spende über Ihre Website mit einem Test-Gateway wie dem Stripe Testmodus zu tätigen. Nach Abschluss der Spende öffnen Sie die Spende unter Charitable » Spenden, erweitern Sie das Panel Google Analytics und bestätigen Sie, dass der Abschnitt GA4-Ereignisse ausgelöst einen Zeitstempel für purchase anzeigt. Überprüfen Sie dann unter GA4 » Berichte » Echtzeit, ob das Ereignis innerhalb von 30 Sekunden erscheint.

Wenn Sie das Rückerstattungsereignis testen, ändern Sie den Status der Spende in der Spendenliste auf Zurückerstattet. Die Metabox sollte einen Zeitstempel für refund hinzufügen, und GA4 Echtzeit sollte das Ereignis refund innerhalb von 30 Sekunden anzeigen.

Fehlerbehebung

Ereignisse erscheinen nicht in GA4

Wenn Ihre Testspenden nicht in GA4 landen, gehen Sie diese Prüfungen in der angegebenen Reihenfolge durch:

• Stellen Sie unter Charitable » Einstellungen » Erweitert sicher, dass das Feld Google Analytics Ihre Mess-ID und nicht eine GTM-Container-ID oder eine ältere UA-Property enthält.
• Klicken Sie auf die Schaltfläche Testereignis an GA4 senden. Die Fehlermeldung nennt das spezifische Problem (ungültiger API-Schlüssel, ungültige Mess-ID, Netzwerkfehler).
• Prüfen Sie, ob Sie mit einer Rolle angemeldet sind, die Sie unter Tracking für Rollen ausschließen hinzugefügt haben. Ausgeschlossene Benutzer generieren keine Ereignisse, auch nicht beim Testen. Melden Sie sich ab und versuchen Sie es in einem Inkognito-Fenster.
• Deaktivieren Sie alle Browser-Werbeblocker (uBlock Origin, AdBlock Plus, Brave Shields) für Ihre Domain. Sie blockieren das Laden von gtag.js im Frontend.

Site Kit von Google ist bereits aktiv

Wenn Sie Google Site Kit installiert und mit Ihrer GA4-Property verbunden haben, verzögert Charitable das Laden von gtag.js an Site Kit. Dies verhindert, dass die Seite das GA4-Skript doppelt lädt. Die Spendenereignisse werden weiterhin über die gtag-Instanz von Site Kit ausgelöst.

Wenn Sie Site Kit installiert, aber das Analytics-Modul nicht verbunden haben, ist die Verzögerung von Charitable unnötig. Entwickler können sie überschreiben, indem sie false vom Filter charitable_google_analytics_is_ga4_loaded zurückgeben.

Hinweis zu Konflikten bei der GTM-Konversionsverfolgung von Charitable

Wenn Sie das Addon Charitable Conversion Tracking installiert und eine GTM-Container-ID konfiguriert haben, zeigt Charitable auf den Einstellungsseiten von Charitable eine Admin-Meldung an, die erklärt, dass gtag.js unterdrückt wird. Dies ist beabsichtigt – Ihr GTM-Container soll GA4 selbst laden, und das Laden von gtag.js darüber würde Seitenaufrufe doppelt zählen.

Wenn Ihr GTM-Container kein GA4-Tag enthält, ist diese Unterdrückung für Ihre Einrichtung nicht korrekt. Überschreiben Sie sie mit dem charitable_google_analytics_is_ga4_loaded -Filter.

Serverseitige Ereignisse werden nicht ausgelöst

Serverseitiges Tracking wird nur aktiviert, wenn sowohl die Mess-ID als auch das Geheimnis der Measurement Protocol API festgelegt sind. Wenn Ihre refund-Ereignisse oder Spenden von externen Websites nicht in GA4 erscheinen, aber Spenden von der Website schon, fehlt wahrscheinlich das API-Geheimnis oder es ist ungültig. Verwenden Sie die Schaltfläche „Verbindung testen“, um dies zu überprüfen.

Wenn das API-Geheimnis festgelegt ist und der Test erfolgreich ist, aber Statusänderungen keine Ereignisse generieren, überprüfen Sie die Metabox „Google Analytics“ der Spende. Der Abschnitt „Einwilligung beim Einfügen“ zeigt möglicherweise statistics: Denied an. In diesem Fall überspringt das Add-on für die Spenden dieses Spenders korrekt serverseitige Ereignisse.

Das ist alles! Sie haben jetzt GA4, das Ihre Charitable-Spenden End-to-End verfolgt, wobei Attributionsdaten sowohl in Google Analytics als auch in Ihrem WordPress-Adminbereich fließen. Sehen Sie als Nächstes Weitere Charitable-Erweiterungen verbinden, um dieses Add-on mit Conversion Tracking für Meta- und TikTok-Pixel oder mit dem Add-on für wiederkehrende Spenden für Abonnementanalysen zu koppeln.

Filter

Das Add-on stellt 12 Filter bereit, die die Loader-Erkennung, die Anpassung der Nutzdaten, die Einwilligung, die Attribuierung und das Hashing von Identitäten abdecken. Die Filter-Namen folgen dem Präfix charitable_google_analytics_* und übergeben den gefilterten Wert als erstes Argument.

charitable_google_analytics_is_ga4_loaded

Ob ein anderes Plugin bereits GA4 auf der Seite lädt. Wenn true zurückgegeben wird, injiziert das Add-on kein eigenes gtag.js , um eine doppelte Ladung zu verhindern. Erkannte Loader sind MonsterInsights, Site Kit by Google und Charitable Conversion Tracking mit einer konfigurierten GTM-Container-ID.

apply_filters( 'charitable_google_analytics_is_ga4_loaded', $is_loaded );

Verwenden Sie dies, wenn Sie einen nicht standardmäßigen GA4-Loader haben (z. B. ein benutzerdefiniertes Theme-Tag), den das Add-on nicht automatisch erkennt. Die Rückgabe von true unterdrückt die Injektion des eigenen gtag.js des Add-ons.

charitable_google_analytics_purchase_payload

Die browserseitige purchase-Ereignis-Nutzlast, die auf der Spendenquittungsseite erstellt wird (Phase A). Wird vor dem Inline-<script>-Block ausgelöst, der im Footer ausgegeben wird.

apply_filters(
    'charitable_google_analytics_purchase_payload',
    array $payload,
    Charitable_Donation $donation
);

Das $payload-Array enthält GA4-E-Commerce-Felder (transaction_id, value, currency, items). Die Rückgabe eines leeren Arrays ([]) überspringt die Auslösung des Ereignisses für diese Spende.

charitable_google_analytics_mp_purchase_payload

Die serverseitige Measurement Protocol purchase-Nutzlast (Phase B). Wird vor dem wp_remote_post()-Aufruf an GA4 ausgelöst.

apply_filters(
    'charitable_google_analytics_mp_purchase_payload',
    array $payload,
    Charitable_Donation $donation
);

Das $payload ist der vollständige MP-Body (client_id, optional user_id, events[]). Die Rückgabe einer Nutzlast mit leeren events überspringt den Aufruf.

charitable_google_analytics_mp_refund_payload

Gleiche Struktur wie mp_purchase_payload, aber ausgelöst vor dem serverseitigen refund-Event-POST.

apply_filters(
    'charitable_google_analytics_mp_refund_payload',
    array $payload,
    Charitable_Donation $donation
);

charitable_google_analytics_mp_signup_payload

Die serverseitige sign_up-Payload, die beim Registrieren eines neuen WordPress-Benutzers erstellt wird.

apply_filters(
    'charitable_google_analytics_mp_signup_payload',
    array $payload,
    WP_User $user
);

Verwenden Sie dies, um Registrierungsereignisse für bestimmte Rollen zu unterdrücken oder benutzerdefinierte Ereignisparameter einzufügen (z. B. Registrierungsquelle).

charitable_google_analytics_mp_login_payload

Die serverseitige login-Payload, die beim Anmelden eines WordPress-Benutzers erstellt wird.

apply_filters(
    'charitable_google_analytics_mp_login_payload',
    array $payload,
    WP_User $user
);

Ein häufiger Anwendungsfall ist das Überspringen von Anmeldeereignissen für Benutzer mit Administratorrechten.

charitable_google_analytics_persist_utm

Ob das Add-on UTM-Parameter aus der Request-URL in First-Party-Cookies bei init beibehalten soll. Standard true.

apply_filters( 'charitable_google_analytics_persist_utm', $persist );

Die Rückgabe von false deaktiviert das Schreiben von UTM-Cookies vollständig. Nützlich für Websites, die die UTM-Persistenz selbst über einen benutzerdefinierten Mechanismus handhaben möchten.

charitable_google_analytics_utm_first_touch

Ob First-Touch-UTM-Attribution anstelle des Standard-Last-Touch verwendet werden soll. Standard false.

apply_filters( 'charitable_google_analytics_utm_first_touch', $first_touch );

Wenn true, wird ein UTM-Cookie nur dann geschrieben, wenn es noch nicht existiert. Die erste UTM, der der Spender zugeordnet wurde, gewinnt für das 30-tägige Cookie-Fenster.

charitable_google_analytics_has_consent

Die Zustimmung für eine bestimmte Kategorie zum Zeitpunkt der Auswertung. Empfängt das Ergebnis der WP Consent API und ermöglicht Ihnen, es zu überschreiben.

apply_filters(
    'charitable_google_analytics_has_consent',
    bool $consent,
    string $category,    // 'statistics' or 'marketing'
    int $donation_id     // 0 in live mode, donation ID in stored mode
);

Der Live-Modus ($donation_id === 0) wird für browserseitiges Gating wie die gtag.js-Injektion verwendet. Der gespeicherte Modus ($donation_id > 0) wird für serverseitige MP-Aufrufe verwendet und liest den beim Einfügen der Spende erfassten Zustimmungsstatus. Die Rückgabe von false unterdrückt das Tracking für diese Kategorie.

charitable_google_analytics_consent_default

Der Standardzustand von Consent Mode v2, der im Dokument-Head ausgegeben wird, bevor gtag.js geladen wird.

apply_filters(
    'charitable_google_analytics_consent_default',
    array $consent_default
);

$consent_default enthält vier Schlüssel: ad_user_data, ad_personalization, ad_storage und analytics_storage, die jeweils auf 'granted' oder 'denied' gesetzt sind. Die Rückgabe von 'granted' für alle vier deaktiviert effektiv die Modellierung von Consent Mode v2 für diesen Seitenaufruf.

charitable_google_analytics_user_id

Die gehashte Benutzer-ID, die den MP-Payloads als user_id hinzugefügt wird. Der Standardwert ist sha256(normalized_email), wobei die E-Mail kleingeschrieben und von Subadressen bereinigt wird.

apply_filters(
    'charitable_google_analytics_user_id',
    string $user_id,
    Charitable_Donation $donation
);

Die Rückgabe eines leeren Strings unterdrückt das Feld user_id vollständig. Der Filter empfängt den endgültigen Hash, nicht die rohe E-Mail – wenn Sie ein anderes Identitätsschema benötigen, geben Sie hier Ihren eigenen stabilen pro-Mensch-Hash zurück.

charitable_google_analytics_client_ip

Die Client-IP, die als Quelle für die IP-Anonymisierung verwendet wird. Standardmäßig REMOTE_ADDR. Websites hinter einem CDN oder Reverse-Proxy, die die echte IP des Spenders in einem weitergeleiteten Header setzen, sollten dies überschreiben.

apply_filters( 'charitable_google_analytics_client_ip', string $ip );

Der zurückgegebene Wert wird dann vor der Übergabe an GA4 als Parameter ip_override auf /24 (IPv4) oder /48 (IPv6) gekürzt.

Aktionen

Das Add-on löst für jeden serverseitigen Measurement Protocol-Aufruf zwei Actions aus – eine bei Erfolg, eine bei Fehler. Beide ermöglichen es Drittanbieter-Integrationen, in Echtzeit auf die GA4-Conversion-Zustellung zu reagieren.

charitable_google_analytics_event_sent

Wird nach einer 2xx-Antwort von mp/collect ausgelöst.

do_action(
    'charitable_google_analytics_event_sent',
    string $event_label,    // e.g. 'purchase', 'refund', 'sign_up', 'login'
    int $donation_id,       // 0 for non-donation events
    array $payload,         // the MP body that was sent
    int $http_code          // typically 204
);

Verwenden Sie dies, um Events an ein CDP wie HubSpot oder Segment zu spiegeln, einen Zapier-Webhook auszulösen, ein Analyse-Dashboard zu aktualisieren oder alles andere, das auf eine bestätigte Conversion reagieren soll.

charitable_google_analytics_event_failed

Wird bei einem Netzwerkfehler (WP_Error-Antwort) oder einem HTTP-Status ungleich 2xx ausgelöst.

do_action(
    'charitable_google_analytics_event_failed',
    string $event_label,
    int $donation_id,
    array $payload,
    string $error           // WP_Error message or 'HTTP <code>'
);

Verwenden Sie dies, um den Betrieb zu benachrichtigen, einen erneuten Versuch über Ihr eigenes Job-System anzustoßen oder auf eine alternative Pipeline zurückzugreifen.

Spenden-Metaschlüssel

Das Add-on speichert alles, was es über eine Spende erfasst, als Standard-WordPress-Post-Meta. Sie können diese direkt mit get_post_meta() oder über WP-CLI's wp post meta get abfragen.

Meta-Schlüssel	Gesetzt von	Typ	Was es enthält
_charitable_ga_client_id	capture_session() bei charitable_after_save_donation	Zeichenkette	Geparste GA4-Client-ID aus dem _ga-Cookie des Spenders beim Einfügen der Spende. Format: <part1>.<part2>.
_charitable_ga_session_id	Dasselbe	Zeichenkette	Geparste GA4-Session-ID aus dem _ga_<container>-Cookie des Spenders.
_charitable_ga_ip_override	Dasselbe	Zeichenkette	Anonymisierte Spender-IP (/24 IPv4 oder /48IPv6).
_charitable_ga_consent_statistics	Dasselbe	'granted' oder nicht gesetzt	WP-Einwilligungs-API-Status für die Statistik-Kategorie beim Einfügen. Leere Metadaten gelten als zulässig.
_charitable_ga_consent_marketing	Dasselbe	'granted' oder nicht gesetzt	Dasselbe für Marketing.
_charitable_ga_utm_source	Dasselbe	Zeichenkette	UTM-Quelle aus dem First-Party-Cookie des Spenders (oder $_REQUEST-Fallback).
_charitable_ga_utm_medium	Dasselbe	Zeichenkette	UTM-Medium.
_charitable_ga_utm_campaign	Dasselbe	Zeichenkette	UTM-Kampagne.
_charitable_ga_utm_term	Dasselbe	Zeichenkette	UTM-Begriff.
_charitable_ga_utm_content	Dasselbe	Zeichenkette	UTM-Inhalt.
_charitable_ga_utm_id	Dasselbe	Zeichenkette	UTM-ID.
_charitable_ga_purchase_fired	fire_purchase_event() (Phase A) und fire_purchase_mp() (Phase B)	MySQL-Datum/Uhrzeit-Zeichenkette	Zeitstempel des ersten erfolgreichen purchase-Ereignisses. Wird zwischen Phase A und Phase B geteilt – welches auch immer zuerst ausgelöst wird, setzt ihn.
_charitable_ga_refund_fired	fire_refund_mp()	MySQL-Datum/Uhrzeit-Zeichenkette	Zeitstempel des erfolgreichen refund-Ereignisses. Separat vom Kauf-Flag.

Alle Meta-Schlüssel sind mit einem einzelnen Unterstrich versehen, was bedeutet, dass sie in der Standard-UI für benutzerdefinierte Felder auf dem Spendenbearbeitungsbildschirm ausgeblendet sind. Sie erscheinen stattdessen im Metabox „Google Analytics“ des Add-ons.

Cookie-Namen

Das Add-on schreibt die folgenden Cookies im Browser des Spenders:

• charitable_ga_utm_source, charitable_ga_utm_medium, charitable_ga_utm_campaign, charitable_ga_utm_term, charitable_ga_utm_content, charitable_ga_utm_id – First-Party-Cookies, die bei init gesetzt werden, wenn ein UTM-Parameter in der Anfrage-URL vorhanden ist. Lebensdauer 30 Tage, Pfad /, SameSite Lax, Secure wenn SSL aktiv ist.

Es liest auch diese Cookies, die von gtag.js selbst gesetzt wurden:

• _ga – GA4 client_id Quelle
• _ga_<container> – GA4 session_id Quelle. Der <container>-Teil ist die Mess-ID ohne das führende G-.

Einstellungsoptionsschlüssel

Die Einstellungen des Add-ons befinden sich in der WordPress-Option charitable_settings. Sie können sie über charitable_get_option( $key, $default ) lesen:

Optionsschlüssel	Typ	Standard	Beschreibung
ga4_tracking_id	Zeichenkette	''	Die GA4-Mess-ID (G-XXXXXXXXXX).
ga4_mp_api_secret	Zeichenkette	''	Das Measurement Protocol API-Geheimnis. Erforderlich für serverseitiges Tracking.
ga4_consent_integration	bool	1	Ob der Status der WP Consent API berücksichtigt werden soll.
ga4_excluded_roles	string[]	[]	Array von Rollen-Slugs, die vom Tracking ausgeschlossen werden sollen.

Konstanten

Zwei WordPress-Konstanten ändern das Laufzeitverhalten des Add-ons:

• CHARITABLE_DEBUG (true/false) – wenn true, schreibt das Add-on schrittweise Breadcrumbs in Tools » Logs mit source: google-analytics und fügt debug_mode: 1 zu allen GA4 MP-Ereignis-Payloads hinzu, damit sie in GA4 » Admin » DebugView erscheinen. Definieren Sie in wp-config.php für Entwicklungsseiten.
• SCRIPT_DEBUG (true/false) – wenn true, bindet das Add-on die unminifizierte charitable-google-analytics.js Quelldatei anstelle des minifizierten Produktions-Builds ein. Nützlich beim Debuggen von Frontend-Verhalten.

Häufige Rezepte

UTM-Attribution von Last-Touch auf First-Touch umstellen

add_filter( 'charitable_google_analytics_utm_first_touch', '__return_true' );

Der erste UTM, dem der Spender innerhalb des 30-tägigen Cookie-Fensters zugeordnet wurde, bleibt bestehen. Nachfolgende Besuche mit anderen UTMs werden ignoriert.

Erfassen der echten IP des Spenders hinter Cloudflare

add_filter( 'charitable_google_analytics_client_ip', function( $ip ) {
    if ( ! empty( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ) {
        $candidate = sanitize_text_field( wp_unslash( $_SERVER['HTTP_CF_CONNECTING_IP'] ) );
        if ( filter_var( $candidate, FILTER_VALIDATE_IP ) ) {
            return $candidate;
        }
    }
    return $ip;
} );

Die zurückgegebene IP wird immer noch auf /24 (IPv4) oder /48 (IPv6) anonymisiert, bevor sie an GA4 gesendet wird – der Filter ändert nur, welche IP anonymisiert wird.

Jede bestätigte Spende an ein CDP spiegeln

add_action( 'charitable_google_analytics_event_sent',
    function( $event_label, $donation_id, $payload, $http_code ) {
        if ( 'purchase' !== $event_label ) {
            return;
        }
        // POST to your CDP, fire a Zapier webhook, etc.
        wp_remote_post( 'https://cdp.example.com/events', array(
            'body'    => wp_json_encode( $payload ),
            'headers' => array( 'Content-Type' => 'application/json' ),
            'timeout' => 5,
        ) );
    },
    10,
    4
);

Sowohl erfolgreiche als auch fehlgeschlagene Ereignisse lösen Aktionen aus, sodass Sie fehlgeschlagene Ereignisse auch über Ihr eigenes Job-System erneut versuchen können.

Anmeldeereignisse für Administratoren überspringen

add_filter( 'charitable_google_analytics_mp_login_payload',
    function( $payload, $user ) {
        if ( user_can( $user, 'manage_options' ) ) {
            return array_merge( $payload, array( 'events' => array() ) );
        }
        return $payload;
    },
    10,
    2
);

Ein leeres events Array weist das Add-on an, den MP-Aufruf zu überspringen, ohne andere Ereignistypen zu stören.

Fügen Sie jedem Kauf einen benutzerdefinierten Ereignisparameter hinzu

add_filter( 'charitable_google_analytics_mp_purchase_payload',
    function( $payload, $donation ) {
        if ( ! empty( $payload['events'][0]['params'] ) ) {
            $payload['events'][0]['params']['organization_id'] = '12345';
        }
        return $payload;
    },
    10,
    2
);

Verwenden Sie dies für Multi-Organisation-WordPress-Installationen, bei denen jede Spende ein Organisations-Tag für die GA4-Segmentierung tragen sollte.

Überschreiben Sie die Spender-user_id mit Ihrem eigenen Identitätsschema

add_filter( 'charitable_google_analytics_user_id',
    function( $hashed_email, $donation ) {
        $crm_id = get_post_meta( $donation->ID, '_my_crm_donor_id', true );
        if ( $crm_id ) {
            return hash( 'sha256', 'crm:' . $crm_id );
        }
        return $hashed_email;
    },
    10,
    2
);

Der Filter empfängt den Standard-Hash des Add-ons; Sie können ihn durch Ihren eigenen stabilen Hash pro Person ersetzen. Die Rückgabe eines leeren Strings unterdrückt das user_id Feld vollständig.

Reihenfolge der Hook-Auslösung

Für einen typischen Spendenfluss, der auf der Website abgeschlossen wird, werden die relevanten Hooks in dieser Reihenfolge ausgelöst:

1. init (Priorität 10) – charitable_google_analytics_persist_utm() schreibt UTM-Cookies, wenn die Anfrage-URL UTM-Parameter enthält.
2. wp_head (Priorität 1) – der Inline-Consent-Modus v2-Standard und das gtag.js Skript-Tag werden ausgegeben, gesteuert durch charitable_google_analytics_is_ga4_loaded und die Rollenausschlussprüfung.
3. wp_footer (Priorität 1) – die gtag('js') und gtag('config') Aufrufe werden ausgegeben.
4. Spender reicht das Spendenformular ein. Der AJAX- oder Redirect-gesteuerte Gateway-Fluss wird ausgeführt.
5. charitable_after_save_donation (Priorität 10) – capture_session() liest die Cookies des Spenders und speichert GA4-Clientid, sessionid, anonymisierte IP, UTM-Werte und den Einverständnisstatus als Spenden-Meta.
6. Gateway bestätigt die Zahlung (synchron für On-Site, per Webhook für Off-Site).
7. charitable_donation_status_changed (Priorität 10) – fire_purchase_mp() sendet das serverseitige purchase-Ereignis per POST. Die Aktion charitable_google_analytics_event_sent wird bei Erfolg ausgelöst.
8. charitable_donation_receipt_page (nur Browser) – fire_purchase_event() fügt einen wp_footer-Callback hinzu, der das Inline-gtag('event', 'purchase', ...)-Skript sendet. Das Meta-Feld _charitable_ga_purchase_fired wird innerhalb dieses wp_footer-Callbacks gesetzt (nicht synchron), damit die E-Mail-Darstellung der Quittung das Idempotenz-Flag nicht auslöst.

Für eine Rückerstattung: Schritt 7 oben wird erneut ausgelöst mit new_status === 'charitable-refunded', und fire_refund_mp() sendet das refund-Ereignis per POST.

Für eine Anmeldung oder einen Login: Nur die Schritte 1, 2, 3 oben gelten für den Browserkontext. Die Schritte 5-8 werden durch user_register oder wp_login ersetzt, die fire_signup_mp() bzw. fire_login_mp() auslösen.

Das war's! Sie haben nun die vollständige Hook-Oberfläche für das Charitable Google Analytics Addon. Sehen Sie sich als Nächstes den Vollständigen Leitfaden zu Google Analytics in Charitable für Setup- und Administrationsdokumentation an oder das Charitable Entwicklerdokumentations-Hub für Hooks im Rest von Charitable.

Häufig gestellte Fragen

F: Funktioniert dies mit PayPal Standard oder anderen externen Gateways?

A: Ja, solange Sie das GA4 Measurement Protocol API Secret konfiguriert haben. Der serverseitige Pfad von Charitable erfasst jede Spende, die zu Paid wechselt, unabhängig davon, ob der Browser des Spenders jemals auf Ihre Website zurückgekehrt ist.

F: Ist dies DSGVO-konform?

A: Charitable unterstützt die DSGVO- und EWR-Konformität durch Google Consent Mode v2 und das WP Consent API-Framework. Spender-IPs werden vor der Übertragung anonymisiert, und Spender-E-Mails werden zu einem unidirektionalen SHA-256-Digest gehasht, bevor sie zur GA4-Benutzer-ID werden. Die vollständige E-Mail wird niemals an Google gesendet.

F: Gibt es Konflikte mit Site Kit by Google oder MonsterInsights?

A: Nein. Charitable erkennt beide Plugins automatisch und verzögert das Laden von gtag.js, wenn eines davon aktiv ist, sodass das GA4-Skript nie zweimal auf derselben Seite geladen wird. Spendenereignisse werden weiterhin über den jeweiligen Loader ausgelöst.

F: Wie lange dauert es, bis Ereignisse in den GA4-Berichten angezeigt werden?

A: Echtzeit- und DebugView zeigen Ereignisse innerhalb von etwa 30 Sekunden an. Standardberichte (einschließlich Monetarisierung » E-Commerce-Käufe) werden innerhalb von 24 bis 48 Stunden ausgefüllt.

F: Kann ich meine Mitarbeiter von der Nachverfolgung ausschließen?

A: Ja – verwenden Sie das Feld Tracking für Rollen ausschließen in Charitable » Einstellungen » Erweitert und wählen Sie die WordPress-Rollen aus, die Sie ausschließen möchten. Ausgeschlossene Benutzer überspringen sowohl die browserseitige als auch die rollenbezogene Teile der serverseitigen Nachverfolgung.

F: Werden Spenden im Testmodus von Charitable erfasst?

A: Ja, aber sie werden mit test_mode: true in den Ereignisparametern markiert, sodass Sie sie aus Ihren GA4-Berichten herausfiltern können. Erstellen Sie einen GA4-Vergleich oder ein Publikum, das Ereignisse ausschließt, bei denen test_mode gleich true ist, um Ihre Produktionsberichte sauber zu halten.

F: Sind diese Hooks versionenübergreifend stabil?

A: Alle hier dokumentierten Hooks wurden in Version 1.1.0 eingeführt und sind Teil der öffentlichen API des Addons. Filter- und Aktionssignaturen werden über das @since-Tag im Quellcode versioniert. Breaking Changes werden im Changelog mit einer Deprecation-Meldung in der vorherigen Version angekündigt.

F: Wie deaktiviere ich ein bestimmtes Ereignis vollständig?

A: Verwenden Sie den entsprechenden Payload-Filter und geben Sie ein Array mit leeren events zurück. Um beispielsweise alle serverseitigen refund-Ereignisse zu unterdrücken:

add_filter( 'charitable_google_analytics_mp_refund_payload',
    function( $payload ) {
        return array_merge( $payload, array( 'events' => array() ) );
    }
);

F: Kann ich benutzerdefinierte Dimensionen zu GA4-Ereignissen hinzufügen?

A: Ja. GA4-benutzerdefinierte Dimensionen werden als Ereignisparameter gesendet. Verwenden Sie charitable_google_analytics_mp_purchase_payload (oder den passenden Filter für andere Ereignisse), um Ihren benutzerdefinierten Parameter in $payload['events'][0]['params'] einzufügen. Stellen Sie sicher, dass der Parametername dem „Ereignisparameternamen“ Ihrer benutzerdefinierten Dimension in der GA4-Verwaltung entspricht.

F: Wie teste ich, ob mein benutzerdefinierter Hook ausgelöst wird?

A: Definieren Sie define( 'CHARITABLE_DEBUG', true ); in wp-config.php, überprüfen Sie dann Tools » Logs gefiltert nach Quelle google-analytics. Erfolgreiche MP-Aufrufe protokollieren Info-Level-Einträge. Fügen Sie einen error_log()-Aufruf in Ihren Hook für einmaliges Debugging ein oder verwenden Sie das „Hooks & Actions“-Panel von Query Monitor für eine Live-Ansicht.

F: Funktioniert das Addon mit WP-CLI?

A: Ja. Die UTM-Persistenz wird bei wp_doing_ajax() und CLI-Kontexten übersprungen (keine Cookies zu setzen), aber serverseitige Hooks wie charitable_donation_status_changed werden korrekt ausgelöst, wenn sie über WP-CLI-Befehle aufgerufen werden. Spenden-Metadaten können über wp post meta get <donation-id> _charitable_ga_purchase_fired abgefragt werden.

F: Kann ich das Addon mit eigenen benutzerdefinierten Ereignistypen erweitern?

A: Ja. Der Hilfsfunktion charitable_google_analytics_post_mp_event() ist intern, aber die von ihr ausgelösten Aktionen (event_sent / event_failed) erleichtern das Hinzufügen eigener serverseitiger Ereignistypen. Verbinden Sie Ihre ereignisauslösende Funktion mit der entsprechenden Charitable-Aktion, erstellen Sie den MP-Payload selbst und POSTen Sie an denselben Endpunkt, den das Addon verwendet. Die MP-Anmeldeinformationshilfe charitable_google_analytics_get_mp_credentials() ist ebenfalls öffentlich.