# Carbon Footprint + Offset Checkout: kompletny przewodnik

> Instalacja Carbon Footprint + Offset Checkout to standardowa wtyczka WooCommerce, instalowana jak każde inne rozszerzenie. Pobierz ZIP df-carbon-offset.zip z karty produktu DataFirefly. W panelu WordPressa przejdź do Wtyczki → Dodaj…

- Strona: <https://www.datafirefly.com/pl/documentation/carbon-footprint-offset-checkout/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/carbon-footprint-offset-checkout/index.md), [en](https://www.datafirefly.com/en/documentation/carbon-footprint-offset-checkout/index.md), [es](https://www.datafirefly.com/es/documentation/carbon-footprint-offset-checkout/index.md), [de](https://www.datafirefly.com/de/documentation/carbon-footprint-offset-checkout/index.md), [it](https://www.datafirefly.com/it/documentation/carbon-footprint-offset-checkout/index.md), [nl](https://www.datafirefly.com/nl/documentation/carbon-footprint-offset-checkout/index.md), [pt](https://www.datafirefly.com/pt/documentation/carbon-footprint-offset-checkout/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## 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**.

**Wymagania:** WordPress 6.0 lub nowszy, WooCommerce 7.0 lub nowszy, PHP minimum 7.4 (zalecane PHP 8.1+). Wtyczka wprost deklaruje zgodność z HPOS oraz blokami Cart/Checkout, w WooCommerce Status nie pojawia się żadne ostrzeżenie.

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.

Bez mapowania wszystkie produkty użyją współczynnika `general` (4,50 kgCO₂e/kg), co jest bardzo przybliżone. Staranne mapowanie przenosi Cię z poziomu „rzędu wielkości" na poziom „wiarygodnego szacunku do raportowania".

### 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.

Składowa transportowa dotyczy wyłącznie **transportu w dół łańcucha** (z magazynu do klienta). Ślad materiałowy współczynnika ADEME zawiera już produkcję i transport w górę łańcucha.

## 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`.

**Ważne:** wtyczka **zbiera** kompensację od Twoich klientów, ale **nie kupuje** kredytów węglowych za Ciebie. To celowa decyzja, abyś sam kontrolował moment, kanał i partnera (Gold Standard, Verra, Ecologi, MyClimate i inni). Panel pokazuje sumę do rozliczenia przy każdym cyklu płatności u Twojego partnera.

## 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

Deinstalacja jest **destrukcyjna**: dziennik przeszłych kompensacji zostaje usunięty. Jeśli potrzebujesz go zachować na audyt CSRD, wyeksportuj tabelę `Raporty` przed usunięciem.

## 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.