Souhaitez-vous savoir quelles campagnes génèrent réellement des dons ? Le module complémentaire Google Analytics connecte vos formulaires de don Charitable à Google Analytics 4, capture chaque événement de don et vous montre exactement d'où viennent vos supporters. Il suit les conversions côté navigateur et côté serveur, vous évitant ainsi de perdre des dons provenant de redirections PayPal, de paiements confirmés par webhook ou de dons hors ligne confirmés par l'administrateur.

Ce guide vous guidera à travers les étapes pour connecter votre site Charitable à GA4, activer le suivi côté serveur, configurer les options de confidentialité et examiner les données que Charitable capture pour chaque don.

Remarque : 
Prérequis : Charitable Pro 1.8.13+
Le module complémentaire Google Analytics nécessite le plan Pro ou supérieur.

Avant de commencer, assurez-vous que Charitable Pro est installé et activé sur votre site. Vous aurez également besoin d'une propriété Google Analytics 4 avec au moins un flux de données configuré pour votre site web.

Dans ce guide

• Configuration du module complémentaire Google Analytics
• Activation du suivi côté serveur
• Configuration du consentement et de la confidentialité
• Exclusion du trafic interne
• Test de votre connexion
• Examen des données sources de dons dans WordPress
• Comprendre les événements suivis par Charitable
• Visualisation de vos données dans GA4
• Test de la fonctionnalité
• Dépannage
• Filtres
• Actions
• Clés méta de don
• Noms des cookies
• Clés d'options de paramètres
• Constantes
• Recettes courantes
• Ordre de déclenchement des hooks
• Questions fréquemment posées

Configuration du module complémentaire Google Analytics

Une fois le module complémentaire installé et activé, les paramètres GA4 sont ajoutés au panneau des paramètres avancés de Charitable. Pour les ouvrir, accédez à Charitable » Paramètres » Avancé dans votre administration WordPress.

Vous aurez besoin de votre ID de mesure GA4, qui commence par G- suivi d'une chaîne de lettres et de chiffres. Pour le trouver, connectez-vous à votre compte Google Analytics, ouvrez Admin » Flux de données et sélectionnez votre flux web. L'ID de mesure s'affiche dans le coin supérieur droit de la page des détails du flux.

De retour dans votre administration WordPress, collez l'ID de mesure dans le champ Google Analytics et cliquez ensuite sur Enregistrer les modifications en bas de la page.

Remarque : Le module complémentaire vérifie que l'ID de mesure commence par G-. Si vous collez accidentellement un ID de conteneur Google Tag Manager (qui commence par GTM-) ou un ID de propriété Universal Analytics hérité (UA-), le suivi ne fonctionnera pas. Le format GA4 actuel est le seul pris en charge.

Activation du suivi côté serveur

Le suivi côté navigateur avec gtag.js fonctionne bien lorsque les donateurs finalisent le paiement sur votre site et atteignent la page de reçu du don. Mais de nombreux dons se terminent dans des endroits que le navigateur ne peut pas voir : une redirection PayPal Standard où le donateur ferme l'onglet, un webhook Stripe qui confirme le paiement des heures plus tard, ou un administrateur marquant manuellement un don hors ligne comme payé. Sans suivi côté serveur, ces dons n'atteignent jamais Google Analytics.

Le suivi côté serveur de Charitable envoie un événement purchase confirmé à GA4 au moment où le statut d'un don passe à Payé, que le navigateur du donateur soit impliqué ou non. Le même chemin déclenche également un événement refund lorsqu'un don est remboursé.

Pour activer le suivi côté serveur, vous aurez besoin d'un secret d'API Measurement Protocol de votre propriété GA4. Pour en créer un, connectez-vous à Google Analytics, ouvrez Admin » Flux de données, sélectionnez votre flux web, faites défiler jusqu'à Secrets de l'API Measurement Protocol, et cliquez sur Créer. Donnez un surnom au secret pour pouvoir l'identifier plus tard.

Une fois que vous avez le secret, copiez sa valeur, revenez à Charitable » Paramètres » Avancé, et collez-la dans le champ Secret de l'API Measurement Protocol GA4. Enregistrez vos modifications.

Remarque : Le secret de l'API est facultatif. Si vous le laissez vide, Charitable continuera à suivre les dons sur site via le navigateur. Le chemin côté serveur ne s'active que lorsque l'ID de mesure et le secret de l'API sont tous deux définis.

Le suivi côté serveur et côté navigateur partagent un indicateur d'idempotence, de sorte qu'un don qui s'achève sur site et est confirmé par webhook ne déclenchera qu'un seul événement purchase dans GA4 – jamais deux. Le premier chemin à se déclencher l'emporte.

Configuration du consentement et de la confidentialité

Le module complémentaire offre une prise en charge complète de Google Consent Mode v2, qui est requise pour le trafic provenant de l'Espace économique européen en vertu des règles d'application de Google de mars 2024. Sans cela, les donateurs qui refusent le consentement d'analyse disparaissent entièrement de GA4. Avec cela, GA4 reçoit toujours des conversions modélisées et des pings sans cookies.

L'état du consentement est envoyé dans l'en-tête de la page, avant le chargement de gtag.js, avec les quatre signaux requis : analytics_storage, ad_storage, ad_user_data, et ad_personalization. Les valeurs proviennent de la plateforme de gestion du consentement que vous avez installée.

Paramètre d'intégration du consentement

Dans le panneau des paramètres avancés, vous verrez une case à cocher Intégration du consentement sous le champ du secret de l'API. Ce paramètre contrôle la façon dont le module complémentaire communique avec votre CMP via le framework WP Consent API, qui est pris en charge par Cookiebot, CookieYes, Complianz, Iubenda, OneTrust, et la plupart des autres plugins de consentement majeurs.

• Activé (par défaut) – le module complémentaire vérifie wp_has_consent('statistics') au moment du don et ne déclenche des événements côté serveur que pour les donateurs qui ont accordé leur consentement d'analyse. Choisissez cette option si vous avez un CMP installé et souhaitez que les événements côté serveur respectent le consentement du donateur.
• Désactivé – le module complémentaire ignore l'état de la WP Consent API et déclenche des événements côté serveur pour chaque don complété. Choisissez cette option uniquement si vous n'avez pas de CMP, ou si votre équipe juridique a confirmé que les données du donateur peuvent être envoyées à Google sans consentement d'analyse.

L'état du consentement est capturé au moment où le don est créé et stocké dans le dossier du don. Cela signifie qu'un donateur qui change d'avis plus tard dans votre CMP ne bloque pas rétroactivement les événements pour les dons qu'il a déjà effectués – l'instantané au moment du don fait autorité pour ce don.

Anonymisation de l'IP

Les adresses IP des donateurs sont toujours anonymisées avant d'être envoyées à Google. Charitable tronque les adresses IPv4 à /24 (le dernier octet est mis à zéro) et les adresses IPv6 à /48 (les 80 derniers bits sont mis à zéro) avant de les transmettre à GA4 en tant que paramètre ip_override.

Le résultat : Google peut géolocaliser les donateurs au niveau du pays et de la région – utile pour l'attribution des collectes de fonds – mais ne peut jamais voir l'adresse IP exacte d'un donateur. L'adresse IP complète n'est jamais non plus stockée dans votre base de données WordPress.

Exclusion du trafic interne

Si votre équipe se connecte pour tester des campagnes ou gérer des dons, vous ne voudrez probablement pas que sa navigation apparaisse dans GA4 aux côtés du trafic réel des donateurs. Le champ Exclure le suivi pour les rôles vous permet de ne pas suivre du tout les utilisateurs connectés dans des rôles spécifiques.

Dans les paramètres avancés, trouvez Exclure le suivi pour les rôles et cochez les cases des rôles que vous souhaitez exclure. Les choix courants sont Administrateur et Éditeur pour une petite équipe, ou Administrateur uniquement si vous souhaitez que le personnel de collecte de fonds soit suivi. Enregistrez vos modifications.

Pour les utilisateurs exclus, le module complémentaire ne chargera pas gtag.js sur le frontend et ne déclenchera aucun événement. Les visiteurs déconnectés et les utilisateurs dans les rôles non sélectionnés sont suivis normalement.

Test de votre connexion

La plus grande source de confusion avec toute intégration d'analyse est « ai-je correctement configuré cela ? ». Le module complémentaire comprend un test en un clic qui déclenche un événement réel vers GA4 avec le mode débogage activé, puis rapporte le résultat en ligne.

Depuis Charitable » Paramètres » Avancé, faites défiler jusqu'à la section Tester la connexion GA4 et cliquez sur Envoyer un événement de test à GA4.

Le bouton fait deux choses en séquence. Premièrement, il envoie votre charge utile au point de terminaison de débogage de GA4, qui valide la structure et rejette les identifiants de mesure ou les secrets d'API invalides avec une erreur descriptive. Deuxièmement, il envoie le même événement au point de terminaison en direct de GA4 avec debug_mode activé, de sorte que l'événement apparaisse dans GA4 » Admin » DebugView en quelques secondes.

Si le test réussit, vous verrez une coche verte avec un message de confirmation nommant l'événement de test (charitable_test_event). S'il échoue, le message vous expliquera pourquoi – les causes les plus courantes sont un secret d'API invalide, une faute de frappe dans l'identifiant de mesure ou un problème de connectivité réseau entre votre serveur et Google.

L'événement de test est inoffensif. Il utilise un identifiant client synthétique afin de ne pas apparaître aux côtés des données réelles des donateurs dans vos rapports standard.

Examen des données sources de dons dans WordPress

Chaque don dans votre administration Charitable affiche un panneau Google Analytics dans la colonne de droite de l'écran de modification du don. Le panneau n'apparaît que lorsqu'il y a des données capturées pour ce don, donc les dons plus anciens datant d'avant l'installation du module complémentaire ne l'afficheront pas.

Le panneau regroupe les données capturées en quatre sections :

• Source (UTM) – affiche les valeurs utm_source, utm_medium, utm_campaign, utm_term, utm_content, et utm_id de l'URL que le donateur a utilisée pour accéder à votre site. Seuls les champs avec des valeurs capturées sont affichés.
• Session GA4 – affiche l'ID client GA4 et l'ID de session du donateur, analysés à partir du cookie _ga au moment du don. Ceux-ci vous permettent de rapprocher le don dans les rapports GA4 si vous avez besoin d'enquêter sur une transaction spécifique.
• Consentement à l'insertion – affiche l'état de l'API WP Consent du donateur pour les catégories statistics et marketing au moment où il a fait un don. Utile pour les audits de conformité.
• Événements GA4 déclenchés – affiche l'horodatage lorsque les événements purchase et (le cas échéant) refund ont été envoyés à GA4. Si un don n'a pas d'horodatage de purchase, cela signifie que l'événement n'a pas encore été envoyé (toujours en attente) ou a été supprimé par vos paramètres de consentement ou d'exclusion de rôle.

Le panneau se charge fermé par défaut pour garder l'écran de modification du don épuré. Cliquez sur la barre de titre Google Analytics pour l'agrandir. WordPress mémorise votre préférence par utilisateur.

Marquage UTM de vos campagnes

Pour que la section Source (UTM) capture des données, le donateur doit arriver sur votre site via une URL contenant des paramètres UTM. Une URL de campagne typique pourrait ressembler à ceci :

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

Vous enverriez ce lien dans votre e-mail de collecte de fonds au lieu de l'URL nue de la page de don. Lorsque le donateur clique, Charitable enregistre ces valeurs UTM dans un cookie tiers qui expire après 30 jours. Chaque fois qu'il fait un don dans ce délai, les valeurs UTM sont jointes à l'enregistrement du don et transmises à GA4 en tant que paramètres d'événement source, medium, et campaign.

Par défaut, le module complémentaire utilise l'attribution du dernier contact : si le donateur visite avec un ensemble d'UTM, puis visite plus tard avec un ensemble différent, le dernier ensemble l'emporte. Les développeurs peuvent passer à l'attribution du premier contact avec le filtre charitable_google_analytics_utm_first_touch.

Comprendre les événements suivis par Charitable

Charitable déclenche les événements GA4 suivants à différents points du cycle de vie du don. Tous apparaissent automatiquement dans vos rapports GA4 – aucune configuration d'événement personnalisée n'est requise du côté de GA4.

• purchase – se déclenche lorsqu'un don est confirmé comme payé. Envoie les champs GA4 ecommerce standards : transaction_id (l'ID du don), value, currency, et un tableau items[] avec la campagne comme article, catégorisé comme Recurring (Récurrent) ou One-Time (Unique).
• refund – se déclenche lorsqu'un don est marqué comme remboursé. Correspond au transaction_id de l'événement purchase d'origine, afin que GA4 puisse les rapprocher automatiquement. Les revenus nets dans vos rapports GA4 restent précis.
• sign_up – se déclenche lorsqu'un donateur crée un compte utilisateur WordPress sur votre site. L'événement inclut un identifiant haché afin que les dons ultérieurs du même donateur soient corrélés à la même personne sur différents navigateurs et appareils.
• login – se déclenche lorsqu'un donateur revient et se connecte. Utile pour les rapports de rétention dans GA4.
• donation_button_click et donate_now_click – événements de clic uniquement pour le navigateur, pour un signal de haut de l'entonnoir. Ils se déclenchent lorsqu'un donateur clique sur un bouton de don, avant que le formulaire ne soit soumis.

Les dons effectués en mode test de Charitable sont marqués avec test_mode: true dans les paramètres de l'événement, vous pouvez donc les exclure de vos rapports. Pour ce faire dans GA4, créez une comparaison ou une audience qui exclut les événements où test_mode est égal à true.

Visualisation de vos données dans GA4

Une fois que vous avez effectué un don de test (ou qu'un don réel a été traité), Google Analytics propose trois endroits pour vérifier que les données arrivent.

Temps réel

Le moyen le plus rapide de confirmer que le suivi fonctionne. Depuis votre propriété GA4, ouvrez Rapports » Temps réel. Environ 30 secondes après la confirmation d'un don, vous verrez l'événement purchase dans la carte Nombre d'événements par nom d'événement sur la droite. Cliquez sur n'importe quel nom d'événement pour examiner ses paramètres.

DebugView

Pour une vérification étape par étape d'un événement spécifique, ouvrez Admin » DebugView. Les événements marqués avec debug_mode apparaissent ici en temps réel, avec les détails complets des paramètres. Le bouton Test Connection marque automatiquement ses événements pour DebugView, et vous pouvez également activer le mode débogage sur l'ensemble du site en ajoutant define('CHARITABLE_DEBUG', true); à votre fichier wp-config.php.

Rapports standards

Pour l'analyse des revenus, le rapport le plus utile est Rapports » Monétisation » Achats Ecommerce. Ce rapport agrège vos événements purchase en totaux de revenus ventilés par campagne (le item_name), catégorie (récurrent vs unique) et date. Les remboursements sont automatiquement soustraits grâce à la correspondance des ID de transaction de GA4. Les rapports standards sont peuplés dans les 24 à 48 heures.

Pour l'analyse des sources de trafic, consultez Rapports » Acquisition » Acquisition de trafic. Vos campagnes balisées UTM apparaîtront sur des lignes distinctes, avec des métriques de revenus, de taux de conversion et d'engagement pour chacune.

Test de la fonctionnalité

Le test de bout en bout le plus rapide consiste à effectuer un don réel sur votre site en utilisant une passerelle de test comme le mode test Stripe. Une fois le don terminé, ouvrez le don dans Charitable » Dons, développez le panneau Google Analytics et confirmez que la section Événements GA4 déclenchés affiche un horodatage de purchase. Vérifiez ensuite dans GA4 » Rapports » Temps réel pour confirmer que l'événement apparaît dans les 30 secondes.

Si vous testez l'événement de remboursement, faites passer le don à Remboursé depuis la liste des dons. La boîte de métadonnées doit ajouter un horodatage de refund, et GA4 Temps réel doit afficher l'événement refund dans les 30 secondes.

Dépannage

Les événements n'apparaissent pas dans GA4

Si vos dons de test n'apparaissent pas dans GA4, effectuez ces vérifications dans l'ordre :

• Dans Charitable » Paramètres » Avancé, confirmez que le champ Google Analytics contient votre ID de mesure et non un ID de conteneur GTM ou une propriété UA héritée.
• Cliquez sur le bouton Envoyer un événement de test à GA4. Le message d'erreur indiquera le problème spécifique (secret d'API invalide, ID de mesure invalide, erreur réseau).
• Vérifiez si vous êtes connecté avec un rôle que vous avez ajouté à Exclure le suivi pour les rôles. Les utilisateurs exclus ne génèrent pas d'événements, même lors des tests. Déconnectez-vous et essayez dans une fenêtre de navigation privée.
• Désactivez tous les bloqueurs de publicités de navigateur (uBlock Origin, AdBlock Plus, Brave Shields) pour votre domaine. Ils empêchent gtag.js de se charger sur le frontend.

Site Kit by Google est déjà actif

Si vous avez installé Google Site Kit et l'avez connecté à votre propriété GA4, Charitable retarde le chargement de gtag.js au profit de Site Kit. Cela évite que la page ne charge le script GA4 deux fois. Les événements de don seront toujours déclenchés via l'instance gtag de Site Kit.

Si vous avez installé Site Kit mais n'avez pas connecté le module Analytics, le report de Charitable est inutile. Les développeurs peuvent le remplacer en renvoyant false du filtre charitable_google_analytics_is_ga4_loaded.

Avis de conflit GTM pour le suivi des conversions Charitable

Si vous avez installé le module complémentaire Charitable Conversion Tracking avec un ID de conteneur GTM configuré, Charitable affichera un avis d'administration sur les pages de paramètres de Charitable expliquant que gtag.js est supprimé. Ceci est intentionnel – votre conteneur GTM est censé charger GA4 lui-même, et charger gtag.js par-dessus doublerait le comptage des vues de page.

Si votre conteneur GTM n'inclut pas réellement de balise GA4, cette suppression est incorrecte pour votre configuration. Remplacez-la par le filtre charitable_google_analytics_is_ga4_loaded.

Les événements côté serveur ne se déclenchent pas

Le suivi côté serveur ne s'active que lorsque l'ID de mesure et le secret de l'API Measurement Protocol sont définis. Si vos événements de remboursement ou les dons hors site n'apparaissent pas dans GA4 mais que les dons sur site le font, le secret de l'API est probablement manquant ou invalide. Utilisez le bouton Tester la connexion pour confirmer.

Si le secret de l'API est défini et que le test réussit, mais que les changements de statut réels ne génèrent pas d'événements, vérifiez la métabox Google Analytics du don. La section Consentement à l'insertion peut afficher statistiques : Refusé, auquel cas le module complémentaire ignore correctement les événements côté serveur pour les dons de ce donateur.

C'est tout ! Vous avez maintenant GA4 qui suit vos dons Charitable de bout en bout, avec des données d'attribution circulant à la fois dans Google Analytics et dans votre administration WordPress. Ensuite, consultez Connexion d'autres extensions Charitable pour associer ce module complémentaire au suivi des conversions pour les pixels Meta et TikTok, ou au module complémentaire Récurrent pour les analyses d'abonnements.

Filtres

Le module complémentaire expose 12 filtres couvrant la détection du chargeur, la personnalisation de la charge utile, le consentement, l'attribution et le hachage d'identité. Les noms des filtres suivent le préfixe charitable_google_analytics_* et passent la valeur filtrée comme premier argument.

charitable_google_analytics_is_ga4_loaded

Si un autre plugin charge déjà GA4 sur la page. Lorsque true, le module complémentaire n'injectera pas son propre gtag.js pour éviter le double chargement. Les chargeurs détectés incluent MonsterInsights, Site Kit by Google et le suivi des conversions Charitable avec un ID de conteneur GTM configuré.

apply_filters( 'charitable_google_analytics_is_ga4_loaded', $is_loaded );

Utilisez ceci lorsque vous avez un chargeur GA4 non par défaut (par exemple, une balise de thème personnalisée) que le module complémentaire ne détecte pas automatiquement. Retourner true supprime l'injection du gtag.js du module complémentaire.

charitable_google_analytics_purchase_payload

La charge utile de l'événement purchase côté navigateur construite sur la page de reçu du don (Phase A). Se déclenche avant que le bloc <script> en ligne ne soit émis dans le pied de page.

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

Le tableau $payload contient les champs e-commerce GA4 (transaction_id, value, currency, items). Retourner un tableau vide ([]) ignore le déclenchement de l'événement pour ce don.

charitable_google_analytics_mp_purchase_payload

La charge utile purchase du protocole de mesure côté serveur (Phase B). Se déclenche avant l'appel wp_remote_post() à GA4.

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

Le $payload est le corps complet du MP (client_id, user_id facultatif, events[]). Retourner une charge utile avec des events vides ignore l'appel.

charitable_google_analytics_mp_refund_payload

Même structure que mp_purchase_payload, mais déclenché avant l'événement serveur refund POST.

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

charitable_google_analytics_mp_signup_payload

La charge utile serveur sign_up construite lorsqu'un nouvel utilisateur WordPress est enregistré.

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

Utilisez ceci pour supprimer les événements d'inscription pour des rôles spécifiques ou pour injecter des paramètres d'événement personnalisés (par exemple, source d'inscription).

charitable_google_analytics_mp_login_payload

La charge utile serveur login construite lorsqu'un utilisateur WordPress se connecte.

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

Une utilisation courante consiste à ignorer les événements de connexion pour les utilisateurs ayant des capacités administratives.

charitable_google_analytics_persist_utm

Si le module complémentaire doit conserver les paramètres UTM de l'URL de requête dans des cookies de premier niveau lors de l'init. Par défaut true.

apply_filters( 'charitable_google_analytics_persist_utm', $persist );

Retourner false désactive complètement l'écriture des cookies UTM. Utile pour les sites qui souhaitent gérer la persistance UTM eux-mêmes via un mécanisme personnalisé.

charitable_google_analytics_utm_first_touch

Si vous devez utiliser l'attribution UTM du premier contact au lieu du dernier contact par défaut. Par défaut false.

apply_filters( 'charitable_google_analytics_utm_first_touch', $first_touch );

Lorsque true, un cookie UTM est écrit uniquement s'il n'existe pas déjà. Le premier UTM auquel le donateur a été attribué est conservé pendant la fenêtre de 30 jours du cookie.

charitable_google_analytics_has_consent

La décision de consentement pour une catégorie donnée au moment de l'évaluation. Reçoit le résultat de l'API WP Consent et vous permet de remplacer.

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
);

Le mode Live ($donation_id === 0) est utilisé pour le filtrage côté navigateur comme l'injection gtag.js. Le mode stocké ($donation_id > 0) est utilisé pour les appels MP côté serveur et lit l'état du consentement capturé lors de l'insertion du don. Retourner false supprime le suivi pour cette catégorie.

charitable_google_analytics_consent_default

L'état par défaut du mode de consentement v2 émis dans l'en-tête du document avant le chargement de gtag.js.

apply_filters(
    'charitable_google_analytics_consent_default',
    array $consent_default
);

$consent_default contient quatre clés : ad_user_data, ad_personalization, ad_storage, et analytics_storage, chacune définie sur 'granted' ou 'denied'. Retourner 'granted' pour les quatre désactive efficacement la modélisation du mode de consentement v2 pour ce chargement de page.

charitable_google_analytics_user_id

L'ID utilisateur haché attaché aux charges utiles MP en tant que user_id. La valeur par défaut est sha256(normalized_email), où l'e-mail est mis en minuscules et débarrassé de la sous-adresse.

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

Retourner une chaîne vide supprime complètement le champ user_id. Le filtre reçoit le hachage final, pas l'e-mail brut – si vous avez besoin d'un schéma d'identité différent, retournez votre propre hachage stable par humain ici.

charitable_google_analytics_client_ip

L'IP client utilisée comme source pour l'anonymisation de l'IP. Par défaut REMOTE_ADDR. Les sites derrière un CDN ou un proxy inverse qui place la véritable IP du donateur dans un en-tête transféré devraient remplacer cela.

apply_filters( 'charitable_google_analytics_client_ip', string $ip );

La valeur retournée est ensuite tronquée à /24 (IPv4) ou /48 (IPv6) avant d'être transmise à GA4 en tant que paramètre ip_override.

Actions

Le module déclenche deux actions pour chaque appel au protocole de mesure côté serveur – une en cas de succès, une en cas d'échec. Les deux permettent aux intégrations tierces de réagir à la livraison des conversions GA4 en temps réel.

charitable_google_analytics_event_sent

Déclenché après une réponse 2xx de mp/collect.

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
);

Utilisez ceci pour refléter les événements vers un CDP comme HubSpot ou Segment, déclencher un webhook Zapier, mettre à jour un tableau de bord d'analyse, ou toute autre action qui doit réagir à une conversion confirmée.

charitable_google_analytics_event_failed

Déclenché en cas d'erreur réseau (réponse WP_Error) ou de statut HTTP non-2xx.

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

Utilisez ceci pour alerter les opérations, mettre en file d'attente une nouvelle tentative via votre propre système de tâches, ou revenir à un pipeline alternatif.

Clés méta de don

Le module stocke tout ce qu'il capture sur un don en tant que métadonnées standard de publication WordPress. Vous pouvez les interroger directement avec get_post_meta() ou via wp post meta get de WP-CLI.

Clé de métadonnées	Défini par	Type	Ce qu'il contient
_charitable_ga_client_id	capture_session() sur charitable_after_save_donation	chaîne de caractères	Client_id GA4 analysé à partir du cookie _ga du donateur lors de l'insertion du don. Format : <part1>.<part2>.
_charitable_ga_session_id	Identique	chaîne de caractères	Identifiant de session GA4 analysé à partir du cookie _ga_<container> du donateur.
_charitable_ga_ip_override	Identique	chaîne de caractères	IP anonymisée du donateur (/24 IPv4 ou /48IPv6).
_charitable_ga_consent_statistics	Identique	'granted'ou non défini	État de l'API WP Consent pour la catégorie statistics lors de l'insertion. Les métadonnées vides sont considérées comme permissives.
_charitable_ga_consent_marketing	Identique	'granted'ou non défini	Identique pour marketing.
_charitable_ga_utm_source	Identique	chaîne de caractères	Source UTM du cookie first-party du donateur (ou $_REQUESTfallback).
_charitable_ga_utm_medium	Identique	chaîne de caractères	Support UTM.
_charitable_ga_utm_campaign	Identique	chaîne de caractères	Campagne UTM.
_charitable_ga_utm_term	Identique	chaîne de caractères	Terme UTM.
_charitable_ga_utm_content	Identique	chaîne de caractères	Contenu UTM.
_charitable_ga_utm_id	Identique	chaîne de caractères	ID UTM.
_charitable_ga_purchase_fired	fire_purchase_event() (Phase A) et fire_purchase_mp() (Phase B)	Chaîne de date et heure MySQL	Horodatage du premier événement purchase réussi. Partagé entre la Phase A et la Phase B – le premier qui se déclenche le définit.
_charitable_ga_refund_fired	fire_refund_mp()	Chaîne de date et heure MySQL	Horodatage de l’événement refund réussi. Distinct du drapeau d’achat.

Toutes les clés meta sont préfixées par un seul underscore, ce qui signifie qu’elles sont masquées de l’interface utilisateur standard des champs personnalisés dans l’écran de modification du don. Elles apparaissent à la place dans la boîte meta « Google Analytics » du module complémentaire.

Noms des cookies

Le module complémentaire écrit les cookies suivants dans le navigateur du donateur :

• charitable_ga_utm_source, charitable_ga_utm_medium, charitable_ga_utm_campaign, charitable_ga_utm_term, charitable_ga_utm_content, charitable_ga_utm_id – cookies de premier niveau définis à l’init chaque fois qu’un paramètre UTM est présent dans l’URL de la requête. Durée de vie 30 jours, chemin /, SameSite Lax, Secure lorsque le SSL est actif.

Il lit également ces cookies définis par gtag.js lui-même :

• _ga – source client_id de GA4
• _ga_<container> – source session_id de GA4. La partie <container> est l’ID de mesure avec le G- initial supprimé.

Clés d'options de paramètres

Les paramètres du module complémentaire se trouvent dans l’option WordPress charitable_settings. Vous pouvez les lire via charitable_get_option( $key, $default ):

Clé d’option	Type	Défaut	Description
ga4_tracking_id	chaîne de caractères	''	L’ID de mesure GA4 (G-XXXXXXXXXX).
ga4_mp_api_secret	chaîne de caractères	''	Le secret de l’API Measurement Protocol. Requis pour le suivi côté serveur.
ga4_consent_integration	bool	1	Si l’état de l’API WP Consent doit être respecté.
ga4_excluded_roles	string[]	[]	Tableau de slugs de rôles à exclure du suivi.

Constantes

Deux constantes WordPress modifient le comportement d'exécution du module complémentaire :

• CHARITABLE_DEBUG (vrai/faux) – lorsqu'il est vrai, le module complémentaire écrit des fils d'Ariane étape par étape dans Outils » Journaux avec source: google-analytics, et ajoute debug_mode: 1 à toutes les charges utiles d'événements MP GA4 afin qu'elles apparaissent dans GA4 » Admin » DebugView. Définir dans wp-config.php pour les sites de développement.
• SCRIPT_DEBUG (vrai/faux) – lorsqu'il est vrai, le module complémentaire met en file d'attente le fichier source charitable-google-analytics.js non minifié au lieu de la version de production minifiée. Utile pour déboguer le comportement du frontend.

Recettes courantes

Changer l'attribution UTM du dernier contact au premier contact

add_filter( 'charitable_google_analytics_utm_first_touch', '__return_true' );

La première UTM à laquelle le donateur a été attribué dans la fenêtre de cookie de 30 jours reste. Les visites ultérieures avec des UTM différentes sont ignorées.

Capturer la véritable IP du donateur derrière 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;
} );

L'IP retournée est toujours anonymisée en /24 (IPv4) ou /48 (IPv6) avant d'être envoyée à GA4 – le filtre change simplement quelle IP est anonymisée.

Miroir chaque don confirmé à un CDP

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
);

Les événements réussis et échoués déclenchent des actions, vous pouvez donc également réessayer les événements échoués via votre propre système de tâches.

Ignorer les événements de connexion pour les administrateurs

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
);

Un tableau events vide indique au module complémentaire d'ignorer l'appel MP sans perturber les autres types d'événements.

Ajouter un paramètre d'événement personnalisé à chaque achat

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
);

Utilisez ceci pour les installations WordPress multi-organisations où chaque don doit porter une étiquette d'organisation pour la segmentation GA4.

Remplacer l'identifiant utilisateur du donateur par votre propre schéma d'identité

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
);

Le filtre reçoit le hachage par défaut du module complémentaire ; vous pouvez le remplacer par votre propre hachage stable par personne. Retourner une chaîne vide supprime complètement le champ user_id.

Ordre de déclenchement des hooks

Pour un flux de don typique qui se termine sur le site, les hooks pertinents se déclenchent dans cet ordre :

1. init (priorité 10) – charitable_google_analytics_persist_utm() écrit les cookies UTM si l'URL de la requête a des paramètres UTM.
2. wp_head (priorité 1) – le mode de consentement v2 par défaut en ligne et la balise de script gtag.js sont émis, limités par charitable_google_analytics_is_ga4_loaded et la vérification d'exclusion de rôle.
3. wp_footer (priorité 1) – les appels gtag('js') et gtag('config') sont émis.
4. Le donateur soumet le formulaire de don. Le flux de passerelle basé sur AJAX ou la redirection s'exécute.
5. charitable_after_save_donation (priorité 10) – capture_session() lit les cookies du donateur et stocke l'identifiant client GA4, l'identifiant de session, l'IP anonymisée, les valeurs UTM et l'état du consentement en tant que métadonnées de don.
6. La passerelle confirme le paiement (synchrone pour sur site, via webhook pour hors site).
7. charitable_donation_status_changed (priorité 10) – fire_purchase_mp() POSTe l'événement serveur purchase. L'action charitable_google_analytics_event_sent se déclenche en cas de succès.
8. charitable_donation_receipt_page (navigateur uniquement) – fire_purchase_event() ajoute un rappel wp_footer qui émet le script inline gtag('event', 'purchase', ...). Le méta _charitable_ga_purchase_fired est défini dans ce rappel wp_footer (pas de manière synchrone) afin que le rendu par e-mail du reçu ne déclenche pas le drapeau d'idempotence.

Pour un remboursement : l'étape 7 ci-dessus est réactivée avec new_status === 'charitable-refunded', et fire_refund_mp() POSTe l'événement refund.

Pour une inscription ou une connexion : seules les étapes 1, 2, 3 ci-dessus s'appliquent dans le contexte du navigateur. Les étapes 5 à 8 sont remplacées par user_register ou wp_login, qui déclenchent respectivement fire_signup_mp() ou fire_login_mp().

C'est tout ! Vous disposez maintenant de la surface complète des hooks pour le module complémentaire Charitable Google Analytics. Consultez ensuite le Guide complet de Google Analytics dans Charitable pour la documentation d'installation et d'administration, ou le hub de Documentation du développeur Charitable pour les hooks du reste de Charitable.

Questions fréquemment posées

Q : Cela fonctionnera-t-il avec PayPal Standard ou d'autres passerelles externes ?

R : Oui, tant que vous avez configuré le Secret de l'API GA4 Measurement Protocol. Le chemin côté serveur de Charitable intercepte chaque don qui passe à l'état Payé, que le navigateur du donateur soit revenu ou non sur votre site.

Q : Est-ce conforme au RGPD ?

R : Charitable prend en charge la conformité RGPD et EEE via Google Consent Mode v2 et le framework WP Consent API. Les adresses IP des donateurs sont anonymisées avant la transmission, et les e-mails des donateurs sont hachés en un condensé SHA-256 unidirectionnel avant de devenir l'ID utilisateur GA4. L'e-mail complet n'est jamais envoyé à Google.

Q : Y a-t-il un conflit avec Site Kit by Google ou MonsterInsights ?

R : Non. Charitable détecte automatiquement les deux plugins et retarde le chargement de gtag.js lorsque l'un d'eux est actif, de sorte que vous ne vous retrouvez jamais avec le script GA4 chargé deux fois sur la même page. Les événements de don sont toujours déclenchés via le chargeur en cours.

Q : Combien de temps faut-il pour que les événements apparaissent dans les rapports GA4 ?

R : Realtime et DebugView affichent les événements en environ 30 secondes. Les rapports standard (y compris Monétisation » Achats e-commerce) se remplissent dans les 24 à 48 heures.

Q : Puis-je exclure mon personnel du suivi ?

R : Oui – utilisez le champ Exclure le suivi pour les rôles dans Charitable » Paramètres » Avancé et sélectionnez les rôles WordPress que vous souhaitez exclure. Les utilisateurs exclus sautent les parties côté navigateur et les parties applicables aux rôles du suivi côté serveur.

Q : Les dons effectués en mode test de Charitable sont-ils suivis ?

R : Oui, mais ils sont marqués avec test_mode: true dans les paramètres de l'événement afin que vous puissiez les filtrer de vos rapports GA4. Créez une comparaison ou une audience GA4 qui exclut les événements où test_mode est égal à true pour maintenir la propreté de vos rapports de production.

Q : Ces hooks sont-ils stables entre les versions ?

R : Tous les hooks documentés ici ont été introduits dans la version 1.1.0 et font partie de l'API publique du module complémentaire. Les signatures des filtres et des actions sont versionnées via la balise @since dans le code source. Les changements majeurs seront annoncés dans le journal des modifications avec un avis de dépréciation dans la version précédente.

Q : Comment désactiver complètement un événement spécifique ?

R : Utilisez le filtre de charge utile correspondant et renvoyez un tableau avec des events vides. Par exemple, pour supprimer tous les événements de refund côté serveur :

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

Q : Puis-je ajouter des dimensions personnalisées aux événements GA4 ?

R : Oui. Les dimensions personnalisées GA4 sont envoyées en tant que paramètres d'événement. Utilisez charitable_google_analytics_mp_purchase_payload (ou le filtre correspondant pour d'autres événements) pour injecter votre paramètre personnalisé dans $payload['events'][0]['params']. Assurez-vous que le nom du paramètre correspond au « nom du paramètre d'événement » de votre dimension personnalisée dans l'administration GA4.

Q : Comment puis-je tester si mon hook personnalisé se déclenche ?

R : Définissez define( 'CHARITABLE_DEBUG', true ); dans wp-config.php, puis vérifiez Outils » Journaux filtrés par la source google-analytics. Les appels MP réussis enregistrent des entrées de niveau info. Ajoutez un appel error_log() à l'intérieur de votre hook pour un débogage unique, ou utilisez le panneau « Hooks & Actions » de Query Monitor pour une vue en direct.

Q : Le module complémentaire fonctionne-t-il avec WP-CLI ?

R : Oui. La persistance UTM est ignorée dans les contextes wp_doing_ajax() et CLI (aucun cookie à définir), mais les hooks côté serveur comme charitable_donation_status_changed se déclenchent correctement lorsqu'ils sont déclenchés via des commandes WP-CLI. Les métadonnées de don sont interrogeables via wp post meta get <donation-id> _charitable_ga_purchase_fired.

Q : Puis-je étendre le module complémentaire avec mes propres types d'événements personnalisés ?

R : Oui. L'aide charitable_google_analytics_post_mp_event() est interne mais les actions qu'elle déclenche (event_sent / event_failed) facilitent l'ajout de vos propres types d'événements côté serveur. Connectez votre fonction de déclenchement d'événement à l'action Charitable appropriée, construisez vous-même la charge utile MP et POSTez vers le même point de terminaison que celui utilisé par le module complémentaire. L'aide pour les identifiants MP charitable_google_analytics_get_mp_credentials() est également publique.