Carbon Footprint + Offset Checkout: kompletny przewodnik

Instalacja

Carbon Footprint + Offset Checkout to standardowa wtyczka WooCommerce, instalowana jak każde inne rozszerzenie.

1. Pobierz ZIP df-carbon-offset.zip z karty produktu DataFirefly.
2. W panelu WordPressa przejdź do Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer.
3. Wybierz plik ZIP, kliknij Zainstaluj teraz, a następnie Włącz.
4. W bocznym menu WooCommerce pojawia się nowa pozycja Carbon Footprint.

Przy aktywacji automatycznie powstają dwie tabele SQL: {prefix}dfcarbon_factors (współczynniki emisji) i {prefix}dfcarbon_log (dziennik kompensacji). Baza ADEME jest natychmiast zasilana około 25 wstępnie załadowanymi współczynnikami.

Konfiguracja początkowa

Wtyczka działa bez konfiguracji od razu po aktywacji: współczynniki ADEME są załadowane, odznaka wyświetla się na wszystkich kartach produktów, kompensacja pojawia się na checkoucie. Kilka wstępnych korekt da jednak znacznie trafniejsze liczby.

Ustawienia ogólne

Przejdź do Carbon Footprint → Ustawienia. Cztery bloki parametrów:

• API Climatiq: opcjonalne. Zostaw puste, aby działać w 100 % lokalnie na współczynnikach ADEME.
• Kompensacja: włączenie bloku na checkoucie, cena za tonę (domyślnie 25 €/t, typowy rynek 15 do 30 €/t), wyświetlany partner (domyślnie Gold Standard), opis dla klienta.
• Transport: włączenie składowej transportowej, średni dystans w km (domyślnie 500 km), współczynnik emisji transportu (domyślnie transport drogowy).
• Wyświetlanie: pozycja odznaki na karcie produktu (5 dostępnych hooków), styl (karta, plakietka, minimalny), kolor, priorytet hooka.

Mapowanie kategorii na współczynniki

To krok o największym wpływie. Przejdź do Carbon Footprint → Mapowanie. Dla każdej kategorii produktów WooCommerce wybierz najbardziej trafny współczynnik emisji spośród tych z bazy ADEME.

Włączenie API Climatiq (opcjonalne)

Climatiq to baza ponad 80 000 współczynników emisji, dokładniejsza od Bazy Empreinte ADEME w niektórych sektorach (szczegółowa elektronika, kosmetyki per składnik, żywność per łańcuch dostaw). Jeśli masz klucz:

1. Załóż konto na climatiq.io (darmowa oferta dla umiarkowanego użycia).
2. Skopiuj klucz API do Carbon Footprint → Ustawienia → Climatiq API.
3. Kliknij Testuj połączenie, aby zweryfikować.

Po włączeniu API Climatiq używane jest z priorytetem 2 (po ewentualnym ręcznym nadpisaniu na produkcie), przed mapowaniem ADEME. Każdy wynik jest cache’owany przez tydzień: renderowanie stron nie generuje żadnych dodatkowych wywołań.

Jak działa obliczanie śladu

Priorytety obliczeń

Dla każdego produktu wtyczka ustala ślad z czterech źródeł, w ścisłej kolejności priorytetów:

1. Ręczne nadpisanie na produkcie: jeśli wpisano wartość w zakładce „Carbon” karty produktu (meta _dfcarbon_kgco2e), używana jest właśnie ona. Omija wszystkie pozostałe źródła.
2. API Climatiq: jeśli skonfigurowano klucz API, a produkt ma wagę albo kategorię możliwą do odpytania.
3. Współczynnik ADEME przez mapowanie: współczynnik przypisany kategorii produktu, stosowany do wagi.
4. Ogólny fallback: współczynnik general (4,50 kgCO₂e/kg) stosowany do wagi, albo wartość ryczałtowa, jeśli waga nie jest uzupełniona.

Obliczenie jest cache’owane przez API obiektowe WordPressa (grupa dfcarbon_product) i automatycznie unieważniane przy każdej zmianie karty produktu albo mapowania.

Składowa transportowa

Jeśli włączona, składowa transportowa dodawana jest do śladu materiałowego:

slad_calkowity = slad_materialowy + (waga_kg × dystans_km × wspolczynnik_transportu_tkm)

Domyślny współczynnik transportu drogowego wynosi 0,105 kgCO₂e na tonokilometr (źródło ADEME, średni pojazd ciężarowy). Możesz zmienić współczynnik transportu w ustawieniach albo przełączyć się na inny (transport morski, lotniczy i tak dalej), jeśli dodasz go do bazy.

Dołączone współczynniki emisji ADEME

Wtyczka dostarczana jest z około 25 wstępnie załadowanymi współczynnikami z Bazy Empreinte ADEME (Francja). Główne pokryte sektory:

• Tekstylia: odzież standardowa, bawełna, wełna, syntetyk, obuwie
• Elektronika: smartfon, laptop, małe AGD, duże AGD
• Żywność: wołowina, wieprzowina, drób, ryby, nabiał, artykuły suche
• Kosmetyki: pielęgnacja ciała, makijaż, perfumeria
• Dom: meble drewniane, meble metalowe, tekstylia domowe
• Papier: książka, magazyn, karton opakowaniowy
• Sport: sprzęt sportowy, odzież sportowa
• Biżuteria: biżuteria sztuczna, srebro, złoto
• Transport: transport drogowy, transport morski
• Fallback: general (4,50 kgCO₂e/kg)

Współczynniki możesz przeglądać, edytować, usuwać i dodawać własne w Carbon Footprint → Współczynniki. Każdy współczynnik ma: unikalny slug, etykietę, wartość w kgCO₂e/jednostkę, jednostkę (domyślnie kg), źródło (ADEME, Climatiq, własne i inne) oraz rok.

Przycisk Załaduj ponownie domyślne wartości ADEME przywraca bazę pierwotną bez nadpisywania Twoich własnych wpisów: ponownie wstawiane są wyłącznie brakujące slugi ADEME.

Odznaka na produkcie

Dostępne style

Trzy warianty do wyboru (regulowane w Ustawienia → Wyświetlanie → Styl odznaki):

• Karta (szczegółowa): pełny blok ze śladem, źródłem, dwoma edukacyjnymi porównaniami (km samochodem, lata drzewa) i ceną kompensacji.
• Plakietka w linii: kompaktowa odznaka „🌱 5,2 kg CO₂e” obok ceny.
• Minimalny tekst: sama wartość, bez ramki.

Pozycje

Odznaka doczepia się do jednego ze standardowych hooków WooCommerce:

• after_price: tuż po cenie (domyślnie)
• before_add_to_cart: przed przyciskiem dodania do koszyka
• after_add_to_cart: po przycisku dodania do koszyka
• before_meta: przed metadanymi produktu
• after_summary: po pełnym podsumowaniu produktu

Jeśli żadna pozycja nie pasuje do Twojego motywu, możesz użyć shortcode’u [dfcarbon_badge] bezpośrednio w szablonie albo builderze wizualnym (Elementor, Divi, Gutenberg i inne).

Ukrywanie na wybranych produktach

W zakładce Carbon każdej karty produktu zaznacz „Ukryj odznakę”. Obliczanie śladu pozostaje aktywne (przydatne do raportów i checkoutu), ale publiczne wyświetlanie znika. Praktyczne przy produktach cyfrowych, kartach podarunkowych i usługach.

Kompensacja na checkoucie

Na checkoucie wtyczka wstawia blok między podsumowaniem zamówienia a metodą płatności. Blok zawiera:

• Szacowany ślad koszyka (suma śladów wszystkich pozycji × ich ilości)
• Odpowiadający koszt kompensacji (ślad × cena za tonę)
• Opcjonalne pole wyboru „Tak, dodaję X €, aby skompensować wpływ mojego zamówienia”
• Konfigurowalny tekst opisowy wskazujący partnera (Gold Standard, Verra i inni)

Gdy klient zaznaczy pole, do sumy dodawana jest dynamiczna opłata WooCommerce przez hook woocommerce_cart_calculate_fees. Stan przechowywany jest w sesji WooCommerce (dfcarbon_offset_active), a następnie utrwalany na zamówieniu przez meta _dfcarbon_cart_kgco2e, _dfcarbon_offset_active, _dfcarbon_offset_amount i _dfcarbon_offset_provider.

Panel i raporty

Menu Carbon Footprint → Panel pokazuje wskaźniki globalne:

• Łączna liczba skompensowanych zamówień
• Skumulowany ślad CO₂ zmierzony na zamówieniach
• Ślad CO₂ faktycznie skompensowany
• Łączna kwota zainwestowana w kompensację

Menu Carbon Footprint → Raporty wyszczególnia każde skompensowane zamówienie: datę, numer zamówienia, ślad zamówienia, skompensowane kilogramy, kwotę, partnera. Ta tabela zasila bezpośrednio Twoje raportowanie pozafinansowe CSRD i każde zapytanie audytowe CSR.

Zdjęcie śladu przechowywane jest też per pozycja zamówienia (meta _dfcarbon_line_kgco2e): wyświetlane wartości nie zmieniają się wstecznie, gdy później zmodyfikujesz współczynnik ADEME.

Dostępne shortcode’y

Trzy publiczne shortcode’y do osadzania elementów w dowolnym miejscu witryny:

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

Wyświetla odznakę węglową konkretnego produktu. id jest obowiązkowe, style opcjonalny (domyślnie card, także pill, minimal).

[dfcarbon_cart_summary]

Wyświetla ślad bieżącego koszyka i koszt kompensacji. Przydatne na własnej stronie „Mój koszyk” albo w side-carcie.

[dfcarbon_stats]

Publiczny blok ze zagregowanymi statystykami: skompensowane tony, liczba zamówień, zainwestowana kwota. Idealny na stronę „Nasze zobowiązanie klimatyczne”.

Hooki i filtry dla deweloperów

Wtyczka udostępnia główny filtr do pełnego nadpisania obliczeń śladu:

add_filter( 'dfcarbon_product_footprint', function( $footprint, $product_id, $context ) {
    // $footprint is an array: ['kg' => 5.2, 'source' => 'ademe', 'breakdown' => [...]]
    // Return a modified array to override
    return $footprint;
}, 10, 3 );

Inne przydatne hooki:

• dfcarbon_daily_sync: codzienna akcja WP-Cron (czyszczenie transientów Climatiq)
• dfcarbon_before_offset_fee: akcja przed dodaniem opłaty kompensacyjnej
• dfcarbon_offset_purchased: akcja wyzwalana przy utrwaleniu na zamówieniu

Wtyczka używa przestrzeni nazw PHP DataFirefly\CarbonOffset. Aby dodać współczynnik programistycznie z mu-plugina albo motywu potomnego, zaimportuj klasę Database:

use DataFirefly\CarbonOffset\Database;

Database::upsert_factor( [
    'slug'   => 'my-factor',
    'label'  => 'My specific sector',
    'value'  => 2.35,
    'unit'   => 'kg',
    'source' => 'Custom',
    'year'   => 2026,
] );

Wielojęzyczność (Polylang / WPML)

Wtyczka jest zgodna z Polylang Pro i WPML. 5 dostarczanych języków (FR, EN, ES, DE, IT) znajduje się w katalogu languages/, z już skompilowanymi plikami .po i .mo.

Aby poprawić tłumaczenie:

1. Zainstaluj Loco Translate (darmowa wtyczka) albo użyj Poedita lokalnie.
2. Otwórz katalog df-carbon-offset-fr_FR.po.
3. Edytuj wpisy do przetłumaczenia.
4. Skompiluj ponownie do .mo: w Loco Translate dzieje się to automatycznie.

Aby dodać nowy język spoza kompletu (portugalski, niderlandzki i inne), zduplikuj istniejący .po, zmień nazwę na właściwe locale (df-carbon-offset-pt_PT.po, df-carbon-offset-nl_NL.po i tak dalej), przetłumacz i skompiluj.

Deinstalacja

Wtyczka porządnie sprząta przy deinstalacji przez uninstall.php:

• Usunięcie tabel dfcarbon_factors i dfcarbon_log
• Usunięcie opcji dfcarbon_settings i dfcarbon_db_version
• Usunięcie postmeta _dfcarbon_* ze wszystkich produktów i zamówień
• Wyrejestrowanie crona dfcarbon_daily_sync
• Wyczyszczenie transientów Climatiq

FAQ

Czy mogę wymusić konkretny współczynnik na produkcie bez zmiany jego kategorii?

Tak. W zakładce Carbon karty produktu wybierz współczynnik z listy rozwijanej „Współczynnik emisji”. Ma on pierwszeństwo przed mapowaniem kategorii, wyłącznie dla tego produktu.

Co się dzieje, gdy produkt nie ma wagi?

Obliczenie używa wartości ryczałtowej dla produktów bez wagi (traktowanych jako „sztuka”). Możesz też użyć ręcznego nadpisania i wpisać wartość w kg CO₂e bezpośrednio.

Czy wtyczka działa z produktami wariantowymi?

Tak. Ślad liczony jest na poziomie produktu nadrzędnego (przez jego wagę i kategorię), co pozostaje spójne w większości przypadków. Do sterowania per wariant użyj filtra dfcarbon_product_footprint.

Jak obsłużyć produkty do pobrania (cyfrowe)?

Dla produktu czysto cyfrowego (ebook, kurs online, licencja) zaznacz „Ukryj odznakę” i pozwól obliczeniu spaść na ogólny fallback (wpływ będzie minimalny, jeśli produkt nie ma wagi). Alternatywa: użyj ręcznego nadpisania z małą wartością (typowo 0,01 do 0,1 kg CO₂e dla ebooka).

Czy mogę wykluczyć produkt z kompensacji na checkoucie?

Kompensacja dotyczy koszyka jako całości, nie pojedynczych produktów. Jeśli produkt ma być całkowicie wyłączony z obliczeń, użyj filtra dfcarbon_product_footprint i zwróć tablicę z ['kg' => 0].

Czy wtyczka wykonuje wywołania API przy każdej odsłonie strony?

Nie. Ślad każdego produktu jest cache’owany przez API obiektowe WordPressa. Wywołania Climatiq (jeśli włączone) są dodatkowo cache’owane w transientach przez tydzień. Strona produktu nie wywołuje żadnych zapytań zewnętrznych.

Zgodne z cache (WP Rocket, LiteSpeed, W3TC)?

Tak, w pełni. Renderowanie odznaki jest statyczne po stronie serwera. Część dynamiczna (pole kompensacji na checkoucie) obsługiwana jest w AJAX i nie wpływa na cache’owanie karty produktu.