DF Samples: zamawianie próbek produktów (PrestaShop 8 i 9)

Wprowadzenie

DF Samples dodaje na kartach produktów przycisk zamawiania próbki. Próbka może być bezpłatna lub kosztować kilka euro, dla produktu albo dla kombinacji wybranej przez klienta. Moduł tworzy ukryty produkt-próbkę dla każdego zapisanego produktu, blokuje ilość na 1, egzekwuje limity na klienta na zawartości koszyka, mierzy konwersję z próbki na zakup i wysyła e-mail przypominający z opcjonalnym kodem rabatowym.

Moduł działa z PrestaShop 8.0 do 9.x, w trybie multistore i wielojęzycznym, bez override rdzenia. Ta dokumentacja dotyczy wersji 1.1.0.

Instalacja

1. W panelu administracyjnym przejdź do Moduły > Menedżer modułów.
2. Kliknij Załaduj moduł i upuść plik dfsamples.zip.
3. Otwórz Katalog > Samples (DF): na tej stronie znajdują się lista produktów, panel statystyk i ustawienia.

Podczas instalacji moduł tworzy:

• trzy tabele: dfsamples_product, dfsamples_order i dfsamples_cart;
• wyłączoną kategorię Samples pod kategorią główną, dostępną dla wszystkich grup klientów, do której trafiają produkty-próbki;
• ustawienia domyślne i token bezpieczeństwa dla zadania cron;
• zakładkę Katalog > Samples (DF);
• kopię angielskiego szablonu e-maila dla każdego zainstalowanego języka, który go nie ma.

Moduł rejestruje się na 12 hookach, m.in. displayProductActions, displayProductAdditionalInfo, displayDfSamplesButton, actionCartSave, actionCartUpdateQuantityBefore, actionValidateOrder i actionOrderStatusPostUpdate.

Aktualizacja z wersji 1.0.0

Załaduj nowy plik ZIP na poprzednią wersję w menedżerze modułów. Skrypt aktualizacji:

• dodaje tabelę dfsamples_cart i nowe kolumny;
• rejestruje nowe hooki;
• tworzy kategorię próbek i przenosi do niej istniejące produkty-próbki;
• zmienia ich nazwy na nowy format i dodaje brakujące zdjęcia (w PrestaShop 9 wersja 1.0.0 nie kopiowała zdjęcia);
• zachowuje zapisane produkty, statystyki i historię przypomnień.

Jeśli któryś krok się nie powiedzie, przycisk Resync sample products u góry strony modułu ponownie synchronizuje wszystkie produkty-próbki.

Dodawanie produktu do programu próbek

1. Otwórz Katalog > Samples (DF) i kliknij Add a product.
2. Wyszukaj produkt po nazwie lub referencji i wybierz go. Produkty już zapisane i produkty-próbki są wykluczone z wyników.
3. Wpisz Sample price (tax incl.), czyli cenę brutto próbki. Wpisz 0,00 dla próbki bezpłatnej.
4. Ustaw Max per customer, maksimum dla tego produktu na klienta w oknie kroczącym (0 = bez limitu).
5. Włącz Sample per option, jeśli produkt ma kombinacje i klient ma wybrać swoją (patrz niżej).
6. Zapisz.

Co moduł robi przy zapisie

Moduł tworzy ukryty produkt-próbkę lub aktualizuje istniejący:

• nazwa w formacie „Sample: Nazwa produktu” (Échantillon, Muestra, Muster, Campione w językach przetłumaczonych);
• referencja w formacie SMPL i identyfikator produktu źródłowego;
• cena netto obliczona z wpisanej ceny i reguły podatkowej produktu źródłowego;
• zdjęcie okładki produktu źródłowego skopiowane do wszystkich formatów obrazów;
• kategoria domyślna: kategoria próbek;
• widoczność „nigdzie”: produkt nie pojawia się na listach ani w wyszukiwarce;
• zamawianie dozwolone przy braku stanu, aby nigdy nie blokować prośby;
• waga z ustawienia globalnego, używana przez przewoźników.

Jeśli później zmienisz cenę, opcję kombinacji, wagę globalną lub status aktywności, produkt-próbka zostanie zsynchronizowany. Jeśli został ręcznie usunięty z katalogu, zostanie odtworzony przy następnym zapisie.

Próbka dla kombinacji

Po włączeniu Sample per option klient wybiera kombinację na karcie produktu jak przy zwykłym zakupie, a następnie klika przycisk zamawiania próbki tej kombinacji.

• Kombinacja jest zapisywana w pozycji próbki, na przykład „Format: A4, Papier: kredowy 300 g”. Pojawia się w polu personalizacji w koszyku, zamówieniu, na fakturze i w e-mailu przypominającym.
• Każda kombinacja to osobna pozycja. Tej samej kombinacji nie można dodać dwa razy.
• Maksimum na klienta dla produktu jest liczone na kombinację.
• Cena próbki jest taka sama dla wszystkich kombinacji produktu.

Ustawienia

Ustawienia znajdują się pod listą produktów na stronie Katalog > Samples (DF).

General settings (ustawienia ogólne)

• Button position: pod przyciskiem dodania do koszyka (displayProductActions), w bloku informacji dodatkowych (displayProductAdditionalInfo) lub tylko we własnym miejscu (displayDfSamplesButton, patrz następna sekcja).
• Default sample price (tax incl.): wartość proponowana przy dodawaniu próbki.
• Sample weight: w kilogramach, dla wszystkich produktów-próbek, używana do kosztów wysyłki.
• Require customer account: domyślnie włączone. Limity na klienta można skutecznie egzekwować tylko wobec zidentyfikowanych klientów.
• Customer group discounts on samples: stosować (domyślne zachowanie PrestaShop) lub nie. Patrz „Ceny i rabaty grupowe”.
• Samples category: kategoria domyślna wszystkich produktów-próbek. Pozostaw ją wyłączoną. Jeśli wybierzesz inną, istniejące próbki zostaną do niej przeniesione.
• Redirect sample pages: domyślnie włączone. Odwiedzający stronę produktu-próbki jest przekierowywany kodem 301 do produktu źródłowego.
• Conversion counted on: tylko zakup produktu z próbki albo dowolny późniejszy zakup.

Limits (limity)

• Max samples per cart: 0 = bez limitu.
• Max samples per customer per window: wszystkie produkty-próbki razem, 0 = bez limitu.
• Rolling window: okno kroczące w dniach, domyślnie 30. Przy 0 limity na klienta obejmują wszystkie wcześniejsze zamówienia, bez ograniczenia czasu.

Automatic follow-up (automatyczne przypomnienie)

• Enable follow-up emails: włącza e-maile przypominające.
• Delay after sample order: w dniach, domyślnie 14.
• Only customers subscribed to the newsletter: włącz, jeśli podstawą prawną e-maili handlowych jest zgoda.
• Include a discount voucher: dla każdego przypomnienia generowany jest imienny kod jednorazowy.
• Voucher amount: w procentach, domyślnie 10.
• Voucher validity: w dniach, domyślnie 30.

Adres URL zadania cron jest widoczny w tej sekcji i w panelu statystyk.

Przycisk w Creative Elements lub we własnym motywie

Gdy karta produktu jest zbudowana w page builderze, natywne hooki nie zawsze są wyświetlane albo nie tam, gdzie trzeba. Moduł udostępnia własny hook displayDfSamplesButton.

1. W ustawieniu Button position wybierz Custom placement only (displayDfSamplesButton). Przycisk przestaje być dodawany do natywnych hooków, więc nie pojawi się dwa razy.
2. W Creative Elements: w szablonie karty produktu dodaj widget Module w wybranym miejscu, wybierz moduł DF Samples i hook displayDfSamplesButton.
3. We własnym motywie: dodaj {hook h='displayDfSamplesButton'} do szablonu karty produktu, na przykład templates/catalog/product.tpl.

Niezależnie od miejsca przycisk podąża za wybraną kombinacją i aktualizuje się, gdy klient ją zmieni.

Ceny i rabaty grupowe

Cena próbki jest niezależna od produktu źródłowego: ceny progowe, ceny specyficzne i minimalna ilość produktu źródłowego nie mają zastosowania. Do próbek zastosowałaby się jedynie reguła cenowa katalogu obejmująca wszystkie produkty bez wyjątku.

Rabat grupy klientów (Klienci > Grupy, na przykład -15 % dla sprzedawców) domyślnie obejmuje wszystkie produkty, także próbki. Po wybraniu Do not apply: samples keep their price moduł wyłącza produkty-próbki z rabatu każdej grupy: sprzedawcy płacą ustaloną cenę próbki, a rabat nadal obowiązuje na resztę katalogu. Grupy utworzone później są uwzględniane automatycznie.

Przycisk pokazuje cenę, którą zapłaci zalogowany klient, z rabatem grupowym i VAT.

Limity i kontrola koszyka

Reguły są sprawdzane przy każdym zapisie koszyka, a nie tylko po kliknięciu przycisku. Dodanie przyciskami + i – na stronie koszyka, przez bezpośredni adres URL, przez „Zamów ponownie” lub przez scalenie koszyków przy logowaniu przechodzi przez te same kontrole:

1. pozycje wyłączonych próbek są usuwane;
2. duplikaty są usuwane (ta sama próbka lub ta sama kombinacja w trybie kombinacji);
3. ilość każdej pozycji wraca do 1;
4. stosowane jest maksimum na koszyk;
5. stosowane są maksimum na produkt i globalne maksimum na klienta w oknie kroczącym.

Gdy pozycja musi zostać usunięta, usuwana jest najnowsza. Klient widzi komunikat na stronie koszyka lub zamówienia. Zamówienia anulowane, zwrócone lub z błędem płatności nie liczą się do limitów. Koszyki tworzone przez pracownika w panelu administracyjnym nie podlegają limitom.

Konfiguracja zadania cron

Przypomnienia są wysyłane przez zadanie cron. Zaplanuj co godzinę adres URL widoczny w ustawieniach. Przykład crontab:

0 * * * * wget -q -O /dev/null "https://twoj-sklep.pl/module/dfsamples/cron?token=TWOJ_TOKEN"

Każde uruchomienie przetwarza do 50 zamówień i zwraca podsumowanie JSON: processed, sent, skipped, waiting i retry.

Reguły zadania cron

• Jeden e-mail na zamówienie, nawet jeśli zawiera kilka próbek. Wymienia testowane produkty i zawiera najwyżej jeden kod.
• Brane są pod uwagę tylko próbki nieskonwertowane i bez przypomnienia, po upływie ustawionego czasu.
• Zamówienie próbki musi mieć status opłacone, wysłane lub dostarczone. Zamówienie wciąż oczekujące na płatność jest sprawdzane później i pomijane, jeśli nadal nie jest opłacone 60 dni po terminie przypomnienia.
• Zamówienia anulowane, zwrócone lub z błędem płatności są ignorowane.
• Próbka, której produkt kupiono w tym samym zamówieniu, nie dostaje przypomnienia.
• Przy włączonej opcji newslettera klienci niezapisani nie dostają przypomnienia.
• W razie błędu wysyłki moduł ponawia próbę w kolejnych uruchomieniach, najwyżej trzy razy i co najmniej co sześć godzin. Kod wygenerowany dla e-maila, który nie wyszedł, jest usuwany.
• Dwa równoczesne uruchomienia nie mogą wysłać tego samego e-maila: każde zamówienie jest rezerwowane przed przetworzeniem.

Śledzenie konwersji

Przy zatwierdzeniu zamówienia z próbką moduł zapisuje klienta, jego e-mail, produkt źródłowy, kombinację, język i sklep.

Gdy ten klient złoży kolejne zamówienie, odpowiednie próbki są oznaczane jako skonwertowane:

• w trybie produkt (domyślnym): jeśli zamówienie zawiera produkt, którego próbkę otrzymał;
• w trybie dowolny zakup: gdy tylko zamówienie zawiera prawdziwy produkt.

Konwersja jest liczona dopiero wtedy, gdy zamówienie zakupowe osiągnie status zatwierdzony (na przykład płatność zaakceptowana). Zamówienie opłacone przelewem liczy się więc po otrzymaniu płatności. Zakup w tym samym zamówieniu co próbka nie jest konwersją.

Panel statystyk

Panel nad listą produktów pokazuje:

• Samples ordered: liczba zapisanych pozycji próbek;
• Conversions: liczba próbek, po których nastąpił zakup, i wskaźnik konwersji;
• Revenue from conversions: suma brutto zamówień konwersji, przeliczona na walutę domyślną;
• Pending follow-ups: oczekujące przypomnienia.

Lista produktów pokazuje też dla każdego produktu liczbę zamówionych próbek, liczbę konwersji i to, czy tryb kombinacji jest włączony.

E-maile przypominające

Szablony znajdują się w katalogu mails modułu, po francusku, angielsku, hiszpańsku, niemiecku i włosku, w wersji HTML i tekstowej (dfsamples_followup). Dla polskiego szablon angielski jest kopiowany przy instalacji do mails/pl/: przetłumacz oba pliki w tym katalogu, zachowując zmienne w nawiasach klamrowych.

Dostępne zmienne:

• {firstname} i {lastname};
• {product_name}: testowany produkt lub produkty, oddzielone przecinkami;
• {product_link}: link do karty pierwszego produktu;
• {voucher_block}: sformatowany kod rabatowy dla wersji HTML, pusty, gdy kod jest wyłączony;
• {voucher_text}: ta sama treść dla wersji tekstowej;
• {shop_name}.

Kody rabatowe

Przy włączonej opcji każde przypomnienie tworzy regułę koszyka PrestaShop:

• kod w formacie SMPL i osiem losowych znaków;
• zastrzeżony dla odbiorcy, jednorazowy;
• rabat procentowy, konfigurowalna ważność.

Kody są widoczne w Katalog > Rabaty > Reguły koszyka.

Katalog, mapa witryny i feedy produktowe

Produkty-próbki mają widoczność „nigdzie” i znajdują się w wyłączonej kategorii próbek. Nie pojawiają się na listach, w wyszukiwarce ani w blokach promocyjnych, a ich strona przekierowuje do produktu źródłowego. Większość modułów mapy witryny i feedów pomija te produkty. Jeśli Twój je uwzględnia, wyklucz w jego ustawieniach kategorię próbek lub referencje zaczynające się od SMPL.

Zgodność z procesem zamówienia

Moduł nie ingeruje w proces zamówienia: próbka to zwykła pozycja produktu. Działa z natywnym checkoutem i z checkoutami na jednej stronie, które korzystają z natywnych kroków PrestaShop. Komunikat o usunięciu próbki wyświetla się na stronach koszyka i zamówienia.

Odinstalowanie

Odinstalowanie usuwa tabele, ustawienia i zakładkę modułu. Produkty-próbki są wyłączane, a nie usuwane, a kategoria próbek zostaje zachowana, aby historia zamówień pozostała spójna. Ponowna instalacja korzysta z tej samej kategorii. Możesz ręcznie usunąć te produkty i kategorię, jeśli nie są już potrzebne.

Rozwiązywanie problemów

Przycisk nie pojawia się na karcie produktu

Sprawdź, czy produkt jest zapisany i aktywny w Katalog > Samples (DF). Następnie zmień pozycję przycisku: niektóre motywy nie wyświetlają displayProductActions. W page builderze użyj hooka displayDfSamplesButton.

Zamiast przycisku pojawia się komunikat

Komunikat o osiągniętym limicie próbek dla produktu oznacza, że klient wykorzystał swoje maksimum w oknie kroczącym. Komunikat o maksymalnej liczbie próbek w koszyku oznacza, że osiągnięto maksimum na koszyk. W razie potrzeby dostosuj limity.

Produkty-próbki nie mają zdjęcia

Dotyczyło to próbek utworzonych przez wersję 1.0.0 w PrestaShop 9. Kliknij Resync sample products: brakujące zdjęcia zostaną dodane.

Wyświetlana cena nie jest oczekiwana

Cenę wpisuje się brutto i przelicza według reguły podatkowej produktu źródłowego. Dla klienta z grupy z rabatem sprawdź ustawienie „Customer group discounts on samples”. Globalna reguła cenowa katalogu również obejmuje próbki.

Przypomnienia nie są wysyłane

Otwórz adres URL zadania cron w przeglądarce i przeczytaj podsumowanie JSON. enabled: false oznacza, że przypomnienia są wyłączone. waiting to zamówienia próbek jeszcze nieopłacone. Sprawdź też czas oczekiwania, opcję newslettera i konfigurację poczty sklepu (Zaawansowane > E-mail).

Próbka znika z koszyka

To kontrola koszyka: duplikat, maksimum na koszyk lub osiągnięty limit klienta. Klient widzi komunikat na stronie koszyka.