Pasek darmowej dostawy (dffreeshipbar) — Kompletny przewodnik

Kompletny przewodnik po module dffreeshipbar dla PrestaShop 8 i 9: instalacja, progi dla krajów i regionów, filtrowanie według przewoźnika, pozycje wyświetlania, obsługa wielu sklepów i rozwiązywanie problemów. Wszystkie reguły ustalania progu są opisane, wraz z przypadkami granicznymi.

Przegląd

dffreeshipbar wyświetla pasek postępu informujący klienta, ile jeszcze musi wydać, aby otrzymać darmową dostawę. Po osiągnięciu progu komunikat zmienia się w potwierdzenie.

Moduł działa na własnych progach, zapisanych we własnych tabelach. Nigdy nie odczytuje natywnej zmiennej PS_SHIPPING_FREE_PRICE: możesz zostawić ją na 0 i sterować darmową dostawą przez przedziały przewoźnika bez żadnego konfliktu.

Wyróżnikiem modułu jest dwupoziomowe ustalanie progu według terytorium. Próg można zdefiniować na poziomie kraju, ale również na poziomie regionu PrestaShop — co pozwala odmiennie traktować terytoria administracyjnie przypisane do tego samego kraju, na przykład departamenty zamorskie należące do Francji metropolitalnej.

Wymagania

• PrestaShop od 8.0 do 9.x
• PHP minimum 7.4 (obsługiwane 8.0 – 8.3)
• Motyw Classic, Hummingbird lub dowolny motyw własny wywołujący standardowe hooki
• Dostęp administratora do panelu

Instalacja

1. W panelu przejdź do Moduły → Menedżer modułów → Wgraj moduł.
2. Wgraj plik dffreeshipbar-2.1.0.zip.
3. Kliknij Zainstaluj, a następnie Konfiguruj.

Podczas instalacji moduł tworzy dwie tabele i rejestruje swoje hooki:

• PREFIX_dffreeshipbar_country — progi na poziomie kraju, z kolumną id_shop.
• PREFIX_dffreeshipbar_state — progi na poziomie regionu, z kolumną id_shop.

Zarejestrowane hooki: displayHeader, displayBanner, displayNav2, displayNavFullWidth, displayShoppingCartFooter, displayCheckoutSummaryTop, actionCarrierUpdate.

Ustawienia ogólne

Ekran konfiguracji znajduje się w Moduły → DataFirefly – Pasek darmowej dostawy → Konfiguruj. Składa się z trzech paneli: ustawienia ogólne, reguły przewoźników i progi według terytorium.

Globalny próg zapasowy

Dwa powiązane ustawienia:

• Użyj globalnego progu domyślnego: w pozycji Nie pasek pojawia się wyłącznie w jawnie skonfigurowanych terytoriach. W pozycji Tak każde nieskonfigurowane terytorium otrzymuje kwotę podaną poniżej.
• Globalny próg domyślny: kwota stosowana w ostateczności.

Zostaw próg zapasowy wyłączony, jeśli darmowa dostawa obejmuje tylko kilka kierunków. Włącz go, jeśli obowiązuje powszechnie, a wyjątki są nieliczne.

Podstawa obliczeń

• Porównuj kwoty brutto: określa, czy suma koszyka jest liczona z podatkiem, czy bez. Musi odpowiadać podstawie stosowanej w przedziałach przewoźnika, w przeciwnym razie pasek i kasa będą się różnić.
• Uwzględnij reguły koszyka w sumie: gdy opcja jest aktywna, rabaty są odejmowane przed porównaniem z progiem. Koszyk o wartości 70 € z bonem 10 € jest wtedy liczony jako 60 €.

Obliczana suma odpowiada natywnemu wywołaniu:

Cart::getOrderTotal(
    $with_taxes = (bool) DFFREESHIPBAR_TAX_INCL,
    $type = DFFREESHIPBAR_INCLUDE_DISCOUNTS
        ? Cart::BOTH_WITHOUT_SHIPPING
        : Cart::ONLY_PRODUCTS
);

Koszty dostawy i pakowanie na prezent nigdy nie wliczają się do postępu.

Wymagaj adresu dostawy

Dopóki klient nie poda adresu, miejsce dostawy jest tylko szacunkiem, a region pozostaje nieznany. Trzy tryby:

• Nigdy: pasek pojawia się już podczas przeglądania katalogu, na podstawie szacowanego kraju.
• Dla krajów z regionami (zalecane): pasek pozostaje widoczny wszędzie poza krajami, których regiony mogą mieć odmienne warunki. Odwiedzający szacowany na Belgię widzi pasek; odwiedzający szacowany na Francję zobaczy go dopiero po podaniu adresu, ponieważ to jego region wyznacza rzeczywisty próg.
• Zawsze: nic, dopóki koszyk nie ma przypisanego adresu.

Pozycje i wygląd

• Pokaż na górze strony: baner widoczny w całym serwisie.
• Pokaż w koszyku i przy zamówieniu: blok wyświetlany w momencie decyzji.
• Włącz animację: animowane paski w trakcie postępu. Animacja jest automatycznie wyłączana dla odwiedzających z ustawieniem prefers-reduced-motion.
• Cztery kolory: tło, pasek, tekst i komunikat potwierdzenia.

Do dowolnego umieszczenia w motywie moduł implementuje WidgetInterface:

{widget name='dffreeshipbar'}
{widget name='dffreeshipbar' position='cart'}

Progi według terytorium

To serce modułu. Tabela wymienia wszystkie aktywne kraje sklepu, a pod każdym krajem posiadającym regiony — jego regiony z wcięciem.

Kolejność ustalania

Dla danego adresu dostawy moduł szuka w tej kolejności i zatrzymuje się na pierwszym trafieniu:

1. Region adresu, jeśli istnieje dla niego reguła.
2. Kraj adresu, jeśli istnieje dla niego reguła.
3. Globalny próg zapasowy, jeśli jest włączony.

Jeśli żaden z tych trzech kroków nie da kwoty, pasek nie zostanie wyświetlony.

Pole wyboru i pole kwoty: dwa różne skutki

To najważniejszy element konfiguracji i najczęściej mylnie rozumiany:

• Pole odznaczone → pasek jest ukryty dla tego terytorium. Nie dziedziczy ono ani z kraju nadrzędnego, ani z progu globalnego. Ustalanie kończy się w tym miejscu.
• Pole zaznaczone, kwota pusta → reguła zostaje usunięta, a terytorium dziedziczy z poziomu wyższego.
• Pole zaznaczone, kwota podana → obowiązuje ta kwota.

Przykład: tylko terytorium metropolitalne

Typowy przypadek francuskiego sklepu oferującego darmową dostawę od 65 € we Francji metropolitalnej i na Korsyce, ale nie na terytoriach zamorskich:

• Francja: pole zaznaczone, kwota 65.
• Korsyka: pole zaznaczone, kwota pusta — dziedziczy 65 € z Francji.
• Gwadelupa, Martynika, Gujana Francuska, Reunion, Majotta: pola odznaczone. Brak paska na tych kierunkach.
• Globalny próg zapasowy: wyłączony, aby żaden inny kraj nie otrzymał paska przypadkowo.

Klient z Gwadelupy nigdy nie zobaczy obietnicy darmowej dostawy, mimo że jego adres należy w PrestaShop do kraju „Francja”.

Filtr i wyszukiwanie

Pole wyszukiwania filtruje kraje i regiony według nazwy. Pole Pokaż tylko skonfigurowane terytoria ogranicza tabelę do wierszy z istniejącą regułą — przydatne w sklepie wysyłającym do stu krajów.

Oba przyciski zapisu działają niezależnie: Zapisz kraje i Zapisz regiony.

Reguły przewoźników

Jeśli darmową dostawę oferują tylko niektórzy przewoźnicy, ogranicz wyświetlanie odpowiednio. Trzy tryby:

• Wszyscy przewoźnicy: bez filtrowania.
• Pokaż tylko dla przewoźników zaznaczonych poniżej: biała lista.
• Ukryj dla przewoźników zaznaczonych poniżej: czarna lista.

Przed wyborem przewoźnika

Przewoźnik jest znany dopiero na etapie dostawy. Ustawienie Przed wyborem przewoźnika decyduje, co dzieje się wcześniej:

• Pokaż: pasek pojawia się w katalogu i koszyku, po czym znika, jeśli klient wybierze wykluczonego przewoźnika.
• Ukryj: pasek pojawia się dopiero po wybraniu kwalifikującego się przewoźnika.

Aktualizacja w czasie rzeczywistym

Pasek jest przeliczany po stronie serwera i odświeżany bez przeładowania strony przy każdym zdarzeniu koszyka: dodanie, usunięcie, zmiana ilości, zmiana adresu, zmiana kroku zamówienia.

Skrypt nasłuchuje zdarzeń PrestaShop updatedCart, updateCart, updatedAddressForm, changedCheckoutStep oraz updateDeliveryForm. Ręczne odświeżenie możesz wywołać z własnego kodu:

document.dispatchEvent(new Event('dffreeshipbar:refresh'));

O widoczności decyduje serwer: jeśli terytorium lub przewoźnik przestaje się kwalifikować, pasek jest usuwany z DOM zamiast pozostawać z nieaktualną wartością.

Wiele sklepów

Progi zapisywane są z kolumną id_shop. Każdy sklep ma zatem własne reguły krajów i regionów, niezależne od pozostałych.

Aby skonfigurować dany sklep, wybierz jego kontekst u góry panelu przed otwarciem ekranu konfiguracji. Panel progów wyświetla nazwę bieżącego sklepu jako przypomnienie.

Tłumaczenia

Moduł dostarczany jest z tłumaczeniami na polski, francuski, angielski, niemiecki, hiszpański i włoski.

Aby dostosować teksty widoczne dla klienta, przejdź do Międzynarodowe → Tłumaczenia, wybierz „Tłumaczenia modułów”, następnie dffreeshipbar i język, po czym odszukaj domenę Modules.Dffreeshipbar.Shop. Dostępne ciągi:

• „Brakuje tylko %amount% do darmowej dostawy!” — koszyk w trakcie.
• „Darmowa dostawa od %amount%.” — pusty koszyk.
• „Gratulacje! Twoje zamówienie objęte jest darmową dostawą.” — próg osiągnięty.

Znacznik %amount% zostaje zastąpiony kwotą sformatowaną zgodnie z aktywną walutą i lokalizacją. Zachowaj go w swoich tłumaczeniach.

Aktualizacja z wersji 1.0

Aktualizacja przebiega automatycznie po podmianie pliku ZIP. Skrypty aktualizacyjne wykonują następujące operacje:

• Utworzenie tabeli regionów.
• Zmiana nazwy kolumny active na enabled w tabeli krajów. Istniejące progi zostają zachowane.
• Globalny próg zapasowy zostaje włączony, jeśli miałeś go w wersji 1.0, aby nie zmieniać tego, co widzą klienci.
• Tryb wymogu adresu ustawiany jest na Nigdy, co odpowiada zachowaniu wersji 1.0. Przełącz go na tryb zalecany, gdy uznasz to za stosowne.

Rozwiązywanie problemów

Pasek nie pojawia się nigdzie

1. Czy moduł jest włączony? (przełącznik Włącz moduł).
2. Czy skonfigurowano co najmniej jedno terytorium lub włączono globalny próg zapasowy? Bez jednego z nich pasek nigdy się nie pojawi.
3. Czy tryb wymogu adresu jest ustawiony na Zawsze, podczas gdy testujesz bez adresu dostawy?
4. Czy pozycje są włączone? (baner i/lub koszyk).
5. Czy motyw wywołuje używane hooki? Sprawdź w Moduły → Pozycje. W motywie własnym lepiej użyć widgetu.

Pasek pojawia się tam, gdzie nie powinien

Typowy przypadek to terytorium, które dziedziczy, choć powinno być wykluczone. Sprawdź, czy jego pole wyboru jest faktycznie odznaczone, a nie jedynie czy wyczyszczono kwotę — te dwie czynności dają przeciwne skutki.

Wyświetlany próg nie zgadza się z kasą

• Sprawdź, czy Porównuj kwoty brutto odpowiada podstawie przedziałów przewoźnika.
• Sprawdź ustawienie reguł koszyka: koszyk z rabatem może spaść poniżej progu.
• Moduł nie odczytuje przedziałów przewoźnika. Jeśli zmieniłeś przedział, przenieś nową wartość do modułu.

Pasek nie aktualizuje się po dodaniu do koszyka

Odświeżanie opiera się na zdarzeniach JavaScript PrestaShop. Niektóre motywy lub zewnętrzne moduły koszyka ich nie emitują. Dwie kontrole:

• Czy konsola przeglądarki zgłasza błąd JavaScript w innym zasobie? Blokujący błąd wcześniej uniemożliwia zainstalowanie nasłuchu.
• Czy Twój moduł koszyka ajax rzeczywiście emituje prestashop.emit('updatedCart')? Jeśli nie, wywołaj dffreeshipbar:refresh ze swojego kodu.

Reguły przewoźników wydają się ignorowane

Sprawdź, czy wybrany przewoźnik to ten, o którym myślisz: po zmianie cennika PrestaShop tworzy nowego. Moduł podąża za referencją, więc reguła powinna zadziałać — ale jeśli przewoźnik został utworzony od zera, a nie edytowany, jego referencja jest nowa i trzeba go ponownie zaznaczyć.

Odinstalowanie

Przejdź do Moduły → Menedżer modułów → DataFirefly – Pasek darmowej dostawy → Odinstaluj. Odinstalowanie usuwa obie tabele progów oraz wszystkie klucze konfiguracji z przedrostkiem DFFREESHIPBAR_.

Szybkie FAQ

• Czy moduł odczytuje PS_SHIPPING_FREE_PRICE? Nigdy. Możesz zostawić ją na 0 i sterować darmową dostawą przez przedziały przewoźnika.
• Czy moduł odczytuje przedziały przewoźnika, aby wyliczyć próg? Nie. Progi wprowadza się ręcznie. Automatyczna synchronizacja z przedziałów jest możliwa jako rozwiązanie na zamówienie.
• Moja darmowa dostawa zależy też od wagi. Czy to jest obsługiwane? Nie, moduł mierzy wyłącznie kwotę. Warunek wagowy to rozwiązanie na zamówienie.
• Czy mogę wyświetlić pasek poza proponowanymi pozycjami? Tak, przez {widget name='dffreeshipbar'} w dowolnym szablonie.
• Czy moduł działa z motywem Hummingbird? Tak. Hooki displayNavFullWidth i displayCheckoutSummaryTop są dla niego zarejestrowane, a widget obsługuje własne rozmieszczenia.
• Czy progi są niezależne dla każdego sklepu? Tak, każdy wiersz zawiera id_shop.

Wsparcie i aktualizacje

Moduł obejmuje 12 miesięcy aktualizacji i wsparcia od daty zakupu. Wsparcie e-mailowe po francusku lub angielsku, odpowiedź w ciągu 24 godzin roboczych.

W razie pytań lub nieprawidłowości skontaktuj się ze wsparciem DataFirefly, podając:

• Wersję PrestaShop i PHP
• Zainstalowaną wersję modułu
• Używany motyw
• Terytorium i przewoźnika, których dotyczy obserwowane zachowanie
• Zachowanie obserwowane a oczekiwane