# DataFirefly Push: kompletny przewodnik

> Prezentacja i wymagania DataFirefly Push zamienia Twój sklep WooCommerce w natywną platformę powiadomień Web Push. Bez SDK, bez śledzenia przez podmioty trzecie: cała kryptografia (VAPID i szyfrowanie RFC 8291) działa…

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

## Prezentacja i wymagania

DataFirefly Push zamienia Twój sklep WooCommerce w natywną platformę powiadomień Web Push. Bez SDK, bez śledzenia przez podmioty trzecie: cała kryptografia (VAPID i szyfrowanie RFC 8291) działa na Twoim serwerze w czystym PHP przez OpenSSL. Wtyczka obejmuje inteligentny opt-in w wielu stylach, dziesięć automatycznych triggerów, kampanie ręczne z wizualnym builderem i segmentacją, kompletny dashboard analityczny, dedykowaną stronę Moje konto dla klientów oraz natywną zgodność z RODO.

- WordPress 6.2 i nowszy.
- WooCommerce 7.0 i nowszy, testowane do 9.6, zgodne z HPOS oraz blokami Koszyka/Zamówienia.
- PHP 8.1 i nowszy.
- Wielojęzyczność (FR/EN/ES/DE/IT), zgodność z Polylang i WPML.
- Zgodność z LiteSpeed Cache, WP Rocket i innymi wtyczkami cache: Service Worker jest serwowany jako samodzielny plik PHP.

Żadnej usługi zewnętrznej do podłączenia, żadnej biblioteki Composera do utrzymania. Klucze VAPID są generowane automatycznie przy aktywacji, a subskrypcje i zdarzenia pozostają w Twojej bazie danych.

## Instalacja

1. Pobierz archiwum `df-push.zip` ze swojego konta klienta.
2. W panelu WordPressa przejdź do **Wtyczki > Dodaj nową > Wyślij wtyczkę na serwer** i prześlij archiwum.
3. Kliknij **Włącz**.
4. W pasku bocznym administracji pojawi się menu **DF Push** z siedmioma pozycjami: Dashboard, Kampanie, Subskrybenci, Triggery, Opt-in, Ustawienia, Webhooks i API.

Przy aktywacji wtyczka tworzy osiem dedykowanych tabel z prefiksem `dfpush_`, generuje klucze VAPID, planuje dzienny cron `df_push_daily_lifecycle` i rejestruje endpoint Mojego konta. Żadna ręczna interwencja nie jest potrzebna.

## Pierwsza konfiguracja: klucze VAPID i opt-in

Po aktywacji wtyczka działa od razu z ustawieniami domyślnymi: pływający dzwonek pojawia się w prawym dolnym rogu po pięciu sekundach, pre-prompt jest włączony, triggery automatyczne są gotowe. Przed komunikowaniem usługi sprawdź tylko dwie rzeczy w **DF Push > Ustawienia**:

- **Klucz publiczny VAPID**: blok pokazuje Twój automatycznie wygenerowany klucz publiczny (application server key używany przez przeglądarkę). Możesz go zregenerować, ale unieważni to wszystkie istniejące subskrypcje.
- **Manifest PWA** i **ikona domyślna**: dodaj swoją ikonę (minimum 192×192), jeśli `site_icon` nie jest ustawione na witrynie.

Żadnej usługi zewnętrznej do rejestracji, żadnego konta deweloperskiego Firebase / OneSignal. Generowane przez wtyczkę klucze VAPID wystarczają: uwierzytelniają Twój serwer aplikacji wobec push services FCM, Mozilla Push i WNS.

## Zakładka Opt-in: prompt, style i wyzwalacze

Ta zakładka steruje prośbą o subskrypcję. Dostępnych jest pięć stylów, każdy z konfigurowalną pozycją i motywem:

- **Pływający dzwonek** (domyślny): dyskretna pastylka w prawym lub lewym dolnym rogu.
- **Baner** u góry lub u dołu strony.
- **Modal** wyśrodkowany z overlayem.
- **Slide-in** boczny.
- **Sticky bar** przypięty u góry.

**Pre-prompt soft ask** (zalecany) wyświetla Twój własny komunikat przed natywną prośbą przeglądarki. Ten mechanizm chroni Twój limit opt-in: w Chrome odrzucenie pre-promptu nie zużywa limitu próśb natywnych (×3 zamiast 1 bez pre-promptu).

Pięć konfigurowalnych, łączonych wyzwalaczy:

- **Opóźnienie** (w sekundach) po załadowaniu strony.
- **Scroll** jako procent strony (0 = wyłączone).
- **Exit-intent** przy ruchu myszy w stronę wyjścia (tylko desktop).
- **X obejrzanych stron** w sesji.
- **Dodanie do koszyka** (przechwytuje zdarzenie WooCommerce `added_to_cart`).

Włącz **test A/B promptu** z tytułem i komunikatem wariantu B oraz konfigurowalnym podziałem. Przydział jest utrwalany w localStorage, aby zapewnić spójność między sesjami dla danego odwiedzającego.

Raz odrzucona zgoda przeglądarki nie może zostać ponownie zażądana skryptem. Zadbaj o pre-prompt i nie wywołuj prośby przy pierwszym scrollu: obserwuje się wtedy 70 % odmów, wobec 20-30 % przy pre-prompcie wyzwolonym we właściwym momencie.

## Zakładka Triggery: automatyzacje

Dziesięć automatycznych triggerów, każdy włączany indywidualnie w zakładce **Triggery**. Każdy korzysta z Action Schedulera do wysyłek odroczonych, z synchronicznym fallbackiem, gdy Action Scheduler jest niedostępny.

### Porzucony koszyk

Trzy konfigurowalne przypomnienia, domyślnie 1 godzinę, 24 godziny i 72 godziny po porzuceniu. Detekcja przechwytuje zdarzenie `added_to_cart` dla subskrybentów Push i planuje trzy akcje `df_push_abandoned_cart` w malejących odstępach. Przypomnienia są anulowane automatycznie, jeśli zamówienie zostało w międzyczasie złożone.

### Powrót do magazynu (back-in-stock)

Na stronie produktu subskrybenci mogą dołączyć do listy oczekujących per produkt. Gdy WooCommerce wyzwala `woocommerce_product_set_stock_status` z powrotem do _instock_, wtyczka wysyła powiadomienie do listy oczekujących produktu, a następnie ją opróżnia.

### Obniżka ceny

Wtyczka utrzymuje metadaną `_df_push_last_price` per produkt. Przy każdej aktualizacji produktu porównuje starą i nową cenę. Jeśli obniżka przekracza skonfigurowany **minimalny próg procentowy**, powiadomienie trafia do tematu _Promocje_.

### Potwierdzenie, wysyłka, opinia

- **Potwierdzenie zamówienia**: natychmiastowa wysyłka przy `woocommerce_thankyou` do subskrybenta, jeśli identyfikator użytkownika się zgadza.
- **Wysyłka**: wykrywa numer śledzenia zamówienia, czytając kolejno metadane `_tracking_number`, `_wc_shipment_tracking_items` (WooCommerce Shipment Tracking) i `_aftership_tracking_number` (AfterShip). Znaleziony numer trafia do treści powiadomienia.
- **Prośba o opinię**: planowana X dni po przejściu zamówienia w status _completed_ (opóźnienie konfigurowalne).

### Urodziny, reaktywacja, nowy produkt

- **Urodziny**: dzienny cron `df_push_daily_lifecycle` odczytuje pole `billing_birthday` z WooCommerce i wysyła powiadomienie do subskrybentów obchodzących urodziny.
- **Reaktywacja**: wysyłka do subskrybentów nieaktywnych od 30, 60 i 90 dni (okna konfigurowalne w CSV: `30,60,90`).
- **Nowy produkt**: przy publikacji produktu powiadomienie trafia do tematu _Nowości_.

Każdy trigger przyjmuje szablonowy payload: `{firstname}`, `{product_name}`, `{product_price}`, `{old_price}`, `{order_number}`, `{tracking_number}`, `{category}`, `{discount_code}`. Zmienne są rozwiązywane w chwili wysyłki, nie przy planowaniu.

## Zakładka Kampanie: wizualny builder, segmentacja, test A/B

Zbuduj kampanię ręczną w **DF Push > Kampanie > Nowa kampania**. Builder oferuje podgląd na żywo powiadomienia w takiej postaci, w jakiej pojawi się na urządzeniu subskrybenta.

- **Treść**: tytuł, komunikat, adres docelowy, obraz hero, do dwóch przycisków akcji z własną etykietą i adresem.
- **Powiadomienie trwałe** (opcja _requireInteraction_): powiadomienie pozostaje widoczne do interakcji.
- **Segmentacja** według języka, kraju, urządzenia, tematu oraz zachowań RFM: minimalna liczba zamówień, minimalny średni koszyk, dni nieaktywności, kupiona kategoria. Segmenty behawioralne są liczone przez `wc_get_orders` przy starcie.
- **Test A/B**: włącz wariant B (tytuł i komunikat), podział jest konfigurowalny w procentach. Przydział jest losowy per subskrybent, deterministyczny po identyfikatorze dla spójności analityki.
- **Planowanie**: wybierz datę i godzinę albo uruchom natychmiast.
- **Tryb testowy**: wyślij kampanię wyłącznie do administratorów, z buildera, przed startem produkcyjnym.

Silnik wysyłki automatycznie dzieli segment na fragmenty, respektuje quiet hours według strefy czasowej subskrybenta, stosuje skonfigurowany frequency capping i na bieżąco czyści endpointy zwracające 404 lub 410 (wypisanie po stronie przeglądarki).

## Dashboard i analityka

Panel **DF Push > Dashboard** agreguje KPI z 30 dni. Chart.js jest dołączony lokalnie (żadnych zależności od zewnętrznego CDN).

- **KPI**: aktywni subskrybenci, wskaźnik opt-in, wysyłki, wskaźnik kliknięć (CTR), konwersje, przypisany przychód.
- **Seria czasowa 30 dni**: wysyłki kontra kliknięcia, linia per dzień.
- **Heatmapa 7 × 24**: najlepsze okna wysyłki według kliknięć, w układzie dzień tygodnia i godzina.
- **Lejek per kampania**: wysłane > dostarczone > kliknięte > skonwertowane.
- **Przypisany przychód**: konfigurowalne okno atrybucji (domyślnie 72 godziny) wiąże każde kliknięcie z pierwszym zakupem złożonym w tym oknie przez subskrybenta.
- **Eksport CSV** wszystkich zdarzeń do audytu RODO albo integracji BI.

## Strona klienta: Moje konto → Powiadomienia

Do panelu WooCommerce automatycznie dodawana jest dedykowana strona **Moje konto → Powiadomienia**. Klient ma tam cztery bloki:

- **To urządzenie**: bieżący status (włączone, wyłączone, zablokowane przez przeglądarkę, nieobsługiwane), z przyciskiem Włącz lub Wyłącz na tym urządzeniu.
- **Wszystkie urządzenia**: lista subskrybowanych urządzeń (typ, przeglądarka, język, ostatnia aktywność), z indywidualnym wypisaniem lub wypisaniem wszystkich jednym kliknięciem.
- **Moje preferencje**: pola wyboru dla tematów natywnych (Nowości, Promocje, Powrót do magazynu). Zapis przez REST z potwierdzeniem.
- **Historia powiadomień**: 30 ostatnich otrzymanych powiadomień, z tytułem, treścią, ikoną, linkiem i datą.

Adres to `/moje-konto/df-push-notifications/` (zależnie od bazy Mojego konta). Rewrite endpoint jest rejestrowany z maską `EP_ROOT | EP_PAGES`, z autonaprawą na `init:999`, która wykrywa brakującą regułę (przypadek równoległego flusha permalinków) i automatycznie wykonuje ponowny flush.

Akcje klienta (wypisanie, preferencje) przechodzą przez trasy REST pod `df-push/v1/account/*`, uwierzytelnione ciasteczkiem + nonce `wp_rest`. Żadna akcja nie może zostać wykonana na cudzym koncie, nawet przy manipulacji identyfikatorem urządzenia w żądaniu.

## RODO i rejestr zgód

Zgodność z RODO jest obsługiwana natywnie, nie jako kosmetyczny dodatek. Każdy opt-in i każde wypisanie trafia do tabeli `dfpush_consent_log` z:

- identyfikatorem subskrybenta,
- akcją: _subscribe_ lub _unsubscribe_,
- adresem IP hashowanym SHA-256 (jawne IP nigdy nie jest utrwalane),
- user-agentem,
- znacznikiem czasu UTC.

Natywne WordPress Privacy Exporters i Erasers są podłączone: klient może zażądać eksportu lub usunięcia swoich danych osobowych z **Narzędzia → Eksportuj dane osobowe** lub **Narzędzia → Usuń dane osobowe**. Wtyczka dołącza wtedy jego subskrypcje, tematy, inbox i rejestr zgód do odpowiedzi, albo usuwa je zgodnie z żądaniem.

## Zakładka Ustawienia: antyspam i atrybucja

Ta zakładka centralizuje parametry poszanowania subskrybentów i okno atrybucji:

- **Godziny ciszy** (quiet hours): przedział, w którym żadne powiadomienie nie jest wysyłane. Uwzględnia strefę czasową subskrybenta (odczytaną z urządzenia przy opt-in przez `Intl.DateTimeFormat().resolvedOptions().timeZone`). Domyślnie 22:00-8:00 czasu lokalnego.
- **Frequency cap**: maksymalna liczba powiadomień dziennie per subskrybent. 0 = bez limitu.
- **Smart send time**: optymalizuje godzinę wysyłki per subskrybent na podstawie jego historycznych okien kliknięć.
- **Okno atrybucji**: czas w godzinach między kliknięciem a zamówieniem, aby zamówienie zostało przypisane powiadomieniu. Domyślnie 72 godziny.
- **Inbox in-site**: włącza lub wyłącza pływający dzwonek z historią powiadomień na froncie.
- **Manifest PWA**: włącza generowanie manifestu, dzięki czemu witryna jest instalowalna na urządzeniach mobilnych.

## Zakładka Webhooks i API REST

Zakładka **Webhooks i API** obejmuje dwa mechanizmy integracji.

### Webhooks wychodzące

Skonfiguruj jeden lub więcej endpointów HTTP per zdarzenie. Dostępne są trzy formaty:

- **Slack**: payload `{ text }` zgodny ze slackowymi Incoming Webhooks.
- **Discord**: payload `{ content }` zgodny z webhookami Discorda.
- **Generic**: pełny payload JSON z event, timestamp, data, zgodny z Zapierem, n8n i Make.

Dostępne zdarzenia: `subscriber.created`, `campaign.launched`, `notification.clicked`, `order.attributed`. Żądania są nieblokujące (`wp_remote_post` z `blocking=false`), aby nigdy nie spowalniać wysyłki głównej.

### API REST

W przestrzeni nazw `df-push/v1` wtyczka udostępnia publiczną trasę wysyłki zabezpieczoną tokenem: `POST /wp-json/df-push/v1/send` z nagłówkiem `X-DF-Push-Token`. Token można zregenerować jednym kliknięciem z panelu.

```
curl -X POST https://twoja-witryna.com/wp-json/df-push/v1/send
  -H "Content-Type: application/json"
  -H "X-DF-Push-Token: TWOJ_TOKEN"
  -d '{
    "title": "Flash sale",
    "body": "20 % na caly katalog do polnocy",
    "url": "https://twoja-witryna.com/promocje",
    "segment": { "lang": "pl", "topic": "promos" }
  }'
```

Traktuj ten token jak hasło. Każdy, kto go posiada, może wysyłać powiadomienia do Twoich subskrybentów. Zregeneruj go natychmiast przy podejrzeniu kompromitacji.

## Inbox in-site, PWA i wielojęzyczność

Trzy funkcje uzupełniające obejmują przypadki, gdy użytkownik nie zezwolił na Push.

- **Inbox in-site**: pływający dzwonek (konfigurowalny na froncie) otwiera listę ostatnich powiadomień użytkownika, przeczytanych lub nie, nawet jeśli nigdy nie zezwolił na Push. Szczególnie przydatne dla iOS Safari sprzed 16.4 i użytkowników PWA.
- **Manifest PWA**: generowany dynamicznie pod `/df-push-manifest.json` na podstawie `site_icon` albo własnej ikony. Dostępny filtr `df_push_manifest` do dostrojenia theme color, display, scope, start_url.
- **Wielojęzyczność**: zgodność z Polylang i WPML. Powiadomienia są wysyłane w języku subskrybenta (wykrytym przy opt-in), z fallbackiem na język domyślny witryny. Pliki `.po` i `.mo` w FR, EN, ES, DE, IT w komplecie.

## Service Worker i architektura techniczna

Service Worker jest serwowany przez samodzielny plik PHP pod adresem `/wp-content/plugins/df-push/sw.php`. To podejście całkowicie omija routing WordPressa: zero ryzyka interferencji z wtyczką cache, canonical redirectem czy innym handlerem `template_redirect`.

W odpowiedzi wysyłany jest nagłówek `Service-Worker-Allowed: /`, pozwalający na rejestrację z zakresem głównym (`scope: '/'`), mimo że skrypt żyje pod `/wp-content/`.

Po stronie bazy danych osiem tabel z prefiksem `dfpush_`:

- `dfpush_subscribers`: subskrybenci i ich endpoint Push.
- `dfpush_topic_subs`: przypisania temat ↔ subskrybent.
- `dfpush_campaigns`: kampanie ręczne z payloadem, segmentem i harmonogramem.
- `dfpush_notifications`: dziennik pojedynczych wysłanych powiadomień.
- `dfpush_events`: surowe zdarzenia (opt-in, sent, delivered, clicked, converted) na potrzeby analityki.
- `dfpush_inbox`: trwała kopia powiadomień dla inboxa in-site.
- `dfpush_stock_waitlist`: listy oczekujących na powrót do magazynu.
- `dfpush_consent_log`: rejestr RODO.

**Deinstalacja** (pełne usunięcie z ekranu Wtyczki) usuwa te osiem tabel i czyści wszystkie opcje. Sama dezaktywacja zachowuje dane na wypadek ponownej aktywacji.

## Hooki dla deweloperów

Wtyczka udostępnia akcje i filtry w kluczowych punktach, aby rozszerzać jej działanie bez modyfikowania rdzenia.

- `df_push_booted` (akcja): wyzwalana po starcie wtyczki, przydatna do rejestrowania własnych rozszerzeń.
- `df_push_payload_build` (filtr): modyfikacja payloadu JSON wysyłanego do push service przed szyfrowaniem.
- `df_push_should_send` (filtr): pomijanie wysyłki według własnych warunków (zwróć _false_, aby pominąć).
- `df_push_segment_query` (filtr): wzbogacanie kryteriów segmentacji behawioralnej.
- `df_push_webhook_payload` (filtr): dostrajanie payloadów webhooków wychodzących.
- `df_push_manifest` (filtr): modyfikacja generowanego manifestu PWA.
- Zarejestrowane akcje Action Schedulera: `df_push_send_one`, `df_push_fan_out`, `df_push_abandoned_cart`, `df_push_review_request`, `df_push_dispatch_campaign`.

## FAQ i rozwiązywanie problemów

### Prompt opt-in się nie pojawia

Trzy możliwe przyczyny: zgoda przeglądarki jest już odrzucona (sprawdź ustawienia przeglądarki), zgoda jest już udzielona (prompt nie ma już racji bytu), albo wyzwalacz nie został osiągnięty (nie upłynęło opóźnienie, za mały scroll). W konsoli JavaScript wykonaj `window.DFPush.isSubscribed()`, aby sprawdzić bieżący stan.

### Lista Subskrybenci jest pusta, mimo że opt-in się udał

Sprawdź w konsoli sieciowej, czy żądanie `POST /wp-json/df-push/v1/subscribe` zwraca kod 200. Od wersji 1.0.1 wtyczka przy każdym ładowaniu strony automatycznie resynchronizuje z serwerem każdą istniejącą `PushSubscription` i loguje błędy zapisu do bazy w `error_log`.

### Service Worker zwraca błąd rejestracji

Jeśli przeglądarka zgłasza „The script resource is behind a redirect" albo „Unexpected token '<'", przetestuj bezpośrednio adres `https://twoja-witryna.com/wp-content/plugins/df-push/sw.php`. Powinieneś zobaczyć kod JavaScript Service Workera z `Content-Type: application/javascript` i nagłówkiem `Service-Worker-Allowed: /`. Jeśli widzisz HTML 403, sprawdź reguły htaccess, które mogą blokować bezpośrednie wykonywanie plików PHP pod `wp-content/plugins/`.

### Powiadomienia nie docierają na iOS

Safari na iOS obsługuje powiadomienia Push dopiero od wersji 16.4 i wyłącznie dla witryn zainstalowanych jako PWA przez przycisk **Dodaj do ekranu początkowego**. Generowany przez wtyczkę manifest PWA ułatwia tę instalację. Jeśli nie celujesz specjalnie w iOS, to nie problem: pozostałe przeglądarki otrzymują powiadomienia normalnie.

### Jak zmigrować z OneSignal lub Pushera

Subskrybenci istniejący w tych usługach zewnętrznych nie są przenośni: kryptografia Push wiąże każdą subskrypcję z unikalną parą (klucz VAPID serwera, endpoint przeglądarki). Twoi odwiedzający będą musieli zasubskrybować się ponownie po przejściu na DataFirefly Push. Możesz przygotować przejście, wyłączając stare SDK kilka dni wcześniej i komunikując nową usługę banerem zapowiadającym.

### Co się dzieje przy deinstalacji?

Sama **dezaktywacja** zachowuje wszystkie tabele i opcje: możesz ponownie włączyć wtyczkę i kontynuować od miejsca, w którym skończyłeś. **Pełne usunięcie** z ekranu Wtyczki wykonuje `uninstall.php`, który usuwa osiem tabel `dfpush_`, czyści wszystkie opcje wtyczki (łącznie z kluczami VAPID i tokenem API) i wyrejestrowuje crony. Permalinki są automatycznie flushowane przy następnym żądaniu.