Centrum Powiadomień dla Shopware 6: instalacja, konfiguracja i dokumentacja techniczna

Wprowadzenie

Centrum Powiadomień DataFirefly dodaje dzwonek powiadomień w nagłówku storefrontu Shopware 6, tuż obok koszyka. Czerwona plakietka pokazuje liczbę nieprzeczytanych wiadomości (powyżej dziewięciu wyświetlane jest “9+”), a rozwijany panel prezentuje ogłoszenia, nowe produkty i kody rabatowe.

Wtyczka obsługuje trzy typy powiadomień: ogłoszenia redagowane ręcznie, powiadomienia produktowe tworzone automatycznie przy każdym nowym produkcie (obraz i link rozwiązywane w czasie rzeczywistym) oraz kody rabatowe z przyciskiem “Kopiuj”. Każde powiadomienie można zaplanować, targetować po grupie klientów i kanale sprzedaży, priorytetyzować oraz śledzić przez KPI wyświetleń i kliknięć.

Jedna wtyczka, jeden ZIP, zgodność z Shopware 6.5, 6.6 i 6.7, w tym z administracją opartą na Vite w wersji 6.7, dostarczana wstępnie skompilowana, bez etapu builda.

Wymagania

• Shopware 6.5, 6.6 lub 6.7 (shopware/core ~6.5 || ~6.6 || ~6.7)
• Dostęp do wiersza poleceń w celu wyczyszczenia cache i instalacji zasobów
• Brak zewnętrznych zależności, brak usług firm trzecich

Instalacja

1. W administracji przejdź do Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie i wybierz plik ZIP.
2. Zainstaluj, a następnie aktywuj wtyczkę.
3. Wyczyść cache i zainstaluj zasoby:

bin/console plugin:refresh
bin/console plugin:install --activate DffNotificationCenter
bin/console assets:install
bin/console cache:clear

Shopware 6.7 (administracja Vite)

Moduł administracji jest dostarczany wstępnie skompilowany z plikiem entrypoints.json Vite. Ładuje się bez zmian na 6.5, 6.6 i 6.7, bez etapu builda. Po każdej aktualizacji wystarczy uruchomić:

bin/console assets:install
bin/console cache:clear

Konfiguracja

Przejdź do Rozszerzenia → Moje rozszerzenia → Centrum Powiadomień → Konfiguracja. Ustawienia można zawężać per kanał sprzedaży.

Dzwonek powiadomień

• Włącz dzwonek (domyślnie: tak): pokazuje lub ukrywa dzwonek w storefroncie.
• Maksymalna liczba wyświetlanych powiadomień (domyślnie: 10): ograniczona po stronie serwera do zakresu od 1 do 50.
• Odświeżanie w tle (domyślnie: 60 s): interwał odpytywania, 0 wyłącza.
• Dźwięk (domyślnie: nie): odtwarza dźwięk przy otrzymaniu powiadomienia.
• Animacja (domyślnie: tak): animuje dzwonek przy nieprzeczytanych powiadomieniach.

Automatyczne powiadomienia produktowe

• Twórz powiadomienie dla każdego nowego produktu (domyślnie: tak).
• Tylko dla produktów aktywnych (domyślnie: tak).
• Automatyczne wygasanie (domyślnie: 30 dni, 0 = nigdy): po tym czasie powiadomienie produktowe nie jest już wyświetlane.

Automatyczne powiadomienia promo

• Twórz powiadomienie przy utworzeniu promocji z kodem (domyślnie: nie, wymaga jawnego włączenia).

Zarządzanie powiadomieniami w administracji

Moduł zarządzania znajduje się w Marketing → Centrum Powiadomień. Tworzysz tam, planujesz, targetujesz i priorytetyzujesz swoje ogłoszenia oraz przeglądasz KPI wyświetleń/kliknięć.

Dostępne są trzy typy:

• Ogłoszenie (manual): dowolny tytuł, treść, etykieta przycisku i link.
• Produkt (product): powiązane z produktem; obraz okładki i link do karty produktu są rozwiązywane w czasie rzeczywistym przy każdym wyświetleniu, więc nigdy nie ma zepsutych linków.
• Kod rabatowy (promo): wyświetla kod z przyciskiem “Kopiuj” po stronie klienta.

Planowanie, targetowanie i priorytet

• Planowanie: daty validFrom / validUntil; powiadomienie poza swoim oknem czasowym nie jest wyświetlane.
• Targetowanie po grupie klientów: ogranicza dystrybucję do wybranej grupy klientów (puste = wszyscy).
• Targetowanie po kanale sprzedaży: ogranicza do jednego kanału (puste = wszystkie), przydatne przy wielu sklepach.
• Priorytet: liczba całkowita; wyższe priorytety wyświetlają się pierwsze, następnie sortowanie po malejącej dacie utworzenia.

Działanie po stronie klienta

Dzwonek jest wstawiany do nagłówka przez rozszerzenie Twig (sw_extends). Jeśli Twój motyw mocno modyfikuje nagłówek, fallback JavaScript automatycznie wstawia dzwonek obok koszyka.

Panel pobiera powiadomienia przez wywołanie AJAX. Plakietka pokazuje liczbę nieprzeczytanych, z opcjonalnym dźwiękiem i animacją oraz konfigurowalnym odświeżaniem w tle. Interfejs jest dostępny: atrybuty ARIA, nawigacja klawiaturą i wyświetlanie jako bottom-sheet na telefonie.

Architektura techniczna

Wtyczka trzyma się konwencji Shopware: encje deklarowane przez Data Abstraction Layer (DAL), kontroler storefrontu zwracający JSON, subscribery zdarzeń i migracja SQL. Żadnych override’ów: szablony są rozszerzane przez sw_extends, a kod jest w 100% natywny.

Encje i Data Abstraction Layer

Główna encja dff_notification (NotificationDefinition) zawiera pola: type, active, priority, validFrom, validUntil, customerGroupId, salesChannelId, productId (+ productVersionId), promotionId, promoCode, views i clicks. Pola tłumaczalne title, message, buttonLabel i linkUrl znajdują się w encji tłumaczeń dff_notification_translation.

Asocjacje: ManyToOne do customer_group, sales_channel, product i promotion; OneToMany do dff_notification_read (stan przeczytania per klient). Definicje są rejestrowane z tagiem shopware.entity.definition i eksponowane w API (ApiAware).

Schemat bazy danych

Migracja Migration1781049600NotificationCenter tworzy trzy tabele:

• dff_notification: powiadomienie, z indeksami na active i na (product_id, product_version_id). Klucze obce do customer_group i sales_channel (ON DELETE SET NULL) oraz do product (ON DELETE CASCADE).
• dff_notification_translation: tłumaczenia per język (title, message, button_label, link_url).
• dff_notification_read: pary powiadomienie/klient, z unikalnym indeksem na (dff_notification_id, customer_id) zapobiegającym duplikatom odczytu.

Trasy AJAX storefrontu

Trasy są deklarowane w XML (Resources/config/routes.xml), aby zachować zgodność od Shopware 6.5 do 6.7 (Symfony 6.x i 7.x). Kontroler rozszerza AbstractController, a nie StorefrontController, ponieważ zwraca wyłącznie JSON, a setTwig() zniknęło w 6.7.

• GET /dff-nc/list → list(): zwraca powiadomienia do wyświetlenia i inkrementuje ich wyświetlenia.
• POST /dff-nc/read → markRead(): oznacza jako przeczytane po stronie serwera (zalogowani klienci); dla gości odpowiedź wskazuje przechowywanie client.
• POST /dff-nc/click/{id} → click(): inkrementuje licznik kliknięć.

Logika dystrybucji (kontroler list)

Zapytanie DAL filtruje powiadomienia active = true, mieszczące się w oknie ważności (validFrom ≤ teraz ≤ validUntil, dopuszczalne wartości null), zgodne z bieżącym kanałem sprzedaży (lub null) i bieżącą grupą klientów (lub null), posortowane po priorytecie, a następnie malejącej dacie. Powiązane produkty są rozwiązywane dynamicznie (asocjacja cover.media): powiadomienie produktowe, którego produkt został usunięty lub jest niedostępny w danym kanale, jest po cichu ukrywane. Wyświetlenia faktycznie dostarczonych powiadomień są inkrementowane jednym zapytaniem.

Powiadomienia automatyczne (subscribery)

ProductSubscriber nasłuchuje product.written. Przy każdym insercie produktu w wersji live (warianty z parentId są ignorowane) i przy włączonej opcji tworzy powiadomienie typu product, respektując filtr “tylko produkty aktywne”, skonfigurowany czas życia (validUntil) oraz kontrolę antyduplikacyjną per produkt.

PromotionSubscriber nasłuchuje promotion.written. Ponieważ administracja najpierw tworzy promocję, a dopiero potem uzupełnia kod i aktywację kolejnymi aktualizacjami, subscriber reaguje zarówno na inserty, jak i update’y. Powiadomienie promo powstaje tylko wtedy, gdy promocja jest aktywna i posiada kod globalny, z przeniesieniem dat validFrom/validUntil promocji i kontrolą antyduplikacyjną per promocja.

Internacjonalizacja

Storefront i administracja są dostarczane w trzech językach: francuskim, angielskim i niemieckim (snippety fr-FR, en-GB, de-DE). Domyślne tytuły i treści powiadomień produktowych i promo są generowane przez serwis tłumaczeń (klucze dffNc.*).

Prywatność (RODO)

Wtyczka nie zbiera żadnych danych osobowych. Stan przeczytania gości pozostaje w ich przeglądarce (localStorage); stan zalogowanych klientów jest przechowywany po stronie serwera i powiązany z ich kontem. Liczniki wyświetleń i kliknięć są agregowane na poziomie powiadomienia, bez indywidualnych profili.

Odinstalowanie

Przy odinstalowaniu tabele dff_notification_read, dff_notification_translation i dff_notification są usuwane, chyba że zaznaczono opcję “zachowaj dane użytkownika”, w którym to przypadku pozostają nietknięte.

Rozwiązywanie problemów

• Dzwonek się nie pojawia: sprawdź, czy dzwonek jest włączony w konfiguracji, uruchom ponownie assets:install i cache:clear, a następnie wyczyść cache przeglądarki. Fallback JS wstawia dzwonek obok koszyka, jeśli motyw nadpisuje nagłówek.
• Nie powstaje żadne powiadomienie produktowe: opcja musi być włączona, produkt musi być produktem głównym (nie wariantem) i, przy aktywnym filtrze, oznaczony jako aktywny.
• Nie powstaje żadne powiadomienie promo: opcja jest domyślnie wyłączona; promocja musi być aktywna i posiadać kod globalny (kody indywidualne nie są rozpowszechniane).
• Moduł administracji nie ładuje się na 6.7: uruchom ponownie assets:install, potem cache:clear i wymuś przeładowanie przeglądarki (Ctrl+F5).