Carbon Footprint + Offset Checkout — Guide complet

Installation

Carbon Footprint + Offset Checkout est un plugin WooCommerce standard, installable comme n’importe quelle extension.

1. Téléchargez le ZIP df-carbon-offset.zip depuis la fiche produit DataFirefly.
2. Dans votre back-office WordPress, allez sur Extensions → Ajouter → Téléverser une extension.
3. Sélectionnez le fichier ZIP, cliquez sur Installer maintenant, puis sur Activer.
4. Une nouvelle entrée Carbon Footprint apparaît dans le menu latéral WooCommerce.

À l’activation, deux tables SQL sont créées automatiquement : {prefix}dfcarbon_factors (facteurs d’émission) et {prefix}dfcarbon_log (journal des compensations). La base ADEME est immédiatement seedée avec environ 25 facteurs pré-chargés.

Configuration initiale

Le plugin fonctionne zero-config dès l’activation : les facteurs ADEME sont chargés, le badge s’affiche sur toutes les fiches produit, la compensation apparaît au checkout. Mais quelques ajustements initiaux vous donneront des chiffres bien plus pertinents.

Réglages généraux

Allez sur Carbon Footprint → Réglages. Quatre blocs de paramètres :

• API Climatiq — optionnelle. Laissez vide pour un fonctionnement 100% local sur les facteurs ADEME.
• Compensation — activation du bloc au checkout, prix par tonne (défaut 25 €/t, marché typique 15–30 €/t), partenaire affiché (Gold Standard par défaut), description client.
• Transport — activation de la composante transport, distance moyenne en km (défaut 500 km), facteur d’émission transport (défaut : transport routier).
• Affichage — position du badge sur la fiche produit (5 hooks disponibles), style (carte, pastille, minimal), couleur, priorité du hook.

Mapping catégories → facteurs

C’est l’étape la plus impactante. Allez sur Carbon Footprint → Mapping. Pour chaque catégorie de produits WooCommerce, sélectionnez le facteur d’émission le plus pertinent parmi ceux de la base ADEME.

Activation de l’API Climatiq (optionnelle)

Climatiq est une base de plus de 80 000 facteurs d’émission, plus fine que la Base Empreinte ADEME sur certains secteurs (électronique détaillée, cosmétique par composant, agroalimentaire par filière). Si vous avez une clé :

1. Créez un compte sur climatiq.io (offre gratuite disponible pour un usage modéré).
2. Copiez la clé API dans Carbon Footprint → Réglages → Climatiq API.
3. Cliquez sur Tester la connexion pour valider.

Une fois activée, l’API Climatiq est utilisée en priorité 2 (après un éventuel override manuel produit) et devant le mapping ADEME. Chaque résultat est mis en cache une semaine — aucun surcoût d’appel au rendu des pages.

Comment fonctionne le calcul d’empreinte

Priorités du calcul

Pour chaque produit, le plugin détermine l’empreinte via quatre sources, dans cet ordre strict de priorité :

1. Override manuel produit — si vous avez saisi une valeur dans l’onglet « Carbon » de la fiche produit (meta _dfcarbon_kgco2e), c’est celle-ci qui est utilisée. Elle court-circuite toutes les autres sources.
2. API Climatiq — si une clé API est configurée et que le produit a un poids ou une catégorie interrogeable.
3. Facteur ADEME via mapping — le facteur assigné à la catégorie du produit, appliqué au poids.
4. Fallback général — le facteur general (4,50 kgCO₂e/kg) appliqué au poids, ou une valeur forfaitaire si le poids n’est pas renseigné.

Le calcul est mis en cache via l’API objet WordPress (groupe dfcarbon_product) et invalidé automatiquement à chaque modification de fiche produit ou de mapping.

Composante transport

Si activée, la composante transport est ajoutée à l’empreinte matière :

empreinte_totale = empreinte_matière + (poids_kg × distance_km × facteur_transport_tkm)

Le facteur transport routier par défaut est de 0,105 kgCO₂e par tonne-kilomètre (source ADEME, poids lourd moyen). Vous pouvez changer le facteur transport dans les réglages, ou basculer sur un autre facteur (transport maritime, aérien, etc.) si vous en ajoutez à la base.

Facteurs d’émission ADEME inclus

Le plugin est livré avec environ 25 facteurs pré-chargés, issus de la Base Empreinte ADEME (France). Les principaux secteurs couverts :

• Textile — vêtement standard, coton, laine, synthétique, chaussures
• Électronique — smartphone, ordinateur portable, petit électroménager, gros électroménager
• Alimentaire — bovin, porc, volaille, poisson, produits laitiers, épicerie sèche
• Cosmétique — soin corps, maquillage, parfumerie
• Maison — mobilier bois, mobilier métal, textile de maison
• Papier — livre, magazine, carton d’emballage
• Sport — équipement sportif, vêtement sport
• Bijoux — bijouterie fantaisie, argent, or
• Transport — transport routier, transport maritime
• Fallback — general (4,50 kgCO₂e/kg)

Vous pouvez consulter, éditer, supprimer ou ajouter vos propres facteurs depuis Carbon Footprint → Facteurs. Chaque facteur possède : un slug unique, un libellé, une valeur en kgCO₂e/unité, une unité (kg par défaut), une source (ADEME, Climatiq, personnalisé…) et une année.

Un bouton Recharger les valeurs ADEME par défaut permet de restaurer la base d’origine sans écraser vos ajouts personnels : seuls les slugs ADEME manquants seront réinsérés.

Le badge produit

Styles disponibles

Trois rendus au choix (réglable dans Réglages → Affichage → Style du badge) :

• Carte (détaillée) — bloc complet avec l’empreinte, la source, deux équivalences pédagogiques (km voiture, années d’arbre) et le prix de compensation.
• Pastille en ligne — badge compact « 🌱 5,2 kg CO₂e » à côté du prix.
• Texte minimal — juste la valeur, sans encadré.

Positions

Le badge s’accroche à l’un des hooks WooCommerce standards :

• after_price — juste après le prix (défaut)
• before_add_to_cart — avant le bouton d’ajout au panier
• after_add_to_cart — après le bouton d’ajout au panier
• before_meta — avant les métadonnées produit
• after_summary — après le résumé complet du produit

Si aucune position ne convient à votre thème, vous pouvez utiliser le shortcode [dfcarbon_badge] directement dans un template ou un builder visuel (Elementor, Divi, Gutenberg…).

Masquer sur certains produits

Dans l’onglet Carbon de chaque fiche produit, cochez « Masquer le badge ». Le calcul d’empreinte reste actif (utile pour les rapports et le checkout), mais l’affichage public disparaît. Pratique pour les produits dématérialisés, les cartes cadeaux ou les services.

Compensation au checkout

Au checkout, le plugin insère un bloc entre le récapitulatif de commande et le mode de paiement. Ce bloc contient :

• L’empreinte estimée du panier (somme des empreintes de tous les articles × leurs quantités)
• Le coût de compensation correspondant (empreinte × prix par tonne)
• Une case à cocher optionnelle « Oui, j’ajoute X € pour compenser l’impact de ma commande »
• Un texte descriptif configurable mentionnant le partenaire (Gold Standard, Verra…)

Quand le client coche la case, un fee WooCommerce dynamique est ajouté au total via le hook woocommerce_cart_calculate_fees. L’état est stocké dans la session WooCommerce (dfcarbon_offset_active), puis persisté sur la commande via les metas _dfcarbon_cart_kgco2e, _dfcarbon_offset_active, _dfcarbon_offset_amount et _dfcarbon_offset_provider.

Tableau de bord et rapports

Le menu Carbon Footprint → Tableau de bord affiche les indicateurs globaux :

• Nombre total de commandes compensées
• Empreinte CO₂ cumulée mesurée sur les commandes
• Empreinte CO₂ effectivement compensée
• Montant total investi en compensation

Le menu Carbon Footprint → Rapports détaille chaque commande compensée : date, numéro de commande, empreinte de la commande, kg compensés, montant, partenaire. Ce tableau alimente directement votre reporting extra-financier CSRD ou toute demande d’audit RSE.

Un snapshot d’empreinte est aussi conservé par ligne de commande (meta _dfcarbon_line_kgco2e) : les valeurs affichées ne changent pas rétrospectivement quand vous modifiez un facteur ADEME plus tard.

Shortcodes disponibles

Trois shortcodes publics pour intégrer les éléments partout dans votre site :

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

Affiche le badge carbone d’un produit spécifique. id est obligatoire, style optionnel (card par défaut, pill, minimal).

[dfcarbon_cart_summary]

Affiche l’empreinte du panier en cours et le coût de compensation. Utile dans une page « Mon panier » personnalisée ou dans une side-cart.

[dfcarbon_stats]

Bloc public avec les statistiques agrégées : tonnes compensées, nombre de commandes, montant investi. Parfait pour une page « Notre engagement climat ».

Hooks & filtres pour développeurs

Le plugin expose un filtre principal pour override complet du calcul d’empreinte :

add_filter( 'dfcarbon_product_footprint', function( $footprint, $product_id, $context ) {
    // $footprint est un array : ['kg' => 5.2, 'source' => 'ademe', 'breakdown' => [...]]
    // Retournez un array modifié pour surcharger
    return $footprint;
}, 10, 3 );

Autres hooks utiles :

• dfcarbon_daily_sync — action WP-Cron quotidienne (purge des transients Climatiq)
• dfcarbon_before_offset_fee — action avant l’ajout du fee de compensation
• dfcarbon_offset_purchased — action déclenchée à la persistance sur commande

Le plugin utilise le namespace PHP DataFirefly\CarbonOffset. Pour ajouter un facteur programmatique depuis un mu-plugin ou un thème enfant, importez la classe Database :

use DataFirefly\CarbonOffset\Database;

Database::upsert_factor( [
    'slug'   => 'mon-facteur',
    'label'  => 'Mon secteur particulier',
    'value'  => 2.35,
    'unit'   => 'kg',
    'source' => 'Personnalisé',
    'year'   => 2026,
] );

Multilingue (Polylang / WPML)

Le plugin est compatible avec Polylang Pro et WPML. Les 5 langues fournies (FR, EN, ES, DE, IT) sont dans le dossier languages/ avec les fichiers .po et .mo déjà compilés.

Pour ajuster une traduction :

1. Installez Loco Translate (plugin gratuit) ou utilisez Poedit en local.
2. Ouvrez le catalogue df-carbon-offset-fr_FR.po.
3. Éditez les entrées à traduire.
4. Recompilez en .mo — automatique dans Loco Translate.

Pour ajouter une nouvelle langue non fournie (portugais, néerlandais…), dupliquez un .po existant, renommez-le au bon locale (df-carbon-offset-pt_PT.po, df-carbon-offset-nl_NL.po…), traduisez et compilez.

Désinstallation

Le plugin nettoie proprement à la désinstallation via uninstall.php :

• Suppression des tables dfcarbon_factors et dfcarbon_log
• Suppression des options dfcarbon_settings et dfcarbon_db_version
• Suppression des postmeta _dfcarbon_* sur tous les produits et commandes
• Désinscription du cron dfcarbon_daily_sync
• Purge des transients Climatiq

FAQ

Puis-je forcer un facteur spécifique sur un produit sans changer sa catégorie ?

Oui. Dans l’onglet Carbon de la fiche produit, sélectionnez un facteur dans le menu déroulant « Facteur d’émission ». Il l’emporte sur le mapping de catégorie pour ce produit uniquement.

Que se passe-t-il si mon produit n’a pas de poids ?

Le calcul utilise une valeur forfaitaire pour les produits sans poids (traités comme « unité »). Vous pouvez aussi utiliser l’override manuel pour saisir directement la valeur en kg CO₂e.

Le plugin fonctionne-t-il avec les produits variables ?

Oui. L’empreinte est calculée au niveau du produit parent (via son poids et sa catégorie), ce qui reste cohérent pour la plupart des cas. Pour un contrôle par variation, utilisez le filtre dfcarbon_product_footprint.

Comment gérer les produits téléchargeables (dématérialisés) ?

Pour un produit purement dématérialisé (ebook, formation en ligne, licence logicielle), cochez « Masquer le badge » et laissez le calcul retomber sur le fallback général (l’impact sera minimal si le produit n’a pas de poids). Alternative : utilisez l’override manuel avec une petite valeur (typiquement 0,01 à 0,1 kg CO₂e pour un ebook).

Puis-je exclure un produit de la compensation au checkout ?

La compensation s’applique au panier dans son ensemble, pas produit par produit. Si un produit doit être totalement exclu du calcul, utilisez le filtre dfcarbon_product_footprint pour retourner un array avec ['kg' => 0].

Le plugin fait-il des appels API à chaque page vue ?

Non. Chaque empreinte produit est mise en cache via l’API objet WordPress. Les appels Climatiq (si activés) sont eux-mêmes cachés en transient pendant une semaine. Une page produit ne déclenche aucun appel externe.

Compatible avec les caches (WP Rocket, Litespeed, W3TC) ?

Oui, entièrement. Le rendu du badge est statique côté serveur. La partie dynamique (checkbox de compensation au checkout) est gérée en AJAX et n’affecte pas la mise en cache de la fiche produit.