Smart Offers: kompletna dokumentacja

Smart Offers to moduł zgodny z PrestaShop 8 i 9, który pozwala tworzyć oferty łączone 1+1, pakiety hurtowe, pakiety wieloproduktowe i oferty z wyborem, z automatycznym dodawaniem oferowanych produktów do koszyka i dopracowaną prezentacją na karcie produktu.

Przegląd

Smart Offers obejmuje cztery najpopularniejsze w e-commerce formaty ofert łączonych w jednym module, bez skomplikowanej konfiguracji. Silnik ocenia koszyk przy każdej zmianie, automatycznie dodaje oferowane produkty, gdy tylko warunki są spełnione, i tworzy regułę koszyka, która czyni te sztuki darmowymi. Doświadczenie klienta jest natychmiastowe i czytelne.

Zgodność z PrestaShop 8 i 9

Od wersji 2.0.0 jeden plik ZIP pokrywa PrestaShop 8.0 do 9.x. Nie ma osobnej gałęzi do wyboru przy pobieraniu: moduł wykrywa wersję sklepu w trakcie wykonania i dostosowuje swoje wywołania do API, które zmieniły się między obiema generacjami.

Instalacja

1. Pobierz plik dfoffers-vX.Y.Z.zip ze swojego panelu klienta DataFirefly
2. W zapleczu PrestaShop przejdź do Moduły → Menedżer modułów
3. Kliknij przycisk Wgraj moduł u góry strony
4. Przeciągnij i upuść plik ZIP albo kliknij, aby go wybrać
5. Instalacja jest automatyczna: tabele są tworzone, hooki rejestrowane, a w menu pojawia się nowa zakładka Katalog → Oferty łączone

Cztery typy ofert

1+1 na tym samym produkcie

Wiralowy format buy-one-get-one: klient kupuje jedną sztukę produktu i otrzymuje gratis drugą sztukę tego samego produktu. Konfigurujesz:

• Jeden produkt (który jest jednocześnie wyzwalaczem i nagrodą)
• Ilość do kupienia, aby wyzwolić ofertę (zwykle 1)
• Ilość oferowaną (zwykle 1)

Typowy przykład: „Za 1 kupioną parę skarpetek druga gratis.” Gdy klient dodaje parę do koszyka, silnik automatycznie dodaje drugą i stosuje rabat równy cenie jednostkowej.

Kup X, otrzymaj Y gratis (różne produkty)

Format bundle: kilka odrębnych produktów wyzwalających musi być obecnych w koszyku, aby oferta się aktywowała, a jeden lub kilka innych produktów jest wtedy oferowanych. Konfigurujesz:

• Listę produktów wyzwalających z ich ilościami
• Listę produktów oferowanych z ich ilościami

Typowy przykład: „Za wspólny zakup kremu na dzień i serum otrzymaj gratis próbkę maski.” Silnik sprawdza, czy wszystkie wyzwalacze są obecne, zanim aktywuje ofertę.

Wybór spośród wariantów

Format swobodnej kompozycji: definiujesz zestaw produktów lub wariantów kandydujących, z których klient komponuje swój zestaw. Silnik automatycznie identyfikuje najtańsze sztuki w koszyku jako sztuki oferowane, co odpowiada standardowej interpretacji handlowej buy-N-get-M.

• Lista produktów lub wariantów kandydujących
• Liczba sztuk do kupienia z tego zbioru
• Liczba sztuk oferowanych (najtańszych)

Typowy przykład: „3 kupione t-shirty z naszej selekcji, najtańszy gratis.” Klient komponuje swój zestaw, silnik nie dotyka jego koszyka, ale stosuje rabat na najtańsze sztuki.

Pakiet hurtowy

Format B2B i upłynniania zapasów: za każdy zestaw X kupionych sztuk jednego produktu klient otrzymuje Y sztuk gratis innego produktu. Konfigurujesz:

• Produkt wyzwalający z ilością progową (na przykład 10)
• Produkt oferowany z ilością oferowaną (na przykład 20)

Typowy przykład: „Za 10 kupionych butelek wina 2 kieliszki gratis.” Praktyczne dla dostawców, którzy chcą promować produkt komplementarny lub upłynnić zalegający zapas, wiążąc go z produktem, który dobrze się sprzedaje.

Tworzenie pierwszej oferty

W zapleczu przejdź do Katalog → Oferty łączone, a następnie kliknij Nowa oferta.

Krok 1: wybór typu

Cztery wizualne karty prezentują dostępne typy z krótkim opisem. Kliknij tę, która odpowiada Twojej operacji handlowej. Formularz dostosowuje się automatycznie i pokazuje tylko pola istotne dla tego typu.

Krok 2: nazwa i odznaka oferty

Wypełnij:

• Nazwa oferty (wymagana): to, co klient zobaczy w banerze. Dostępna w pięciu językach.
• Tekst odznaki (opcjonalny, maks. 64 znaki): krótki komunikat wyświetlany w plakietce u góry baneru (na przykład 1+1 GRATIS, OFERTA SPECJALNA, BLACK FRIDAY).
• Kolor odznaki: sześć presetów DataFirefly plus dowolny selektor koloru. Kolor służy zarówno banerowi na karcie produktu, JAK I plakietce prezentu w koszyku.

Krok 3: dodanie produktów wyzwalających

Kliknij Dodaj produkt wyzwalający. Otwiera się okno wyszukiwania z polem odpytującym Twój katalog na żywo (wyszukiwanie z opóźnieniem 250 ms po ostatnim naciśnięciu klawisza). Wpisz nazwę, referencję lub EAN; wyniki pojawiają się natychmiast.

Kliknij produkt, aby go dodać. Jeśli produkt ma warianty, pojawiają się one jako przyciski pod wynikiem, kliknij ten, który Cię interesuje, aby dodać go bezpośrednio. Wpisz wymaganą ilość w polu pojawiającym się po prawej stronie linii.

Krok 4: dodanie produktów oferowanych

Ta sama procedura dla produktów oferowanych. Ta sekcja jest ukryta dla typu Wybór spośród wariantów, ponieważ warianty służą jednocześnie jako kandydaci i nagrody.

Krok 5: reguły szczegółowe

• Kumulacja: jeśli włączona, oferta stosuje się wielokrotnie za każdy wyzwalający zestaw. Bez kumulacji oferta stosuje się tylko raz, niezależnie od liczby sztuk. Domyślnie wyłączona, aby chronić Twoje marże.
• Dla typu Wybór spośród wariantów pojawiają się dwa dodatkowe pola: ile sztuk klient musi kupić i ile jest oferowanych.

Krok 6: aktywacja

• Daty ważności: pozostaw puste dla oferty stałej. Wypełnij datę początku lub końca, aby zautomatyzować aktywację. Od wersji 2.0.0 nieczytelna data jest odrzucana zamiast zapisywana jako 1 stycznia 1970, a data końca musi być późniejsza niż data początku.
• Priorytet: jeśli kilka ofert może stosować się jednocześnie, ta z najniższym priorytetem jest oceniana jako pierwsza.
• Status: przełącznik on/off, domyślnie włączony. Praktyczny do tymczasowego wyłączenia oferty bez jej usuwania.

Krok 7: sklepy (jeśli multisklep)

Zaznacz sklepy, w których oferta ma być dostępna. Niezaznaczenie niczego oznacza aktywację oferty we wszystkich sklepach.

Jak działa silnik automatycznego dodawania

Silnik podpina się do hooka PrestaShop actionCartSave i wykonuje się przy każdej zmianie koszyka (dodanie, usunięcie, zmiana ilości, scalenie przy logowaniu).

1. Pobiera wszystkie aktywne oferty dla bieżącego sklepu
2. Dla każdej oferty oblicza ilość opłaconą każdego produktu wyzwalającego (łączna ilość w koszyku minus to, co silnik już auto-dodał przy poprzedniej ocenie)
3. Ocenia, czy warunki oferty są spełnione
4. Jeśli tak, dodaje brakujące oferowane produkty do koszyka przez Cart::updateQty
5. Tworzy lub aktualizuje regułę koszyka (CartRule) ze stałym rabatem brutto równym wartości oferowanych sztuk
6. Zapisuje w tabeli ps_dfoffers_cart_auto sztuki, które dodał, aby móc je odróżnić od sztuk dodanych przez samego klienta

Czyste wycofanie

Jeśli klient usunie produkt wyzwalający lub zmniejszy jego ilość poniżej progu, silnik ponownie ocenia ofertę przy następnym actionCartSave. Jeśli warunek nie jest już spełniony, usuwa sztuki, które auto-dodał (nie dotykając sztuk dodanych przez samego klienta, dzięki śledzeniu), i kasuje powiązaną regułę koszyka.

Wyświetlanie na karcie produktu

Na każdej wyzwalającej karcie produktu wyświetla się baner z gradientem przez hook displayProductAdditionalInfo. Zawiera:

• Białą plakietkę z ikoną prezentu, zawierającą tekst odznaki
• Tytuł oferty
• Dynamiczny komunikat zależny od typu oferty („Dodaj 1 produkt, otrzymaj 1 gratis”, „Za 10 kupionych sztuk 20 sztuk gratis” itd.)
• Siatkę z klikalnymi miniaturami produktów objętych ofertą, rozdzielonych na dwie grupy Kup / Otrzymaj gratis z okrągłym separatorem SVG pomiędzy nimi

Kolor baneru przejmuje kolor odznaki skonfigurowanej w ofercie. Rendering jest responsywny: na mobile obie grupy układają się pionowo, a separator obraca się, wskazując w dół.

Wyświetlanie w koszyku

Od wersji 1.1.0 dwa odrębne wskaźniki pomagają klientowi zidentyfikować oferowane produkty w koszyku.

Plakietka prezentu na każdej linii

Na każdej linii koszyka zawierającej sztuki auto-dodane przez ofertę pojawia się mała kolorowa plakietka 🎁 ×N gratis obok akcji linii. Kolor przejmuje kolor odznaki oferty, a plakietka wskazuje, ile sztuk tej linii jest darmowych (przydatne, gdy część ilości jest opłacona, a część oferowana, na przykład przy 1+1 na tym samym produkcie).

Szczegółowa stopka koszyka

Na dole siatki produktów zielony blok podsumowuje oferty aktywowane w koszyku. Dla każdej oferty blok wyświetla:

• Nazwę oferty i jej tekst odznaki (w kolorowej plakietce)
• Listę produktów oferowanych przez tę ofertę, w formie wizualnych chipów z okrągłą miniaturą, nazwą i ilością
• Każdy chip jest klikalny i prowadzi do karty produktu prezentu

Klient może w ten sposób jednym spojrzeniem sprawdzić, co otrzymał za darmo i dzięki której operacji handlowej.

Przypadki szczególne i zachowania

Dlaczego 1+1 na tym samym produkcie jest traktowane specjalnie

Gdy produkt wyzwalający jest także produktem nagrodą, wiele modułów ofert łączonych na rynku popełnia błąd, identyfikując opłaconą sztukę klienta jako już oferowaną, i stosuje rabat na tę sztukę. W efekcie klient płaci zero za jedną sztukę zamiast zapłacić za jedną i otrzymać drugą gratis.

Smart Offers obsługuje ten przypadek precyzyjną logiką: docelowa ilość w koszyku wynosi ilość opłacona przez klienta + ilość nagrody. Gdy klient dodaje jedną sztukę, silnik dodaje drugą, aby koszyk zawierał dwie sztuki, a rabat stosuje się wyłącznie na drugą sztukę. Klient płaci więc cenę jednej sztuki, mając dwie w koszyku.

Kumulacja zestawów (opcja stackable)

Bez kumulacji oferta stosuje się tylko raz, niezależnie od liczby wyzwalających zestawów obecnych w koszyku. Jeśli klient kupi 5 sztuk produktu z ofertą 1+1 i wyłączoną kumulacją, otrzyma 1 sztukę gratis (nie 5).

Z włączoną kumulacją silnik mnoży liczbę zestawów nagród przez całkowitą liczbę wyzwalających zestawów. Dla tej samej oferty 1+1 z włączoną kumulacją i 5 sztukami w koszyku klient otrzyma 5 sztuk gratis (finalny koszyk: 10 sztuk, 5 opłaconych).

Stan magazynowy i niedostępność

Dodawanie oferowanych produktów do koszyka przechodzi przez Cart::updateQty, które respektuje natywne reguły magazynowe PrestaShop. Jeśli oferowany produkt jest wyczerpany, a sklep nie zezwala na zamówienia bez stanu, dodanie cicho zawodzi i rabat nie jest stosowany. Warunek pozostaje gotowy do wyzwolenia po uzupełnieniu zapasów.

Kilka jednoczesnych ofert w jednym koszyku

Każda oferta generuje własną regułę koszyka z włączonym partial_use. Pozwala to nakładać kilka równoczesnych ofert na jeden koszyk bez konfliktu i pozostaje zgodne z klasycznymi kodami rabatowymi, które klienci mogą wpisywać.

Architektura techniczna

Używane hooki

• displayProductAdditionalInfo: baner na karcie produktu
• displayShoppingCartFooter: szczegółowa stopka na stronie koszyka
• displayCartExtraProductActions: plakietka prezentu na każdej linii koszyka
• actionCartSave: silnik oceny i automatycznego dodawania
• actionFrontControllerSetMedia i actionAdminControllerSetMedia: wstrzykiwanie CSS i JS
• actionObjectProductDeleteAfter: automatyczne czyszczenie ofert odwołujących się do usuniętego produktu

Od wersji 2.0.0 tylko actionCartSave i actionFrontControllerSetMedia są uznawane za niezbędne przy instalacji. Hooki wyświetlania, których motyw nie implementuje, są logowane bez powodowania niepowodzenia instalacji.

Dodane tabele

• ps_dfoffers_offer: konfiguracja każdej oferty (typ, daty, priorytet, kumulacja)
• ps_dfoffers_offer_lang: nazwa, odznaka i opis tłumaczone per język
• ps_dfoffers_trigger: produkty wyzwalające każdej oferty
• ps_dfoffers_reward: produkty nagrody każdej oferty
• ps_dfoffers_shop: powiązanie oferta / sklep w multisklepie
• ps_dfoffers_cart_auto: śledzenie auto-dodanych sztuk per koszyk i per oferta, z identyfikatorem wygenerowanej reguły koszyka

Wszystkie tabele mają prefiks skonfigurowany w Twojej instalacji PrestaShop (domyślnie ps_). Schemat jest identyczny w PrestaShop 8 i 9, co czyni migrację przezroczystą.

Klasa DfOfferCompat

Wszystkie różnice API między PrestaShop 8 i 9 są skoncentrowane w classes/DfOfferCompat.php. Reszta modułu nigdy nie testuje wersji PrestaShop bezpośrednio. Punkty absorbowane przez tę klasę:

• Odczyt wariantów: PrestaShop 9 usunął argument języka z Product::getAttributeCombinations(), gdzie pierwszy parametr jest teraz logiczną flagą grupowania.
• URL AJAX zaplecza: w PrestaShop 9 para ajax i action musi przechodzić przez czwarty argument getAdminLink(), ponieważ token jest obliczany przed scaleniem parametrów.
• Odpowiedź JSON: metoda wysyłki celowo nosi inną nazwę niż ajaxRender(), której nadrzędna sygnatura nie może być nadpisywana.
• Zakładka admin: PrestaShop 9 wprowadził dodatkowe kolumny tłumaczeń, wypełniane pod ochroną, aby nie tworzyć dynamicznej właściwości w PrestaShop 8.

Nadpisywanie szablonów w motywie

CSS modułu jest izolowany prefiksem .dfoffers-, aby uniknąć konfliktów z Twoim arkuszem stylów. Jeśli chcesz zmodyfikować rendering, skopiuj szablony z /modules/dfoffers/views/templates/hook/ do /themes/twoj-motyw/modules/dfoffers/views/templates/hook/ i dostosuj je. Dostępne są trzy szablony:

• product-banner.tpl: baner na karcie produktu
• cart-offer.tpl: blok podsumowania w stopce koszyka
• cart-line-gift.tpl: plakietka prezentu inline na liniach koszyka

Aktualizacja modułu

Aby zaktualizować do nowej wersji, po prostu wgraj nowy ZIP z Menedżera modułów. PrestaShop wykrywa zmianę wersji w config.xml i automatycznie wykonuje skrypty upgrade obecne w /upgrade/upgrade-X.Y.Z.php, które zajmują się na przykład rejestracją nowych hooków dodanych między wersjami.

Migracja sklepu z PrestaShop 8 na PrestaShop 9

Ponieważ schemat bazy danych jest identyczny, Twoje oferty, tłumaczenia i powiązania sklepów przechodzą migrację bez transformacji. Zalecana procedura:

1. Zaktualizuj moduł do 2.0.0 przed migracją sklepu, gdy jeszcze działa na PrestaShop 8. Wersja 2.0.0 działa na obu generacjach, zmniejszasz więc liczbę zmiennych, gdyby coś poszło nie tak.
2. Zmigruj sklep na PrestaShop 9 zgodnie z oficjalną procedurą PrestaShop.
3. Przejdź do Wygląd → Pozycje i sprawdź, czy sześć hooków modułu jest nadal podpiętych. Migracja może niektóre utracić.
4. Jeśli brakuje hooków, wgraj ponownie ZIP 2.0.0: skrypt upgrade-2.0.0.php ponownie rejestruje każdy brakujący hook i czyści wiersze śledzenia, których koszyk zniknął.

Rozwiązywanie problemów

Oferowane produkty nie dodają się do koszyka

1. Wyczyść cache PrestaShop w Zaawansowane parametry → Wydajność
2. Sprawdź, czy hook actionCartSave zawiera moduł w Wygląd → Pozycje
3. Sprawdź, czy oferowany produkt jest dostępny (nie wyczerpany, jeśli zamówienia bez stanu są zabronione, nie wyłączony, przypisany do bieżącego sklepu)
4. Sprawdź Zaawansowane parametry → Logi, szukając dfoffers: silnik loguje swoje wykonanie przy każdym dodaniu do koszyka

Rabat nie stosuje się mimo dodania produktu

Sprawdź w logach linię checkValidity następującą po utworzeniu reguły koszyka. PrestaShop wskazuje tam dokładnie, dlaczego reguła jest odrzucana (brak stanu, ograniczenie klienta, inna waluta itd.).

Plakietka prezentu nie pojawia się na liniach koszyka

Sprawdź, czy Twój motyw implementuje hook displayCartExtraProductActions w cart-detailed-product-line.tpl. Motywy Classic PrestaShop 8 i 9 oraz większość motywów komercyjnych go zawierają. Jeśli używasz motywu niestandardowego, który go nie implementuje, dodaj następującą linię w pliku cart-detailed-product-line.tpl w wybranym miejscu:

{hook h='displayCartExtraProductActions' product=$product}

Wyszukiwarka produktów w zapleczu nic nie zwraca po migracji na PrestaShop 9

Wyczyść cache PrestaShop, a następnie przeładuj stronę tworzenia oferty. URL endpointu wyszukiwania jest budowany po stronie serwera przy renderowaniu formularza; strona zbuforowana przed migracją może wciąż zawierać stary URL. Jeśli problem się utrzymuje, otwórz konsolę przeglądarki: odpowiedź 404 na żądaniu wyszukiwania wskazuje, że zakładka modułu nie została poprawnie odtworzona, a ponowna instalacja modułu naprawia to bez utraty ofert.

Instalacja wygląda na udaną, ale nie da się utworzyć żadnej oferty

Przed wersją 2.0.0 niepowodzenie utworzenia tabeli podczas instalacji było ciche, a moduł wyświetlał się jako zainstalowany. Od wersji 2.0.0 taka sytuacja powoduje niepowodzenie instalacji z czytelnym komunikatem. Jeśli spotkasz ten przypadek na starszej wersji, sprawdź uprawnienia użytkownika MySQL do tworzenia tabel, a następnie odinstaluj i zainstaluj ponownie moduł w wersji 2.0.0.

Najczęstsze pytania

Czy moduł jest zgodny z PrestaShop 9?

Tak, od wersji 2.0.0. Ten sam plik ZIP instaluje się na PrestaShop 8.0 i na PrestaShop 9.x. Różnice API absorbuje wewnętrzna klasa DfOfferCompat, nie ma więc osobnej gałęzi do wyboru przy pobieraniu. Wersje 1.x były ograniczone do PrestaShop 8.0 do 8.99.

Jaki jest wpływ na wydajność?

Silnik wykonuje jedno zapytanie SQL per aktywna oferta w sklepie, a następnie ocenia warunki w pamięci. Przy katalogu z dziesięcioma aktywnymi ofertami pełna ocena zajmuje średnio mniej niż pięćdziesiąt milisekund. Ta wartość jest identyczna w PrestaShop 8 i 9.

Czy mogę używać modułu z motywem headless?

Silnik automatycznego dodawania jest niezależny od motywu i działa dla każdego frontu przechodzącego przez Cart::updateQty lub API REST PrestaShop. Baner karty produktu i plakietka prezentu w koszyku to natywne hooki Smarty, które do wyświetlenia wymagają klasycznego motywu. Dla frontu headless możesz udostępnić dane przez własne API odpytujące bezpośrednio ps_dfoffers_offer i ps_dfoffers_cart_auto.

Czy moduł obsługuje wiele walut?

Tak. Reguła koszyka generowana dla każdej oferty używa waluty bieżącego koszyka. Jeśli klient zmieni walutę, reguła jest regenerowana z poprawną wartością przy następnym actionCartSave.

Co się stanie, jeśli kliknę Resetuj w menedżerze modułów?

Moduł jest odinstalowywany i ponownie instalowany w tym samym żądaniu, co usuwa i odtwarza tabele: wszystkie Twoje oferty są tracone. Od wersji 2.0.0 ta operacja poprawnie odtwarza tabele, podczas gdy wcześniejsze wersje zostawiały sklep całkowicie bez tabel. W obu przypadkach zrób kopię zapasową przed resetowaniem.