# DfPreorder SW: kompletny przewodnik

> Shopware nie oferuje natywnie żadnej funkcji "Powiadom mnie, gdy produkt wróci do magazynu". DfPreorder SW wypełnia tę lukę: na każdej karcie produktu niedostępnego pojawia się automatycznie formularz zapisu, a klient…

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

Shopware nie oferuje natywnie żadnej funkcji "Powiadom mnie, gdy produkt wróci do magazynu". DfPreorder SW wypełnia tę lukę: na każdej karcie produktu niedostępnego pojawia się automatycznie formularz zapisu, a klient otrzymuje alert e-mailem, w swoim własnym języku, gdy tylko produkt wróci. Plugin dodaje też lekki tryb przedsprzedaży (plakietka i przewidywana data wysyłki) oraz moduł administracji do śledzenia zapisów. Jeden i ten sam ZIP instaluje się na Shopware 6.5, 6.6 i 6.7. Ten przewodnik obejmuje instalację, kompilację zasobów, workera i zadanie cykliczne, konfigurację, użytkowanie w storefroncie, tryb przedsprzedaży, e-maile, Store API, zgodność z RODO i rozwiązywanie problemów.

Zgodny z Shopware 6.5.x, 6.6.x i 6.7.x na jednym codebase. Nie dodaje żadnej zależności Composera. W odróżnieniu od niektórych pluginów dostarczanych z prekompilowanym distem, DfPreorder zawiera źródła JavaScript: po instalacji konieczna jest kompilacja storefrontu i administracji (patrz niżej).

## Jak działa wykrywanie powrotu do magazynu

DfPreorder wykrywa uzupełnienia zapasów na dwa uzupełniające się sposoby, zbiegające się w tym samym idempotentnym przetwarzaniu, więc Twoi klienci są zawsze powiadamiani, nigdy dwukrotnie:

- **W czasie rzeczywistym**: subscriber nasłuchuje zapisu produktów i reaguje, gdy tylko zmienia się stan magazynowy lub stan dostępny.
- **Zaplanowane skanowanie**: zadanie cykliczne wykonuje się co 15 minut i nadrabia aktualizacje stanów wykonane bezpośrednio w SQL, typowo dekrementację stanu dostępnego przy złożeniu zamówienia albo import z ERP, które nie wyzwalają zdarzenia aplikacyjnego.

Formularz listy oczekujących wyświetla się na karcie produktu, gdy spełnione są dwa warunki: produkt jest w trybie "wyczerpany ukrywa dostępność" (closeout) _oraz_ jego stan dostępny spadł do zera.

## Instalacja

1. Pobierz archiwum `DfPreorder-v1.0.0.zip` ze swojego konta DataFirefly.
2. Skopiuj rozpakowany katalog `DfPreorder` do `custom/plugins/` albo zainstaluj ZIP przez **Administracja → Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie**.
3. Zainstaluj i aktywuj plugin: ``` bin/console plugin:refresh bin/console plugin:install --activate DfPreorder ```
4. Skompiluj zasoby storefrontu i administracji (krok niezbędny, żaden dist nie jest dostarczany): ``` ./bin/build-storefront.sh ./bin/build-administration.sh ```
5. Wyczyść cache: ``` bin/console cache:clear ```

Przy instalacji plugin tworzy tabelę `df_stock_notification`, zestaw pól niestandardowych `df_preorder` na encji produktu, dwa szablony e-mail i zadanie cykliczne. Przy odinstalowaniu bez zachowania danych wszystko jest usuwane.

## Worker i zadanie cykliczne

Aby e-maile rzeczywiście wychodziły, muszą działać dwa mechanizmy, co w produkcji zwykle jest już zapewnione przez admin-workera, systemd albo cron:

- **Worker Messengera**, który konsumuje asynchroniczną wiadomość o uzupełnieniu zapasu i wysyła e-maile;
- **Planer zadań**, który uruchamia skanowanie zabezpieczające co 15 minut.

```
bin/console messenger:consume async --time-limit=60
bin/console scheduled-task:run
```

Jeśli nie działa ani worker, ani planer, zapisy są rejestrowane, ale żaden e-mail nie jest wysyłany. To przyczyna numer jeden zgłoszeń "plugin nikogo nie powiadamia". Sprawdź stan admin-workera w **Ustawienia → System → Kolejka** oraz stan zadań cyklicznych w **Ustawienia → System → Zadania cykliczne**.

## Konfiguracja

Otwórz **Rozszerzenia → Moje rozszerzenia → DataFirefly Przedsprzedaż i Lista Oczekujących → ⋯ → Konfiguruj**. Wszystkie opcje można ustawiać **per kanał sprzedaży** dzięki natywnemu selektorowi u góry strony.

- **Włącz listę oczekujących**: główny przełącznik. Wyświetla formularz na kartach produktów niedostępnych.
- **Double opt-in**: wymaga potwierdzenia e-mailem przed aktywacją zapisu (zalecane pod RODO). Domyślnie wyłączone.
- **Zezwól gościom**: po wyłączeniu zapisać mogą się wyłącznie zalogowani klienci.
- **Usuń zapis po powiadomieniu**: minimalizacja danych, adres e-mail jest kasowany po wysłaniu alertu. Po wyłączeniu zapis jest zachowywany ze statusem "powiadomiony".
- **Powiadomienia partiami**: maksymalna liczba e-maili wysyłanych na jedno wykonanie (worker lub skanowanie). Domyślnie 100.
- **Pokaż plakietkę przedsprzedaży**: włącza wyświetlanie plakietki i daty wysyłki na produktach skonfigurowanych jako przedsprzedaż.

## Lista oczekujących w storefroncie

Gdy produkt jest niedostępny (closeout + stan dostępny równy zero), formularz "Powiadom mnie o powrocie do magazynu" wyświetla się automatycznie pod przyciskiem zakupu. Klient wpisuje swój e-mail (uzupełniony wstępnie, jeśli jest zalogowany) i zatwierdza.

- Wysłanie odbywa się przez **AJAX** z pełnym fallbackiem bez JavaScriptu (komunikat flash + przekierowanie).
- Niewidoczne pole **honeypot** filtruje boty.
- Przy włączonym **double opt-in** wysyłany jest e-mail potwierdzający; zapis staje się aktywny dopiero po kliknięciu w link potwierdzający.
- Każdy e-mail może zawierać **link wypisu jednym kliknięciem**.

Formularz jest renderowany w nadpisywalnym szablonie: `views/storefront/component/df-waitlist/waitlist-form.html.twig`, wstrzykiwanym przez buy-widget. Nadpisz go w swoim motywie, aby zmienić wygląd albo umiejscowienie.

## Tryb przedsprzedaży

Plugin tworzy grupę pól niestandardowych **Przedsprzedaż** na encji produktu. Otwórz produkt w **Katalogi → Produkty**, zakładka **Specyfikacje → Pola niestandardowe**, grupa **Przedsprzedaż**:

- **Włącz przedsprzedaż**: przełącznik aktywacji dla tego produktu.
- **Przewidywana data wysyłki**: data wyświetlana w plakietce.
- **Notatka przedsprzedaży**: dowolny tekst wyświetlany pod plakietką.

Gdy przedsprzedaż jest włączona, a plakietka dozwolona w konfiguracji, nad przyciskiem zakupu wyświetla się bursztynowa plakietka z przewidywaną datą wysyłki. Rendering jest wydzielony w szablonie buy-widgetu i pozostaje nadpisywalny.

## E-maile i tłumaczenia

Przy instalacji tworzone są dwa szablony e-mail, przetłumaczone na pięć języków: francuski, angielski, niemiecki, hiszpański i włoski:

- **Powrót do magazynu** (`df_preorder.back_in_stock`): zmienne `productName`, `productUrl` i pełny obiekt `product`.
- **Potwierdzenie zapisu** (`df_preorder.double_opt_in`): dodaje zmienną `confirmUrl`.

Każdy klient jest powiadamiany w języku sklepu z chwili swojego zapisu: plugin odtwarza kontekst języka właściwy dla subskrybenta, aby rozwiązać przetłumaczoną nazwę produktu i właściwy szablon. Adres URL produktu jest rozwiązywany przez kanoniczny URL SEO danego kanału i języka.

Szablony pozostają w pełni edytowalne w **Ustawienia → E-maile → Szablony e-mail**. Wyszukaj "powrót do magazynu" albo "back in stock", aby je odnaleźć.

## Moduł administracji

Menu **Marketing → Lista Oczekujących i Przedsprzedaż** wyświetla wszystkie zapisy: adres e-mail, produkt, status (oczekujący / potwierdzony / powiadomiony), datę zapisu i datę powiadomienia. Dostępne jest usuwanie masowe, przydatne do ręcznego czyszczenia starych zapisów.

## Store API (headless / mobile)

Dla sklepów headless i aplikacji mobilnych punkt wejścia Store API pozwala zapisać klienta na listę oczekujących:

```
POST /store-api/df-waitlist/subscribe
Content-Type: application/json
sw-access-key: <your-access-key>

{
  "productId": "0189a1b2c3d4...",
  "email": "client@example.com"
}
```

Poprawne żądanie zwraca odpowiedź sukcesu; nieprawidłowy identyfikator produktu lub e-mail zwraca błąd 400. Obowiązują te same reguły konfiguracji (double opt-in, zezwolenie dla gości itd.).

## Zgodność z RODO

- Adresy e-mail są zbierane wyłącznie na potrzeby zamówionego powiadomienia.
- Opcjonalny double opt-in rejestruje wyraźną zgodę.
- Domyślne zachowanie usuwa dane osobowe zaraz po wysłaniu alertu.
- Link wypisu jednym kliknięciem można wstawić w szablonach e-mail.
- Odinstalowanie z usunięciem danych kasuje tabelę, szablony, pola niestandardowe i konfigurację.

## Zgodność 6.5 → 6.7 i rozwiązywanie problemów

**Formularz nie wyświetla się na niedostępnym produkcie.** Sprawdź, czy opcja "Włącz listę oczekujących" jest zaznaczona dla właściwego kanału sprzedaży, czy produkt jest w trybie closeout i czy jego stan dostępny wynosi zero. Wyczyść cache po każdej zmianie konfiguracji.

**Zapisy są rejestrowane, ale żaden e-mail nie wychodzi.** Worker Messengera i/lub planer zadań nie działają. Uruchom je ręcznie w celu testu (patrz sekcja Worker), a następnie zapewnij ich ciągłe działanie w produkcji.

**Błąd serwisu mail przy aktywacji na Shopware 6.7.** Abstrakcyjna klasa serwisu mail została zastąpiona klasą konkretną w 6.7. Plugin obsługuje tę różnicę automatycznie przez compiler pass tworzący odpowiedni alias; zwykłe `cache:clear` przekompilowuje kontener, jeśli błąd utrzymuje się po aktualizacji.

**E-mail wychodzi w złym języku.** Przyjmowany jest język kanału sprzedaży z momentu zapisu. Sprawdź, czy dany kanał ma oczekiwany język i czy szablon e-maila ma tłumaczenie dla tego języka.

**E-maile wyglądają na wysłane podwójnie.** To nie powinno się zdarzać: przetwarzanie jest idempotentne i oznacza (albo usuwa) każdy zapis po wysyłce. Jeśli to obserwujesz, sprawdź, czy nie uruchamiasz kilku równoległych workerów bez odpowiedniej konfiguracji transportu.

**Co dzieje się przy odinstalowaniu?** Z opcją usunięcia danych tabela `df_stock_notification`, dwa szablony e-mail, zestaw pól `df_preorder`, zadanie cykliczne i konfiguracja są usuwane. Bez tej opcji wszystko jest zachowywane na potrzeby późniejszej ponownej instalacji.