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

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.

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.

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.

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.

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" }
  }'

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.