# dffreegift: prezent gratis po przekroczeniu progu koszyka: pełny przewodnik
> Pełny przewodnik po module dffreegift dla PrestaShop 8 i 9: instalacja, konfiguracja, działanie wewnętrzne (natywna reguła CartRule), personalizacja, rozwiązywanie problemów i deinstalacja. Każdy etap opisano wraz z dokładnymi parametrami do…
- Strona:
- Język: pl
- Zaktualizowano: 2026-10-28
- Inne języki: [fr](https://www.datafirefly.com/documentation/dffreegift/index.md), [en](https://www.datafirefly.com/en/documentation/dffreegift/index.md), [es](https://www.datafirefly.com/es/documentation/dffreegift/index.md), [de](https://www.datafirefly.com/de/documentation/dffreegift/index.md), [it](https://www.datafirefly.com/it/documentation/dffreegift/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffreegift/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffreegift/index.md)
- Indeks:
Pełny przewodnik po module **dffreegift** dla PrestaShop 8 i 9: instalacja, konfiguracja, działanie wewnętrzne (natywna reguła `CartRule`), personalizacja, rozwiązywanie problemów i deinstalacja. Każdy etap opisano wraz z dokładnymi parametrami do zastosowania na produkcji.
## Przegląd
dffreegift automatycznie dodaje produkt gratis do koszyka, gdy tylko skonfigurowany próg zostanie osiągnięty, i usuwa go, jeśli koszyk spadnie poniżej progu. Mechanika opiera się w całości na natywnym systemie `CartRule` PrestaShop (pole `gift_product`): moduł nigdy nie manipuluje bezpośrednio cenami produktów, nie tworzy tymczasowych `SpecificPrice` i nie wstrzykuje niczego w hooki przeliczania cen. Efekt: pełna zgodność z Twoimi pozostałymi promocjami, kodami rabatowymi, podatkami i wielowalutowością.
Moduł wyświetla też **blok postępu** na stronie koszyka z komunikatem „Dodaj X zł, aby otrzymać prezent”, kolorowym paskiem wypełniającym się w miarę zbliżania do progu oraz animacją przy jego przekroczeniu.
## Wymagania
- PrestaShop 8.0 do 9.x (testowany na 8.0, 8.1, 8.2, 9.0)
- PHP minimum 8.1 (obsługiwane 8.2 i 8.3)
- Aktywny produkt w katalogu, który posłuży jako prezent (produkt prosty albo z wariantami)
- Dostęp administratora do back office PrestaShop
## Instalacja
1. W back office przejdź do **Moduły → Menedżer modułów → Wgraj moduł**.
2. Wgraj plik `dffreegift-1.0.1.zip`.
3. Kliknij **Zainstaluj**, a następnie **Konfiguruj**.
Przy instalacji moduł wykonuje w tle następujące operacje:
- Rejestracja 5 hooków: `actionCartSave`, `actionObjectCartRuleDeleteBefore`, `displayShoppingCart`, `displayCartExtraProductActions`, `displayHeader`.
- Zapis domyślnych wartości konfiguracji (próg 50 w walucie sklepu, przeliczanie brutto, bez kosztów wysyłki, weryfikacja stanu magazynowego włączona).
- Utworzenie „ukrytej” reguły `CartRule` z unikalnym kodem typu `DFFREEGIFT_A7B3F2D9`, widocznej w **Katalog → Rabaty → Reguły koszyka**.
**Uwaga.** Reguła CartRule utworzona przy instalacji nie ma jeszcze przypisanego produktu gratis (`gift_product = 0`), więc funkcjonalnie nie jest aktywna. Zostanie zsynchronizowana, gdy tylko zapiszesz ID produktu gratis na ekranie konfiguracji.
**Aktualizacja z wersji 1.0.0.** Wgraj plik zip 1.0.1 na zainstalowaną wersję: konfiguracja zostaje zachowana, a reguła koszyka otrzymuje przetłumaczoną nazwę („Prezent gratis”…).
## Konfiguracja
Ekran konfiguracji znajduje się w **Moduły → DataFirefly Free Gift → Konfiguruj**. Wszystkie parametry zebrano w jednym formularzu.
### Włącz moduł
Przełącznik **Włącz moduł** działa jak wyłącznik główny. W pozycji _Nie_ moduł pozostaje zainstalowany, ale nic nie robi: brak auto-dodawania, brak bloku na froncie, brak przeliczania progu. Przydatne, aby tymczasowo wyłączyć ofertę (na przykład po zakończeniu akcji sezonowej) bez utraty konfiguracji.
### Produkt gratis i wariant
Dwa pola do uzupełnienia w tej kolejności:
1. **ID produktu gratis**: wpisz identyfikator PrestaShop produktu, który chcesz dawać w prezencie. ID znajdziesz w **Katalog → Produkty** (kolumna ID). Po pierwszym zapisie nazwa produktu pojawia się w pomocy pod polem jako potwierdzenie.
2. **Wariant**: lista rozwijana z kombinacjami dostępnymi dla produktu. Wypełnia się automatycznie _po_ zapisaniu ID produktu. Wybierz konkretny wariant (na przykład „Rozmiar M, kolor czarny”) albo zostaw _— Bez wariantu —_ dla produktu prostego.
**Wskazówka.** Jeśli później zmienisz produkt gratis, reguła CartRule zostanie automatycznie zsynchronizowana przy zapisie. Nie musisz ręcznie dotykać reguły w sekcji Rabaty.
### Próg uruchomienia
Pole **Próg uruchomienia** określa kwotę koszyka, od której prezent jest dodawany. Dwa powiązane parametry decydują o podstawie przeliczania:
- **Przeliczanie brutto**: jeśli włączone, suma zawiera wszystkie podatki naliczone w koszyku. Jeśli wyłączone, próg jest porównywany z sumą netto. Większość sklepów B2C pracuje na kwotach brutto, sklepy B2B często liczą w netto.
- **Uwzględnij koszty wysyłki**: jeśli włączone, szacowany koszt dostawy jest doliczany do sumy przed porównaniem. W praktyce rzadko się to włącza, ponieważ koszty wysyłki nie zawsze są policzone w momencie, gdy klient ogląda koszyk (brak wybranego przewoźnika oznacza 0 zł).
W praktyce oceniana suma odpowiada natywnemu wywołaniu PrestaShop:
```
$amount = Cart::getOrderTotal(
$with_taxes = (bool) CFG_TAX_INCL,
$type = CFG_INCLUDE_SHIPPING ? Cart::BOTH : Cart::ONLY_PRODUCTS
);
if (!CFG_INCLUDE_SHIPPING) {
$amount -= $giftValue; // wartość prezentu już dodanego
}
```
Bez kosztów wysyłki wartość prezentu, który jest już w koszyku, jest odejmowana od sumy (od wersji 1.0.1): prezent nigdy nie liczy się do osiągnięcia progu i jest usuwany, gdy pozostałe produkty znów spadną poniżej niego. Z kosztami wysyłki `Cart::BOTH` już odejmuje rabaty, łącznie z prezentem. Kwoty pochodzą z natywnych metod PrestaShop, tak jak podsumowanie koszyka.
### Weryfikacja stanu magazynowego
Przełącznik **Weryfikuj stan magazynowy prezentu** (domyślnie włączony) wstrzymuje auto-dodawanie, jeśli produktu gratis brakuje. Kontrola respektuje strategię _out of stock_ skonfigurowaną globalnie w PrestaShop:
- Jeśli produkt jest oznaczony jako „zezwalaj na zamówienia przy braku towaru”, auto-dodawanie pozostaje aktywne nawet przy ilości 0.
- Jeśli produkt nie pozwala zamawiać przy braku towaru, auto-dodawanie jest wstrzymywane, gdy ilość osiągnie 0.
**Zalecenie.** Zostaw tę weryfikację włączoną. Wyłączenie kontroli może prowadzić do zamówień zablokowanych w checkoucie z powodu braku prezentu na stanie, co oznacza gorsze doświadczenie klienta i konieczność ręcznej interwencji.
### Ograniczenie do grup klientów
Siatka **Uprawnione grupy klientów** wymienia wszystkie grupy sklepu z polem wyboru przy każdej z nich. Dwa zachowania:
- **Żadne pole nie zaznaczone**: uprawnieni są wszyscy klienci, łącznie z niezalogowanymi gośćmi (pod warunkiem, że domyślna grupa `PS_UNIDENTIFIED_GROUP` nie jest wykluczona, co jest zachowaniem domyślnym).
- **Jedno albo więcej pól zaznaczonych**: blok postępu i auto-dodawanie działają wyłącznie dla klientów należących do przynajmniej jednej zaznaczonej grupy.
Typowe zastosowania:
- Prezent zarezerwowany dla grupy „Profesjonaliści” przy klienteli B2B.
- Prezent zarezerwowany dla grupy „VIP” w programie lojalnościowym.
- Prezent dostępny dla wszystkich _poza_ resellerami (zaznacz wszystkie grupy poza grupą resellerów).
### Opcje wyświetlania
Dwa niezależne przełączniki sterują wyglądem bloku na froncie:
- **Wyświetl komunikat postępu**: całkowicie włącza albo wyłącza blok na stronie koszyka. W pozycji _Nie_ auto-dodawanie nadal działa, ale klient nie widzi żadnego komunikatu (przydatne, jeśli chcesz sterować wyświetlaniem z poziomu własnego motywu).
- **Wyświetl pasek postępu**: włącza albo wyłącza kolorowy pasek pod komunikatem. Sam tekst komunikatu pozostaje widoczny.
Konfiguracja DataFirefly Free Gift: produkt w prezencie, próg koszyka, obliczanie brutto, wysyłka i grupy klientów
## Jak to działa technicznie
### Ukryta reguła CartRule
Zamiast manipulować cenami produktów, dffreegift wykorzystuje natywny mechanizm prezentu PrestaShop przez `CartRule`. Przy instalacji tworzona jest reguła o następujących właściwościach:
- `code` = `DFFREEGIFT_A7B3F2D9` (przyrostek generowany losowo przy instalacji)
- `gift_product` = 0 (aktualizowane przy każdym zapisie konfiguracji)
- `gift_product_attribute` = 0 (aktualizowane przy każdym zapisie konfiguracji)
- `quantity` = 999 999 i `quantity_per_user` = 999 999 (praktycznie bez limitu)
- `date_from` = teraz, `date_to` = +50 lat
- `active` = 1, bez kodu, bez rabatu, bez ograniczeń produktowych ani kategoryjnych
Gdy próg zostanie osiągnięty, moduł dołącza tę regułę do koszyka przez `Cart::addCartRule($id)`. Resztą zajmuje się PrestaShop:
- Wstawienie linii koszyka z `gift = 1` i `price = 0`.
- Wyświetlenie w podsumowaniu koszyka z etykietą „Prezent”.
- Uwzględnienie przy konwersji na zamówienie.
- Zapis historyczny w zamówieniu (prezent pozostaje widoczny, nawet jeśli później zmienisz produkt gratis).
Gdy koszyk spadnie poniżej progu, moduł odłącza regułę przez `Cart::removeCartRule($id)`. Linia prezentu jest usuwana w tym samym żądaniu.
Reguła koszyka PrestaShop utworzona przez moduł, z akcją wysyłającą produkt w prezencie
Składanie zamówienia: produkt w prezencie widnieje w podsumowaniu zamówienia wraz z rabatem
### Używane hooki
- **actionCartSave**: hook główny. Wywoływany przy każdym zapisie koszyka (dodanie, zmiana, usunięcie, logowanie klienta ze scaleniem koszyka). Moduł przelicza sumę i decyduje, czy dołączyć, czy odłączyć regułę. Statyczna flaga `self::$syncing` zapobiega rekurencji, gdyby dołączenie reguły samo wyzwoliło zapis.
- **actionObjectCartRuleDeleteBefore**: automatyczna naprawa. Jeśli administrator ręcznie usunie ukrytą regułę z **Katalog → Rabaty**, ten hook wykrywa usunięcie i zeruje ID w konfiguracji. Kolejna synchronizacja odtworzy czystą regułę.
- **displayHeader**: rejestruje CSS i JS po stronie frontu (`views/css/dffreegift.css` i `views/js/dffreegift.js`).
- **displayShoppingCart**: renderuje blok postępu na stronie koszyka.
- **displayCartExtraProductActions**: zarezerwowany pod przyszłe rozszerzenia (etykieta na linii prezentu).
### Przeliczanie progu
Przy każdym wywołaniu `syncCartGift()` moduł sprawdza w tej kolejności:
1. Czy moduł jest włączony? (jeśli nie, kończymy)
2. Czy klient jest uprawniony według skonfigurowanych grup? (jeśli nie, odłączamy regułę, o ile była dołączona)
3. Czy produkt gratis jest poprawny (istnieje, jest aktywny, jest na stanie przy włączonej weryfikacji)? (jeśli nie, odłączamy)
4. Przeliczenie sumy zgodnie z ustawieniem brutto/netto oraz kosztami wysyłki uwzględnionymi albo pominiętymi.
5. Porównanie z progiem z tolerancją zaokrąglenia 0,001.
6. Dołączenie reguły, jeśli próg osiągnięty, a reguła nie jest jeszcze dołączona. Odłączenie, jeśli suma spadła poniżej progu, a reguła jest dołączona.
## Blok postępu na froncie
Blok wyświetla się automatycznie na stronie koszyka, między podsumowaniem produktów a sumą. Dwa stany wizualne:
- **Oczekiwanie** (próg nieosiągnięty): jasnoszare tło, komunikat „Dodaj X,XX zł, aby otrzymać prezent”, pomarańczowy pasek wypełniający się w miarę zbliżania do progu.
- **Cel osiągnięty** (próg przekroczony): jasnozielone tło, komunikat „Prezent dodany do koszyka!”, pasek wypełniony na zielono. Przy przejściu ze stanu _oczekiwania_ do stanu _osiągnięty_ uruchamia się animacja `pulse`.
Od wersji 1.0.1 blok odświeża się bez przeładowania strony przy każdej zmianie koszyka (ilość, usunięcie produktu). Rabat, dzięki któremu prezent jest darmowy, klient widzi pod przetłumaczoną nazwą: „Prezent gratis”, „Free gift”, „Cadeau offert”, „Regalo gratuito”, „Gratis-Geschenk”, „Omaggio”, „Brinde” lub „Gratis cadeau”, zależnie od języka.
Koszyk: komunikat z kwotą brakującą do prezentu i pasek postępu
Próg osiągnięty: produkt w prezencie trafia automatycznie do koszyka i jest darmowy dzięki rabatowi Prezent gratis
Koszyk ponownie poniżej progu: prezent jest automatycznie usuwany, a komunikat odświeża się bez przeładowania strony
### Personalizacja kolorów
Kolory są zdefiniowane w `views/css/dffreegift.css`. Aby je zmienić bez modyfikowania modułu (co przy aktualizacjach nadpisałoby Twoje zmiany), nadpisz klasy w CSS swojego motywu:
```
.dffreegift-progress {
border-color: #twoj-kolor;
background: #twoje-tlo;
}
.dffreegift-progress--reached {
background: #twoja-jasna-zielen;
border-color: #twoja-zielen;
}
.dffreegift-progress__bar-fill {
background: linear-gradient(90deg, #kolor1, #kolor2);
}
```
### Personalizacja tekstów
Teksty wyświetlane klientowi są tłumaczalne standardowym mechanizmem PrestaShop. Przejdź do **Międzynarodowe → Tłumaczenia**, wybierz „Tłumaczenia modułów”, wskaż _dffreegift_ oraz język, a następnie odszukaj domenę `Modules.Dffreegift.Shop`. Dostępne ciągi:
- _„Dodaj %amount%, aby otrzymać prezent”_: komunikat w stanie oczekiwania (`%amount%` jest automatycznie zastępowane pozostałą kwotą sformatowaną zgodnie z walutą i lokalizacją).
- _„Prezent dodany do koszyka!”_: komunikat po osiągnięciu celu.
- _„Postęp do prezentu”_: etykieta ARIA paska (odczytywana przez czytniki ekranu).
Moduł jest dostarczany przetłumaczony na 8 języków, zarówno w back office, jak i na froncie: francuski (język źródłowy), angielski, hiszpański, niemiecki, włoski, portugalski, polski i niderlandzki. Te tłumaczenia są punktem wyjścia; możesz je zmienić w sposób opisany powyżej.
## Współistnienie z innymi promocjami
Ponieważ prezent jest dodawany przez natywną regułę `CartRule`, współistnieje normalnie z każdą inną regułą `CartRule`. Oczekiwane zachowania:
- **Inne kody rabatowe klienta** (rabat procentowy, kwotowy, darmowa wysyłka): działają równolegle z prezentem. Prezent nie konsumuje rabatu i odwrotnie.
- **Inna reguła ze skonfigurowanym gift_product**: PrestaShop traktuje obie jako niezależne i dodaje oba prezenty. Uważaj przy łączeniu kilku modułów prezentowych.
- **Reguła z product_restriction** wykluczającym produkt gratis: reguła ograniczająca ma pierwszeństwo. Prezent nie zostanie dodany, jeśli inna aktywna reguła jawnie go wyklucza.
- **Reguła z cart_rule_restriction**: jeśli inna reguła zabrania użycia naszej przez ograniczenie krzyżowe, auto-dodawanie jest blokowane (natywne zachowanie PrestaShop).
**Uwaga.** Próg dffreegift jest przeliczany na sumie _bez prezentu_. Jeśli inna reguła koszyka obniża sumę, zanim dffreegift ją oceni, porównanie odbywa się na sumie _po_ rabacie. Koszyk za 250 zł z rabatem 60 zł spada do 190 zł i nie uruchomi progu 200 zł.
## Multistore
Moduł działa z konfiguracją multistore PrestaShop w **kontekście domyślnego sklepu**. Konfiguracje (próg, produkt gratis, opcje) są zapisywane przez `Configuration::updateValue`, które respektuje bieżący kontekst sklepu. Reguła `CartRule` utworzona przy instalacji jest powiązana ze sklepem aktywnym w momencie instalacji.
Przy wdrożeniu multistore z _różnymi prezentami per sklep_ trzeba obecnie zainstalować i skonfigurować moduł osobno w każdym kontekście sklepu. W sprawie wariantu z jawnym zakresowaniem per `id_shop` skontaktuj się ze wsparciem.
## Rozwiązywanie problemów
### Prezent nie dodaje się do koszyka
Sprawdź w tej kolejności:
1. Czy moduł jest włączony? (Moduły → Konfiguruj → przełącznik _Włącz moduł_).
2. Czy produkt gratis jest poprawny? (właściwe ID, produkt aktywny, na stanie przy włączonej weryfikacji stanu).
3. Czy klient należy do uprawnionej grupy? (jeśli ograniczyłeś ofertę do grup, niezalogowany gość spoza uprawnionych grup nie zobaczy niczego).
4. Czy próg jest faktycznie osiągnięty? Przelicz sumę ręcznie zgodnie ze swoimi parametrami (brutto/netto, z wysyłką albo bez).
5. Czy ukryta reguła `CartRule` istnieje i jest aktywna? Przejdź do **Katalog → Rabaty → Reguły koszyka** i poszukaj `DFFREEGIFT_`.
### Blok postępu nie pojawia się na stronie koszyka
Najczęstsze przyczyny:
- Przełącznik _Wyświetl komunikat postępu_ jest w pozycji _Nie_.
- Klient nie jest uprawniony według skonfigurowanych grup klientów.
- Produkt gratis jest niepoprawny (nie istnieje, jest nieaktywny albo brakuje go na stanie przy włączonej weryfikacji stanu).
- Twój własny motyw nie wywołuje hooka `displayShoppingCart`. Sprawdź poleceniem `grep -r "displayShoppingCart" themes/twoj-motyw/` albo w **Moduły → Pozycje**.
### Reguła CartRule zniknęła z back office
Jeśli ktoś usunął regułę z **Katalog → Rabaty**, hook `actionObjectCartRuleDeleteBefore` wykrył usunięcie i wyzerował konfigurację. Przy kolejnej synchronizacji koszyka (czyli przy następnym dodaniu produktu przez klienta) automatycznie tworzona jest nowa reguła z nowym kodem `DFFREEGIFT_xxxxxxxx`.
Aby wymusić regenerację natychmiast, bez czekania na klienta:
1. Przejdź do **Moduły → DataFirefly Free Gift → Wyłącz**.
2. Następnie **Włącz** ponownie. To odtwarza czystą regułę.
### Błędy w logach PrestaShop
Moduł loguje wyjątki w **Parametry zaawansowane → Logi** z prefiksem `[dffreegift]`. Typowy komunikat przy problemie:
```
[dffreegift] actionCartSave error:
```
Te błędy nigdy nie przerywają działania koszyka, mają wyłącznie charakter informacyjny. Przy powtarzającym się logu przekaż pełny komunikat do wsparcia.
### Próg wydaje się źle policzony
Przeliczanie zależy ściśle od Twoich parametrów _Przeliczanie brutto_ i _Uwzględnij koszty wysyłki_. Aby sprawdzić, co zwraca PrestaShop:
- Brutto bez wysyłki: odpowiada pozycji _Suma częściowa produktów brutto_ w podsumowaniu koszyka.
- Brutto z wysyłką: odpowiada pozycji _Suma brutto_ (produkty plus koszty wysyłki, jeśli wybrano przewoźnika).
- Netto bez wysyłki: odpowiada pozycji _Suma częściowa produktów netto_.
- Netto z wysyłką: odpowiada pozycji _Suma netto_ (produkty plus koszty wysyłki netto).
Jeśli widzisz rozbieżność, porównaj z dokładną linią podsumowania koszyka. Z dużym prawdopodobieństwem różnica wynika z kosztów wysyłki, które nie zostały jeszcze policzone (klient nie wybrał jeszcze przewoźnika, więc koszt wynosi 0 zł).
Gdy prezent jest już w koszyku, wyświetlana suma częściowa obejmuje go w zwykłej cenie, zrównoważonej linią rabatu „Prezent gratis”. Moduł porównuje z progiem sumę _bez prezentu_.
## Deinstalacja
Przejdź do **Moduły → Menedżer modułów → DataFirefly Free Gift → Odinstaluj**. Deinstalacja usuwa:
- Ukrytą regułę `CartRule` i wszystkie jej powiązania z koszykami (bieżące koszyki automatycznie stracą prezent).
- Wszystkie klucze konfiguracji z prefiksem `DFFREEGIFT_`.
**Uwaga.** Deinstalacja nie przywraca prezentów w złożonych zamówieniach: zachowują one swój pierwotny zapis historyczny z poprawnie zarejestrowanym prezentem. Wpływ dotyczy wyłącznie bieżących koszyków.
## Szybkie FAQ
- **Czy prezent pojawia się w minikoszyku w nagłówku?** Nie, wyłącznie na stronie koszyka (hook `displayShoppingCart`). Minikoszyk jest obsługiwany inaczej przez każdy motyw i wymagałby integracji motyw po motywie. Na życzenie u wsparcia.
- **Czy mogę dawać kilka prezentów przy kilku progach (na przykład prezent A od 200 zł, prezent B od 400 zł)?** Nie, wersja 1.0.1 obsługuje jeden prezent i jeden próg. W sprawie kilku poziomów skontaktuj się ze wsparciem.
- **Czy prezent jest uwzględniany przy zwrotach?** Jak każdy natywny produkt gratis PrestaShop, prezent widnieje w zamówieniu w cenie 0. Przy zwrocie częściowym pozostaje w zamówieniu bez wpływu finansowego.
- **Czy mogę modyfikować plik dffreegift.php bezpośrednio?** Technicznie tak (kod jest niezaszyfrowany), ale oficjalne aktualizacje nadpiszą Twoje zmiany. Przy głębokiej personalizacji utwórz osobny moduł override.
## Wsparcie i aktualizacje
Moduł zawiera **12 miesięcy aktualizacji i wsparcia** od daty zakupu. Wsparcie e-mailowe po francusku albo angielsku, odpowiedź w ciągu 24 godzin roboczych.
W razie pytań albo nieprawidłowości skontaktuj się ze [wsparciem DataFirefly](https://www.datafirefly.com/pl/kontakt/), podając:
- Wersję PrestaShop (widoczną w **Parametry zaawansowane → Informacje**)
- Wersję PHP
- Wersję zainstalowanego modułu dffreegift
- Opis zaobserwowanego zachowania w zestawieniu z oczekiwanym
- Wycinek logów PrestaShop, jeśli dotyczy (`[dffreegift]`)