DataFirefly Advent Calendar: kalendarz adwentowy dla PrestaShop
Instalacja i aktualizacja, ustawienia i cron przypomnień, gotowe szablony, okienka i kody rabatowe, natychmiastowa wygrana, podgląd, e-maile, losowanie, statystyki i rozwiązywanie problemów.
Instalacja i aktualizacja
Zainstaluj moduł w Moduły > Menedżer modułów > Załaduj moduł, wysyłając plik ZIP, albo skopiuj folder dfadventcalendar do katalogu /modules/ sklepu i kliknij Instaluj. Ten sam ZIP działa od PrestaShop 1.7.8 do 9.x.
Instalacja tworzy tabele modułu, rejestruje jego hooki, tworzy stronę kalendarza (jeden adres na język) i dodaje kartę Katalog > Rabaty > Kalendarz adwentowy. Obrazy okienek są przechowywane w /img/dfadventcalendar/, poza folderem modułu.
Aktualizacja z wersji 1.0.0: wyślij nowy ZIP, a PrestaShop uruchomi migrację. Kalendarze, okienka, uczestnicy i kody zostają zachowane. Poprzedni adres strony działa nadal we wszystkich językach, więc linki wysłane już e-mailem dalej działają.
Ustawienia modułu
Strona konfiguracji modułu (przycisk Konfiguruj) zbiera ustawienia wspólne dla wszystkich kalendarzy.
- Adres strony kalendarza: jeden adres na język, na przykład
/kalendarz-adwentowypo polsku i/advent-calendarpo angielsku. Moduł odrzuca adres używany już przez inną stronę. Tytuł SEO strony ustawisz w Preferencje sklepu > Ruch i SEO. - Strefa czasowa i godzina sklepu: okienka otwierają się w tej strefie, niezależnie od strefy odwiedzającego czy serwera.
- Przypomnienia na uruchomienie cron: maksymalna liczba e-maili wysyłanych przy każdym wywołaniu (domyślnie 150).
- Zachowaj dane przy odinstalowaniu: kalendarze, okienka, uczestnicy i obrazy zostają w bazie, gotowe do ponownej instalacji.
- Zegar testowy (tylko w trybie debugowania): cały kalendarz działa tak, jakby była wpisana data i godzina. Panel pokazuje ostrzeżenie, dopóki zegar jest ustawiony. Nigdy nie zostawiaj go włączonego w działającym sklepie.
Codzienne przypomnienie: zadanie cron
Skopiuj wyświetlony adres cron i zaplanuj go co 15 minut w panelu hostingu:
*/15 * * * * curl -s "https://www.twoj-sklep.pl/module/dfadventcalendar/cron?token=TWOJ_TOKEN" > /dev/null
Kalendarz działa bez cron: zależą od niego tylko e-maile z przypomnieniem. Wyświetlana jest data ostatniego uruchomienia, a lista kontrolna startu na pulpicie sygnalizuje zatrzymany cron.

Tworzenie kalendarza
Otwórz Katalog > Rabaty > Kalendarz adwentowy. Najszybciej jest zacząć od szablonu: daty, liczba okienek, motyw i tytuł we wszystkich Twoich językach są już przygotowane. Pozostaje tylko wypełnić okienka.
- Kalendarz adwentowy, 24 okienka lub 25 okienek z dniem Bożego Narodzenia, od 1 grudnia;
- 12 dni przed świętami, od 13 do 24 grudnia;
- Tydzień Black Friday, 7 okienek do ostatniego piątku listopada;
- Odliczanie do wydarzenia, 10 okienek przed premierą lub wyprzedażą prywatną.
Przycisk Pusty kalendarz lub Nowy kalendarz pozwala wybrać każde ustawienie samodzielnie.

Daty i otwieranie
- Data pierwszego okienka i liczba okienek (od 1 do 60): jedno okienko dziennie od tej daty.
- Godzina otwarcia okienek: 00:00 dla północy albo stała godzina, np. 08:00. Przed tą godziną okienkiem dnia pozostaje okienko z poprzedniego dnia.
Wygląd
Dostępnych jest dziewięć motywów: Las jodłowy, Papier kraft, Szron, Zimowa noc, Laska cukrowa oraz cztery motywy poza świętami (Czerń i złoto, Black Friday, Wiosenny pastel, Letnia laguna). Opcja Własne kolory włącza cztery kolory. Dostępne są trzy style okienek: otwierane drzwiczki, pudełka prezentowe ze wstążką i minimalistyczne kafelki. Dekoracja ożywia tło: śnieg, gwiazdy, konfetti albo brak. Podgląd na żywo pokazuje efekt podczas ustawiania.
Przy zróżnicowanych rozmiarach siatka wypełnia się bez luk na 6 lub 4 kolumnach. Na telefonie przechodzi na 4 równe kolumny. Animacje są wyłączane dla odwiedzających, którzy w swoim urządzeniu wybrali ograniczenie ruchu.

Udział
- E-mail wymagany do otwierania okienek: po wyłączeniu odwiedzający otwierają okienka swobodnie, ale kody osobiste i gry pozostają zarezerwowane dla uczestników.
- Tylko dla kont klientów: biorą udział wyłącznie zalogowani klienci, a ich kody są powiązane z ich kontem. To najlepsza ochrona przed zbieraniem kodów za pomocą jednorazowych adresów.
- Potwierdzenie adresu e-mail (double opt-in) oraz opcjonalne, niezaznaczone pole zgody na newsletter.
- Zezwalaj na otwieranie minionych okienek: kody wspólne pozostają wtedy ważne do końca kalendarza.
- Tekst zgody: dodaj link do swojej polityki prywatności.
Konfiguracja okienek
Pulpit kalendarza pokazuje okienka jako karty: data, typ, nagroda, kod, otwarcia, odsłonięte kody i zamówienia. Filtry Do konfiguracji, Z kodem, Natychmiastowa wygrana, Dziś i nadchodzące i Minione oraz wyszukiwarka od razu znajdują okienko. Każda karta pozwala edytować okienko, otworzyć jego podgląd lub je aktywować.

Typy okienek
- Wiadomość: tekst, obraz i opcjonalny przycisk.
- Kod rabatowy: kod jest w centrum uwagi, na bilecie do skopiowania lub dodania do koszyka.
- Odsłonięty produkt: karta produktu z ceną i przyciskiem dodania do koszyka.
- Natychmiastowa wygrana: uczestnik próbuje szczęścia i wygrywa nagrodę z ustaloną przez Ciebie szansą.
Nagroda i kod
Rabat procentowy, rabat kwotowy, darmowa dostawa, produkt w prezencie albo istniejąca reguła koszyka sklepu z własnymi warunkami. Dla nagród tworzonych przez moduł:
- Kod osobisty: jednorazowa reguła koszyka jest generowana, gdy uczestnik otwiera okienko. Jest powiązana z kontem klienta, jeśli jest znane, i ważna do północy, plus wybrana dodatkowa ważność.
- Ten sam kod dla wszystkich: jedna reguła koszyka na okienko, synchronizowana automatycznie. Zostaw pole puste, aby otrzymać kod automatyczny (prefiks, rok i numer, np.
ADVENT26-07). - Opcjonalna minimalna kwota zamówienia i ograniczenie do odsłoniętego produktu.
Przyciski Poprzednie okienko i Następne okienko pozwalają wypełnić kalendarz jednym ciągiem. Brak czasu? Wypełnij puste okienka stosuje gotowy plan przetłumaczony na wszystkie Twoje języki.
Natychmiastowa wygrana
Ustaw szansę na wygraną (od 1 do 100%), liczbę nagród (0 bez limitu) i wiadomość, gdy uczestnik nie wygra. Losowanie odbywa się na serwerze przy otwarciu okienka, raz na uczestnika. Ponowne otwarcie okienka daje ten sam wynik. Gdy wszystkie nagrody zostaną wygrane, kolejni uczestnicy widzą wiadomość o przegranej.

Podgląd i uruchomienie
Pulpit zbiera wszystko, czego potrzebujesz do uruchomienia kalendarza:
- Podgląd na dzień: wybierz datę i otwórz kalendarz tak, jak będzie wyglądał tego dnia. Pokazane kody są przykładowe i nic nie jest zapisywane. Linki podglądu wygasają po 7 dniach.
- Lista kontrolna startu: kalendarz aktywny, okienka skonfigurowane, cron przypomnień i e-maile sklepu.
- Więcej > Wyślij mi e-maile testowe: cztery e-maile (przypomnienie, powitanie, potwierdzenie, link dostępu) trafiają do zalogowanego pracownika, w jego języku.

Co widzi klient
Strona kalendarza otwiera się odliczaniem do następnego okienka, z wyróżnionym okienkiem dnia. Po zapisaniu się uczestnik widzi swój pierścień postępu, serię dni z rzędu i przełącznik codziennego przypomnienia.

Okienka mają pięć stanów: dziś (animowana poświata), do nadrobienia, otwarte (treść widoczna), nadchodzące (kłódka i data) oraz przegapione. Gwiazdka oznacza okienka z grą.

Po otwarciu okno pokazuje niespodziankę: produkt z ceną, kod na bilecie, przyciski Dodaj do mojego koszyka i Kopiuj. Jeśli koszyk jest pusty, kod jest przechowywany przez 14 dni i stosowany do pierwszego dodanego produktu.

Podsumowanie Twoje kody wyświetla zdobyte kody wraz z ich ważnością i stanem (wykorzystany, wygasły).

Na telefonie siatka przechodzi na 4 równe kolumny, a panele układają się jeden pod drugim.

Gra z natychmiastową wygraną
Okienko z grą pozwala uczestnikowi spróbować szczęścia. Jeśli wygra, otrzymuje kod tak jak w zwykłym okienku. W przeciwnym razie widzi wiadomość o przegranej i może zagrać w następnym okienku z grą. Odwiedzający, który się nie zapisał, jest proszony o podanie e-maila: jedna szansa na uczestnika.

Baner na stronie głównej i pływający przycisk
Baner pojawia się na stronie głównej w czasie trwania kalendarza i, jeśli chcesz, kilka dni przed jego startem. Pływający przycisk, włączany w ustawieniach kalendarza, przypomina o okienku dnia na każdej stronie. Odwiedzający może go ukryć do następnego dnia. Aby umieścić baner w innym miejscu, dodaj {hook h='displayDfAdventCalendar'} do szablonu swojego motywu.

Odliczania poza świętami
Ten sam moduł obsługuje każdy ważny moment: tydzień Black Friday, premierę kolekcji, wyprzedaże, urodziny sklepu. Wybierz szablon odliczania, motyw taki jak Czerń i złoto, minimalistyczne kafelki i godzinę otwarcia. Przed startem strona pokazuje odliczanie do pierwszego okienka.

Przypomnienia i e-maile
Codziennie od wybranej godziny (nigdy przed otwarciem okienek) krótki e-mail zapowiada okienko dnia potwierdzonym uczestnikom, którzy jeszcze go nie otworzyli. Uczestnik otrzymuje najwyżej jedno przypomnienie dziennie i żadnego w dniu zapisu: wystarczy e-mail powitalny. E-maile mają kolory motywu kalendarza.

W mails/ znajdują się cztery szablony w ośmiu językach: dfadvent_reminder (przypomnienie), dfadvent_welcome (powitanie), dfadvent_confirm (potwierdzenie adresu) i dfadvent_access (link dostępu). Uczestnik, który ponownie wpisze swój adres, otrzymuje link dostępu: moduł nigdy nie loguje nikogo na podstawie samego wpisanego adresu, a ten sam adres otrzymuje najwyżej jeden e-mail co 2 minuty. Aby dostosować szablony, skopiuj je do themes/twoj-motyw/modules/dfadventcalendar/mails/.

Uczestnicy
Listę uczestników filtruje się jednym kliknięciem: potwierdzeni, oczekujący na potwierdzenie, przypomnienia włączone, newsletter, konta klientów, zwycięzcy losowania. Pokazuje otwarte okienka i zdobyte kody każdego uczestnika i eksportuje się do CSV.

Losowanie końcowe
W ustawieniach kalendarza określ minimalną liczbę otwartych okienek potrzebną do udziału (0 wyłącza losowanie) i opisz nagrodę. Pulpit pokazuje liczbę uprawnionych uczestników. Przycisk Wylosuj zwycięzcę losuje spośród uprawnionych potwierdzonych uczestników, z pominięciem wcześniejszych zwycięzców. Każde losowanie jest zapisywane.
Losowanie nagród i gra z natychmiastową wygraną podlegają przepisom o grach i loteriach promocyjnych. Opublikuj regulamin w swoim sklepie przed startem.
Statystyki
Pulpit pokazuje uczestników (potwierdzonych, z kontem klienta), otwarte okienka i średnią na uczestnika, odsłonięte kody i odsetek wykorzystanych kodów osobistych, ważne zamówienia złożone z kodem, przychód netto z tych zamówień oraz aktywne przypomnienia. Wykres aktywności pokazuje otwarcia i zapisy okienko po okienku.
Jeśli w sklepie jest Google Tag Manager, moduł wysyła do dataLayer zdarzenia: dfadv_join, dfadv_door_open, dfadv_code_copy, dfadv_code_apply i dfadv_share.
Menu Więcej > Powiel na następny rok kopiuje kalendarz i jego okienka z przesunięciem o rok, jako nieaktywny, bez uczestników i kodów.
Dane osobowe
- Pole zgody jest obowiązkowe, pole newslettera jest osobne i niezaznaczone.
- Każdy e-mail z przypomnieniem zawiera link do wypisania się jednym kliknięciem.
- Adres IP jest przechowywany wyłącznie w postaci skrótu, aby ograniczyć zapisy do 5 na godzinę na połączenie.
- Moduł obsługuje wnioski PrestaShop o eksport (wraz z kodami) i usunięcie danych osobowych.
Rozwiązywanie problemów
Przypomnienia nie są wysyłane
Sprawdź listę kontrolną startu na pulpicie: cron uruchomiony w ciągu ostatnich 24 godzin, e-maile sklepu włączone. Przypomnienia wychodzą od wybranej godziny i tylko do potwierdzonych uczestników, którzy nie otworzyli jeszcze okienka dnia.
Strona kalendarza zwraca błąd 404
Sprawdź, czy przyjazne adresy URL są włączone, a następnie wyczyść pamięć podręczną. Jeśli adres koliduje z inną stroną, zmień go w ustawieniach modułu.
Okienko pozostaje zamknięte w swoim dniu
Sprawdź godzinę otwarcia kalendarza i strefę czasową sklepu (Międzynarodowy > Lokalizacja). Okienko nieskonfigurowane lub nieaktywne pozostaje zamknięte.
Kod nie jest dodawany do koszyka
Wyświetlany komunikat pochodzi z PrestaShop: nieosiągnięta minimalna kwota, wygasły kod lub kod powiązany z innym kontem klienta. Jeśli koszyk jest pusty, kod czeka i zostaje zastosowany do pierwszego produktu.
Kompatybilność
- PrestaShop od 1.7.8 do 9.x, ten sam ZIP dla wszystkich wersji.
- Motywy Classic, Hummingbird i motywy pochodne.
- Multistore (jeden kalendarz na sklep) i wiele walut (kwoty przeliczane na walutę odwiedzającego).
- Architektura ModuleAdminController, bez zależności Composer.
- Moduł przetłumaczony na angielski, francuski, hiszpański, niemiecki, włoski, niderlandzki, polski i portugalski.