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

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.

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:

Cart::getOrderTotal(
    $with_taxes = (bool) CFG_TAX_INCL,
    $type = CFG_INCLUDE_SHIPPING ? Cart::BOTH : Cart::ONLY_PRODUCTS
);

Gwarantuje to, że wartość użyta do porównania jest identyczna z tą, którą PrestaShop pokazuje w podsumowaniu 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.

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.

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.

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.

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

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

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: <opis błędu>

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ł).

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

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.0 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, 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])