# 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…

- Strona: <https://www.datafirefly.com/pl/documentation/dff-notification-center-shopware/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/dff-notification-center-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/dff-notification-center-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/dff-notification-center-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/dff-notification-center-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/dff-notification-center-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/dff-notification-center-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/dff-notification-center-shopware/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## 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
```

Po instalacji lub aktualizacji wyczyść także cache przeglądarki (Ctrl+F5) na stronie administracji, aby przeładować moduł.

### 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).

Powiadomienie promo jest tworzone, gdy tylko **aktywna** promocja posiada **kod globalny**. Z założenia kody indywidualne nigdy nie są rozpowszechniane.

## 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.

**Stan przeczytania:** dla zalogowanych klientów jest zapisywany po stronie serwera (tabela `dff_notification_read`), a więc synchronizowany między urządzeniami. Dla gości pozostaje w `localStorage` przeglądarki, żadne dane osobowe nie są zbierane.

## 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).