PWA Storefront Pack

Kompletny przewodnik po instalacji, konfiguracji i użytkowaniu PWA Storefront Pack: wtyczki, która zamienia Twój sklep WooCommerce w instalowalną Progresywną Aplikację Webową, z trybem offline i natywnymi powiadomieniami push VAPID (bez Firebase, bez OneSignal, bez miesięcznego abonamentu).

Przegląd i zasada działania

PWA Storefront Pack dodaje do Twojego WooCommerce trzy niezależne, ale uzupełniające się elementy:

• Web App Manifest: klienci mogą zainstalować Twój sklep na ekranie głównym jak prawdziwą aplikację (ikona, ekran powitalny, tryb standalone bez paska adresu).
• Service Worker: inteligentny cache stron i zasobów, personalizowalna strona offline, automatyczne wykluczenia stref wrażliwych (koszyk, checkout, moje konto).
• Powiadomienia push VAPID: pełna implementacja protokołu Web Push w czystym PHP: ECDSA P-256, JWT ES256, szyfrowanie aes128gcm. Twój serwer rozmawia bezpośrednio z usługami push przeglądarek.

Wymagania

• WordPress 6.0 lub nowszy
• WooCommerce 7.0 lub nowszy
• PHP 7.4 lub nowszy z rozszerzeniem openssl (włączonym domyślnie u wszystkich hostingodawców)
• HTTPS obowiązkowo: przeglądarki odmawiają rejestracji Service Workera i obsługi push po HTTP (poza localhostem przy developmencie)

Instalacja

1. Pobierz archiwum pwa-storefront-pack.zip ze swojego konta DataFirefly.
2. W WordPressie przejdź do Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer.
3. Wybierz ZIP i kliknij Zainstaluj teraz, a następnie Włącz.
4. Przy aktywacji wtyczka tworzy trzy tabele SQL (wp_pwasp_subscriptions, wp_pwasp_push_log, wp_pwasp_stock_waitlist) i automatycznie generuje Twoją parę kluczy VAPID.
5. Przejdź do WooCommerce → PWA Storefront, aby skonfigurować wtyczkę.

Konfiguracja ogólna

Zakładka General zbiera tożsamość Twojej aplikacji:

• Enable PWA: główny przełącznik. Wyłącz, aby tymczasowo zdjąć manifest i Service Workera bez odinstalowywania wtyczki.
• App name: pełna nazwa wyświetlana przy instalacji i na ekranie powitalnym (np. „Mój Oficjalny Sklep”).
• Short name: krótka etykieta pod ikoną na ekranie głównym, zgodnie z konwencją Androida ograniczona do 12 znaków.
• Theme color: kolor paska adresu i przełącznika zadań (zalecany: Twój główny kolor marki).
• Background color: tło ekranu powitalnego podczas ładowania aplikacji (często białe albo bardzo jasne).

Adresy endpointów

Wtyczka serwuje dwa krytyczne endpointy:

• https://twoja-witryna.pl/pwasp-manifest.json: Web App Manifest
• https://twoja-witryna.pl/pwasp-service-worker.js: Service Worker

Manifest

Zakładka Manifest steruje zachowaniem zainstalowanej aplikacji:

• Display mode: domyślnie standalone (zalecane, doświadczenie zbliżone do aplikacji). Pozostałe opcje: fullscreen, minimal-ui, browser.
• Orientation: any, portrait albo landscape. Na urządzeniach mobilnych portrait jest zwykle najlepszy dla sklepów.
• Start URL: ścieżka, pod którą aplikacja otwiera się przy uruchomieniu. Domyślnie /. Możesz wskazać /shop, aby od razu otwierać katalog.
• Scope: zakres adresów kontrolowany przez aplikację. Zwykle /. Ograniczaj go tylko wtedy, gdy używasz PWA jedynie w podkatalogu.
• Categories: wskazówki dla webowych sklepów z aplikacjami (Chrome, Edge). Przykład: shopping,business.
• Shortcuts: włącz, aby wygenerować skróty Sklep / Koszyk / Moje konto dostępne po dłuższym przytrzymaniu ikony na ekranie głównym.

Ikony aplikacji

Zakładka Icons pozwala podpiąć ikony z biblioteki mediów WordPressa. Obsługiwanych jest pięć formatów:

• Ikona 192×192 (any purpose): obowiązkowa. Używana na Androidzie i w wynikach wyszukiwarki.
• Ikona 512×512 (any purpose): obowiązkowa. Ikona ekranu powitalnego przy uruchomieniu.
• Maskable 192×192: opcjonalna. Z wewnętrznym marginesem bezpieczeństwa 10 % pod adaptacyjne ikony Androida (kształty okrągłe, kwadratowe, kroplowe).
• Maskable 512×512: opcjonalna. Ta sama zasada dla ekranu powitalnego.
• Apple Touch Icon 180×180: dla iOS. Bez zaokrąglonych rogów (iOS dodaje je automatycznie).

Dopóki żadna ikona nie jest ustawiona, wtyczka używa dostarczonych ikon domyślnych (marka DataFirefly). Zastąp je przed wdrożeniem na produkcję.

Tryb offline i strategia cache

Zakładka Offline i Cache konfiguruje zachowanie Service Workera:

Strategie

• Network first (zalecane): przeglądarka próbuje sieci, a przy braku połączenia sięga po cache. Maksymalna świeżość cen i stanów magazynowych.
• Cache first: cache odpowiada natychmiast, a sieć aktualizuje w tle. Szybciej, ale może pokazać nieco nieaktualne ceny.

Strategie dotyczą wyłącznie stron HTML. Pozostałe typy zasobów mają stałe, optymalne strategie:

• CSS / JS / czcionki → cache-first (zmieniają się tylko przy aktualizacjach wersji)
• Obrazy produktów → stale-while-revalidate (natychmiastowe wyświetlenie z cache, odświeżenie w tle)

Zakres cache

Trzy pola wyboru pozwalają włączać i wyłączać cache per typ:

• Cache HTML pages: strony produktów, kategorii, strona główna, wpisy
• Cache CSS / JS / fonts: szkielet Twojego motywu
• Cache images: zdjęcia produktów, obrazy wpisów blogowych

Strona offline

Dwie opcje:

• Użyj ekranu domyślnego: minimalistyczny ekran wbudowany we wtyczkę (ikona, komunikat, przycisk Spróbuj ponownie), w kolorach Twojej marki.
• Użyj własnej strony: wybierz istniejącą stronę WordPressa. Zostanie wstępnie zapisana w cache przy instalacji Service Workera i serwowana przy braku sieci.

Baner instalacji

Zakładka Install Banner steruje promocją instalacji:

• Delay (page views): liczba odsłon przed wyświetleniem. Domyślnie 3: użytkownik wykazał minimalne zainteresowanie, a nie jest nagabywany od pierwszej wizyty.
• Banner title / text / CTA / Dismiss: w pełni personalizowalne teksty, tłumaczalne przez plik .pot.

Zachowanie:

• W Chrome, Edge, Operze i Samsung Internet: baner pojawia się, gdy przeglądarka zasygnalizuje, że witrynę można zainstalować (beforeinstallprompt). Kliknięcie CTA wyświetla natywne okno instalacji.
• W Safari na iOS: baner automatycznie pokazuje instrukcję „Dotknij Udostępnij, a następnie Do ekranu głównego” (Apple nie udostępnia API instalacji programistycznej).
• Zamknięcie zapamiętywane na 7 dni: jeśli użytkownik zamknie baner, nie pojawi się on ponownie przez tydzień.
• Automatyczne wykrywanie: jeśli aplikacja jest już zainstalowana (wykryty tryb standalone), baner nie jest wyświetlany.

Powiadomienia push: klucze VAPID

Powiadomienia push korzystają z protokołu VAPID (Voluntary Application Server Identification), standardu W3C. Przy aktywacji wtyczki automatycznie generowana jest para kluczy ECDSA P-256:

• Klucz publiczny: udostępniany przeglądarkom subskrybentów (przez JavaScript). 65 bajtów, kodowany base64url.
• Klucz prywatny: nigdy nieprzesyłany, służy do podpisywania każdej wysyłki. 32 bajty.

Zakładka Push Notifications pokazuje Twój klucz publiczny otwartym tekstem i liczbę aktywnych subskrypcji. Możesz go skopiować na potrzeby ewentualnych testów zewnętrznych.

Ponowne generowanie kluczy

Przycisk Regenerate keys generuje nową parę. Ta operacja jest destrukcyjna:

VAPID subject

Pole VAPID subject: adres kontaktowy w formacie mailto:ty@przyklad.pl albo https://przyklad.pl/kontakt. Niektóre usługi push (zwłaszcza Mozilla) używają go, aby skontaktować się z Tobą przy wykryciu nadużyć z Twojego serwera. Wstępnie wypełniane adresem e-mail administratora WordPressa.

Zapytanie o zgodę i RODO

Sekcja Opt-in prompt konfiguruje wstępne zapytanie wyświetlane przed natywnym oknem uprawnień:

• Show opt-in prompt: włącza własne wstępne zapytanie. Zalecane: samo okno natywne ma wysoki wskaźnik odmów i blokuje kolejne prośby na 30 dni.
• GDPR consent required: nigdy nie wyświetla natywnego okna bez wyraźnego kliknięcia użytkownika w Twoje CTA. Wymagane w Europie dla zgodności z RODO.
• Delay (seconds): opóźnienie przed wyświetleniem. Domyślnie 10 sekund: pozwól użytkownikowi rozejrzeć się przed prośbą o zgodę.
• Prompt title / text / CTA / Dismiss: w pełni personalizowalne teksty.

Automatyczne wyzwalacze

Wtyczka dostarcza trzy automatyzacje podpięte bezpośrednio pod hooki WooCommerce. Każdą można włączyć niezależnie.

Status zamówienia

Hook: woocommerce_order_status_changed.
Zalogowany klient (nie goście) otrzymuje powiadomienie przy każdej zmianie statusu swojego zamówienia. Tytuł: „Zamówienie #1042 zaktualizowane”. Treść: „Status: Wysłane”. Kliknięcie → strona śledzenia zamówienia.

Powiadomienie używa unikalnego tag per zamówienie (order-1042): kolejne aktualizacje zastępują poprzednią zamiast się nakładać.

Nowe zamówienie (administrator)

Hook: woocommerce_new_order.
Wszyscy użytkownicy z rolą administrator albo shop_manager zapisani do push otrzymują powiadomienie przy każdym nowym zamówieniu. Tytuł: „Nowe zamówienie”. Treść: „Zamówienie #1042: 189,00 €”. Kliknięcie → ekran edycji zamówienia.

Adres w administracji jest świadomy HPOS: jeśli Twój WooCommerce używa High-Performance Order Storage, link prowadzi do nowego schematu (admin.php?page=wc-orders). W przeciwnym razie do starego (post.php?post=X).

Powrót do magazynu

Hooki: woocommerce_product_set_stock i woocommerce_variation_set_stock.
Gdy produkt przechodzi z braku dostępności do stanu „w magazynie”, wtyczka wysyła powiadomienie wszystkim odwiedzającym, którzy zapisali się na jego listę oczekujących. Tytuł: „Znowu dostępne!”. Treść: „Skórzane sneakersy premium w limitowanej edycji są znowu dostępne”. W podglądzie zdjęcie produktu, jeśli jest dostępne.

Każdy wpis oznaczany jest znacznikiem notified_at po udanej wysyłce, aby uniknąć duplikatów przy wahaniach stanu magazynowego.

Kreator broadcastu

Menu: WooCommerce → PWA Broadcast. Interfejs do wysłania ręcznego powiadomienia do wszystkich aktywnych subskrybentów (kampanie marketingowe, ogłoszenia i podobne).

Pola:

• Title: tytuł powiadomienia (zalecane maksimum 100 znaków)
• Message: treść powiadomienia (zalecane maksimum 200 znaków)
• Open URL: strona, na którą trafia użytkownik po kliknięciu (domyślnie strona główna)
• Image URL: duży obraz wyświetlany w powiadomieniu (tylko Android, iOS go nie pokazuje)

Podgląd na żywo pokazuje po prawej stronie ekranu przybliżony wygląd powiadomienia.

Dwa przyciski:

• Send broadcast: wysyłka do wszystkich aktywnych subskrybentów (wymagane potwierdzenie)
• Send test to me: wysyłka wyłącznie do Twoich własnych subskrypcji. Przydatne do sprawdzenia wyglądu przed masową wysyłką.

Lista oczekujących na powrót do magazynu (API JavaScript)

Aby odwiedzający mogli zapisać się na listę oczekujących przy produkcie niedostępnym, wywołaj ze swojego motywu:

window.PWASP.addToWaitlist(productId)
  .then(result => {
    if (result.success) {
      alert('You will be notified as soon as it is back in stock!');
    }
  });

Zachowanie:

1. Jeśli użytkownik nie jest jeszcze zapisany do push, otwiera się natywne okno uprawnień.
2. Po zapisaniu subskrypcji po stronie serwera wpis trafia na listę oczekujących danego produktu.
3. Po wykryciu powrotu do magazynu push wysyłany jest automatycznie.

To API możesz wywołać z dowolnego własnego przycisku albo z hooka woocommerce_single_product_summary przez mu-plugin.

Pozostałe udostępniane API JS

// Subscribe manually (e.g. from a custom button)
window.PWASP.subscribePush();

// Unsubscribe ("Unsubscribe me" button)
window.PWASP.unsubscribePush();

REST API

Wtyczka udostępnia sześć endpointów w przestrzeni nazw pwasp/v1:

• POST /wp-json/pwasp/v1/subscribe: zapisuje subskrypcję. Ciało: obiekt PushSubscription z przeglądarki.
• POST /wp-json/pwasp/v1/unsubscribe: usuwa subskrypcję. Ciało: { endpoint: "..." }.
• POST /wp-json/pwasp/v1/test: wysyłka testowa do bieżącego użytkownika (wymagane uwierzytelnienie, zdolność manage_woocommerce).
• POST /wp-json/pwasp/v1/broadcast: wysyłka do wszystkich subskrybentów (wymagane uwierzytelnienie).
• POST /wp-json/pwasp/v1/regenerate-vapid: generuje klucze VAPID od nowa (wymagane uwierzytelnienie).
• POST /wp-json/pwasp/v1/waitlist: dodaje do listy oczekujących. Ciało: { subscription_id, product_id }.

Uwierzytelnianie: nonce WordPressa X-WP-Nonce przy endpointach publicznych, zdolność manage_woocommerce przy endpointach administracyjnych.

Zgodność i przypadki szczególne

HPOS (High-Performance Order Storage)

Wtyczka formalnie deklaruje WooCommerce zgodność z HPOS przez FeaturesUtil::declare_compatibility. Zaznaczone pole zobaczysz w WooCommerce → Ustawienia → Zaawansowane → Funkcje.

Wtyczki cache

Dodaj w swojej wtyczce cache następujące wykluczenia:

• /pwasp-manifest.json
• /pwasp-service-worker.js

Niektóre wtyczki (WP Rocket, LiteSpeed) oferują też opcję niecache’owania plików JavaScript oznaczonych jako Service Worker: włącz ją, jeśli jest dostępna.

iOS i Safari

Wsparcie według wersji:

• iOS 16.4 i nowszy: instalacja przez „Do ekranu głównego” i powiadomienia push (wyłącznie dla zainstalowanych PWA)
• iOS 15 do 16.3: instalacja możliwa, powiadomienia push niedostępne
• iOS 14 i starszy: instalacja możliwa, brak powiadomień

Na iOS push działa tylko wtedy, gdy użytkownik najpierw zainstalował PWA na ekranie głównym. To ograniczenie Apple, nie wtyczki.

Podkatalogi i multisite

Wtyczka działa przy WordPressie zainstalowanym w katalogu głównym (example.com) albo w podkatalogu (example.com/shop/). Endpointy rozwiązywane są dynamicznie przez home_url(). W trybie multisite włącz wtyczkę per witryna: każda będzie miała własną parę kluczy VAPID i własną bazę subskrybentów.

Rozwiązywanie problemów

„Service Worker nie jest zarejestrowany”

1. Sprawdź, czy Twoja witryna działa po HTTPS (https://, a nie http://).
2. Otwórz konsolę przeglądarki (F12 → zakładka Application → Service Workers). Czy jest tam komunikat błędu?
3. Sprawdź adres https://twoja-witryna.pl/pwasp-service-worker.js w osobnej karcie. Plik musi zwracać JavaScript, a nie stronę 404 ani stronę główną WordPressa.
4. Jeśli 404: przejdź do Ustawienia → Bezpośrednie odnośniki i kliknij Zapisz zmiany, aby odświeżyć reguły przepisywania.

„Powiadomienia nie docierają”

1. Sprawdź w WooCommerce → PWA Subscribers, czy Twoja subskrypcja jest wypisana i ma status active.
2. Użyj przycisku Send test to me w kreatorze broadcastu. Czy powiadomienie dociera?
3. Jeśli nie: okno uprawnień mogło zostać odrzucone. W Chrome: otwórz kłódkę w pasku adresu → Powiadomienia → Zezwól.
4. W Windowsie i macOS: sprawdź, czy Chrome albo Firefox nie działa w trybie „Nie przeszkadzać”.

„Ponowne wygenerowanie kluczy VAPID się nie powiodło”

Prawdopodobna przyczyna: rozszerzenie PHP openssl nie jest dostępne na Twoim hostingu albo generowanie kluczy ECDSA jest zablokowane. Sprawdź w pliku phpinfo.php, czy sekcja openssl jest obecna i czy krzywa prime256v1 jest wspierana. W razie potrzeby skontaktuj się z hostingodawcą.

Deinstalacja

Usunięcie przez Wtyczki → Zainstalowane wtyczki → Usuń:

• Trzy tabele SQL zostają usunięte
• Opcje wtyczki zostają usunięte
• Zaplanowane zadania cron zostają anulowane
• Ikony wgrane do biblioteki mediów pozostają (mogą przydać się gdzie indziej)

Wsparcie

W razie pytań albo nieprawidłowości załóż zgłoszenie ze swojego konta DataFirefly. Odpowiedź w ciągu 24 godzin roboczych.