Carbon Footprint + Offset Checkout — Guida completa

Installazione

Carbon Footprint + Offset Checkout è un plugin WooCommerce standard, installabile come qualsiasi altra estensione.

1. Scarica il file df-carbon-offset.zip dalla scheda prodotto DataFirefly.
2. Nel back-office WordPress, vai su Plugin → Aggiungi nuovo → Carica plugin.
3. Seleziona lo ZIP, clicca su Installa ora, poi su Attiva.
4. Una nuova voce Carbon Footprint appare nel menu laterale di WooCommerce.

All’attivazione, due tabelle SQL vengono create automaticamente: {prefix}dfcarbon_factors (fattori di emissione) e {prefix}dfcarbon_log (registro delle compensazioni). La base ADEME viene subito pre-caricata con circa 25 fattori.

Configurazione iniziale

Il plugin funziona zero-config subito dopo l’attivazione: i fattori ADEME sono caricati, il badge appare su tutte le schede prodotto, la compensazione compare al checkout. Ma alcune regolazioni iniziali ti daranno cifre molto più precise.

Impostazioni generali

Vai su Carbon Footprint → Impostazioni. Quattro blocchi di parametri:

• API Climatiq — opzionale. Lascia vuoto per un funzionamento 100% locale con i fattori ADEME.
• Compensazione — attivazione del blocco al checkout, prezzo per tonnellata (default 25 €/t, mercato tipico 15–30 €/t), partner mostrato (Gold Standard di default), descrizione per il cliente.
• Trasporto — attivazione della componente trasporto, distanza media in km (default 500 km), fattore di emissione del trasporto (default: trasporto su strada).
• Visualizzazione — posizione del badge sulla scheda (5 hook disponibili), stile (scheda, pillola, minimo), colore, priorità dell’hook.

Mappatura categorie → fattori

È il passaggio più incisivo. Vai su Carbon Footprint → Mappatura. Per ogni categoria di prodotti WooCommerce, seleziona il fattore di emissione più rilevante tra quelli della base ADEME.

Attivazione dell’API Climatiq (opzionale)

Climatiq è una base di oltre 80.000 fattori di emissione, più granulare della Base Empreinte ADEME su certi settori (elettronica dettagliata, cosmetica per componente, alimentare per filiera). Se hai una chiave:

1. Crea un account su climatiq.io (piano gratuito disponibile per uso moderato).
2. Incolla la chiave API in Carbon Footprint → Impostazioni → API Climatiq.
3. Clicca su Testa connessione per validare.

Una volta attivata, l’API Climatiq viene usata con priorità 2 (dopo un eventuale override manuale prodotto) e davanti alla mappatura ADEME. Ogni risultato viene messo in cache per una settimana — nessun costo aggiuntivo al rendering delle pagine.

Come funziona il calcolo dell’impronta

Priorità del calcolo

Per ogni prodotto, il plugin determina l’impronta secondo quattro fonti, in questo ordine rigido di priorità:

1. Override manuale prodotto — se hai inserito un valore nella tab «Carbon» della scheda (meta _dfcarbon_kgco2e), è quello che viene usato. Cortocircuita tutte le altre fonti.
2. API Climatiq — se una chiave API è configurata e il prodotto ha un peso o una categoria consultabile.
3. Fattore ADEME tramite mappatura — il fattore assegnato alla categoria del prodotto, applicato al peso.
4. Fallback generale — il fattore general (4,50 kgCO₂e/kg) applicato al peso, o un valore forfettario se non c’è peso.

Il calcolo viene messo in cache tramite l’API a oggetti di WordPress (gruppo dfcarbon_product) e invalidato automaticamente a ogni modifica di prodotto o mappatura.

Componente trasporto

Se attivata, la componente trasporto si aggiunge all’impronta materiale:

impronta_totale = impronta_materiale + (peso_kg × distanza_km × fattore_trasporto_tkm)

Il fattore di trasporto su strada di default è 0,105 kgCO₂e per tonnellata-chilometro (fonte ADEME, camion pesante medio). Puoi cambiarlo nelle impostazioni, o passare a un altro fattore (marittimo, aereo, ecc.) se lo aggiungi alla base.

Fattori di emissione ADEME inclusi

Il plugin viene fornito con circa 25 fattori pre-caricati dalla Base Empreinte ADEME (Francia). Principali settori coperti:

• Tessile — capo standard, cotone, lana, sintetico, calzature
• Elettronica — smartphone, portatile, piccoli elettrodomestici, grandi elettrodomestici
• Alimentare — bovino, suino, pollame, pesce, latticini, drogheria
• Cosmetica — cura del corpo, trucco, profumeria
• Casa — mobili legno, mobili metallo, tessili casa
• Carta — libro, rivista, imballaggio cartone
• Sport — attrezzatura sportiva, abbigliamento sportivo
• Gioielleria — bigiotteria, argento, oro
• Trasporto — trasporto su strada, trasporto marittimo
• Fallback — general (4,50 kgCO₂e/kg)

Puoi consultare, modificare, eliminare o aggiungere i tuoi fattori da Carbon Footprint → Fattori. Ogni fattore ha: uno slug univoco, un’etichetta, un valore in kgCO₂e/unità, un’unità (kg di default), una fonte (ADEME, Climatiq, personalizzato…) e un anno.

Un pulsante Ricarica i valori ADEME predefiniti permette di ripristinare la base originale senza sovrascrivere le tue aggiunte personali: solo gli slug ADEME mancanti vengono reinseriti.

Il badge prodotto

Stili disponibili

Tre rese tra cui scegliere (in Impostazioni → Visualizzazione → Stile del badge):

• Scheda (dettagliata) — blocco completo con impronta, fonte, due equivalenze pedagogiche (km in auto, anni d’albero) e prezzo di compensazione.
• Pillola in linea — badge compatto «🌱 5,2 kg CO₂e» accanto al prezzo.
• Testo minimo — solo il valore, senza riquadro.

Posizioni

Il badge si aggancia a uno degli hook WooCommerce standard:

• after_price — subito dopo il prezzo (default)
• before_add_to_cart — prima del pulsante «aggiungi al carrello»
• after_add_to_cart — dopo il pulsante «aggiungi al carrello»
• before_meta — prima dei meta del prodotto
• after_summary — dopo il riepilogo completo del prodotto

Se nessuna posizione si adatta al tuo tema, usa lo shortcode [dfcarbon_badge] direttamente in un template o in un page builder (Elementor, Divi, Gutenberg…).

Nascondere su alcuni prodotti

Nella tab Carbon di ogni scheda prodotto, spunta «Nascondi il badge». Il calcolo dell’impronta resta attivo (utile per i report e il checkout), ma la visualizzazione pubblica scompare. Pratico per prodotti digitali, buoni regalo o servizi.

Compensazione al checkout

Al checkout, il plugin inserisce un blocco tra il riepilogo ordine e il metodo di pagamento. Questo blocco contiene:

• L’impronta stimata del carrello (somma delle impronte di tutti gli articoli × le loro quantità)
• Il costo di compensazione corrispondente (impronta × prezzo per tonnellata)
• Una casella facoltativa «Sì, aggiungo X € per compensare l’impatto del mio ordine»
• Un testo descrittivo configurabile che menziona il partner (Gold Standard, Verra…)

Quando il cliente spunta la casella, un fee dinamico WooCommerce viene aggiunto al totale tramite l’hook woocommerce_cart_calculate_fees. Lo stato è salvato nella sessione WooCommerce (dfcarbon_offset_active), poi persistito sull’ordine tramite i meta _dfcarbon_cart_kgco2e, _dfcarbon_offset_active, _dfcarbon_offset_amount e _dfcarbon_offset_provider.

Bacheca e report

Il menu Carbon Footprint → Bacheca mostra gli indicatori globali:

• Numero totale di ordini compensati
• Impronta CO₂ cumulativa misurata sugli ordini
• Impronta CO₂ effettivamente compensata
• Importo totale investito in compensazione

Il menu Carbon Footprint → Report dettaglia ogni ordine compensato: data, numero ordine, impronta dell’ordine, kg compensati, importo, partner. Questa tabella alimenta direttamente il tuo reporting extra-finanziario CSRD o qualsiasi richiesta di audit ESG.

Uno snapshot di impronta viene anche conservato per riga d’ordine (meta _dfcarbon_line_kgco2e): i valori mostrati non cambiano retroattivamente quando modifichi un fattore ADEME in seguito.

Shortcode disponibili

Tre shortcode pubblici per integrare gli elementi ovunque sul tuo sito:

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

Mostra il badge carbonio di un prodotto specifico. id è obbligatorio, style facoltativo (card di default, pill, minimal).

[dfcarbon_cart_summary]

Mostra l’impronta del carrello corrente e il costo di compensazione. Utile in una pagina «Il mio carrello» personalizzata o in una side-cart.

[dfcarbon_stats]

Blocco pubblico con statistiche aggregate: tonnellate compensate, numero di ordini, importo investito. Perfetto per una pagina «Il nostro impegno climatico».

Hook e filtri per sviluppatori

Il plugin espone un filtro principale per sovrascrivere completamente il calcolo dell’impronta:

add_filter( 'dfcarbon_product_footprint', function( $footprint, $product_id, $context ) {
    // $footprint è un array: ['kg' => 5.2, 'source' => 'ademe', 'breakdown' => [...]]
    // Ritorna un array modificato per sovrascrivere
    return $footprint;
}, 10, 3 );

Altri hook utili:

• dfcarbon_daily_sync — azione WP-Cron giornaliera (purga dei transient Climatiq)
• dfcarbon_before_offset_fee — azione prima dell’aggiunta del fee di compensazione
• dfcarbon_offset_purchased — azione scatenata alla persistenza sull’ordine

Il plugin usa il namespace PHP DataFirefly\CarbonOffset. Per aggiungere un fattore programmaticamente da un mu-plugin o da un tema figlio, importa la classe Database:

use DataFirefly\CarbonOffset\Database;

Database::upsert_factor( [
    'slug'   => 'mio-fattore',
    'label'  => 'Il mio settore specifico',
    'value'  => 2.35,
    'unit'   => 'kg',
    'source' => 'Personalizzato',
    'year'   => 2026,
] );

Multilingue (Polylang / WPML)

Il plugin è compatibile con Polylang Pro e WPML. Le 5 lingue fornite (FR, EN, ES, DE, IT) sono nella cartella languages/ con i file .po e .mo già compilati.

Per modificare una traduzione:

1. Installa Loco Translate (plugin gratuito) o usa Poedit in locale.
2. Apri il catalogo df-carbon-offset-it_IT.po.
3. Modifica le voci.
4. Ricompila in .mo — automatico in Loco Translate.

Per aggiungere una lingua non fornita di default (portoghese, olandese…), duplica un .po esistente, rinominalo con il locale corretto (df-carbon-offset-pt_PT.po, df-carbon-offset-nl_NL.po…), traduci e compila.

Disinstallazione

Il plugin pulisce accuratamente alla disinstallazione tramite uninstall.php:

• Elimina le tabelle dfcarbon_factors e dfcarbon_log
• Elimina le opzioni dfcarbon_settings e dfcarbon_db_version
• Elimina i postmeta _dfcarbon_* da tutti i prodotti e ordini
• Disiscrizione del cron dfcarbon_daily_sync
• Purga dei transient Climatiq

FAQ

Posso forzare un fattore specifico su un prodotto senza cambiare la sua categoria?

Sì. Nella tab Carbon della scheda, seleziona un fattore nel menu a tendina «Fattore di emissione». Prevale sulla mappatura di categoria solo per quel prodotto.

Cosa succede se il mio prodotto non ha peso?

Il calcolo usa un valore forfettario per i prodotti senza peso (trattati come «unità»). Puoi anche usare l’override manuale per inserire direttamente il valore in kg CO₂e.

Il plugin funziona con i prodotti variabili?

Sì. L’impronta viene calcolata a livello di prodotto padre (tramite il suo peso e categoria), il che resta coerente nella maggior parte dei casi. Per un controllo per variazione, usa il filtro dfcarbon_product_footprint.

Come gestisco i prodotti scaricabili (digitali)?

Per un prodotto puramente digitale (ebook, corso online, licenza software), spunta «Nascondi il badge» e lascia il calcolo cadere sul fallback generale (l’impatto sarà minimo se il prodotto non ha peso). Alternativa: usa l’override manuale con un valore piccolo (tipicamente 0,01 a 0,1 kg CO₂e per un ebook).

Posso escludere un prodotto dalla compensazione al checkout?

La compensazione si applica al carrello nel suo insieme, non prodotto per prodotto. Per escludere totalmente un prodotto dal calcolo, usa il filtro dfcarbon_product_footprint restituendo un array con ['kg' => 0].

Il plugin fa chiamate API a ogni visualizzazione di pagina?

No. Ogni impronta prodotto è messa in cache tramite l’API a oggetti di WordPress. Le chiamate Climatiq (se attive) sono a loro volta memorizzate in transient per una settimana. Una pagina prodotto non fa alcuna chiamata esterna.

Compatibile con le cache (WP Rocket, Litespeed, W3TC)?

Sì, totalmente. Il rendering del badge è lato server. La parte dinamica (casella di compensazione al checkout) è gestita in AJAX e non influisce sulla cache della scheda prodotto.