PWA Storefront Pack

Vollständiger Leitfaden für Installation, Konfiguration und Nutzung von PWA Storefront Pack: das Plugin, das Ihren WooCommerce-Shop in eine installierbare Progressive Web App mit Offline-Modus und nativen VAPID-Push-Benachrichtigungen verwandelt (kein Firebase, kein OneSignal, kein monatliches Abo).

Überblick und Funktionsprinzip

PWA Storefront Pack fügt Ihrem WooCommerce drei unabhängige, aber komplementäre Bausteine hinzu:

• Web App Manifest — Ihre Kunden können Ihren Shop wie eine echte native App auf ihrem Home-Bildschirm installieren (Icon, Splash-Screen, Standalone-Modus ohne Adressleiste).
• Service Worker — intelligentes Caching von Seiten und Ressourcen, anpassbare Offline-Seite, automatische Ausschlüsse sensibler Bereiche (Warenkorb, Checkout, Mein Konto).
• VAPID-Push-Benachrichtigungen — vollständige Implementierung des Web-Push-Protokolls in reinem PHP: ECDSA P-256, JWT ES256, aes128gcm-Verschlüsselung. Ihr Server spricht direkt mit den Push-Diensten der Browser.

Voraussetzungen

• WordPress 6.0 oder höher
• WooCommerce 7.0 oder höher
• PHP 7.4 oder höher mit der Erweiterung openssl (standardmäßig auf allen Hosts aktiviert)
• HTTPS erforderlich — Browser lehnen die Registrierung eines Service Workers oder die Handhabung von Push-Benachrichtigungen über HTTP ab (außer auf localhost für die Entwicklung)

Installation

1. Laden Sie das Archiv pwa-storefront-pack.zip aus Ihrem DataFirefly-Konto herunter.
2. In WordPress gehen Sie zu Plugins → Installieren → Plugin hochladen.
3. Wählen Sie die ZIP-Datei aus und klicken Sie auf Jetzt installieren, dann Aktivieren.
4. Bei der Aktivierung erstellt das Plugin drei SQL-Tabellen (wp_pwasp_subscriptions, wp_pwasp_push_log, wp_pwasp_stock_waitlist) und generiert automatisch Ihr VAPID-Schlüsselpaar.
5. Gehen Sie zu WooCommerce → PWA Storefront, um zu konfigurieren.

Allgemeine Konfiguration

Der Tab General zentralisiert die Identität Ihrer App:

• Enable PWA — Hauptschalter. Deaktivieren Sie, um Manifest und Service Worker vorübergehend zu entfernen, ohne das Plugin zu deinstallieren.
• App name — vollständiger Name, der bei der Installation und auf dem Splash-Screen angezeigt wird (z. B. „Mein Offizieller Shop“).
• Short name — kurzer Bezeichner unter dem Home-Bildschirm-Icon, gemäß Android-Konvention auf 12 Zeichen begrenzt.
• Theme color — Farbe der Adressleiste und des Task-Switchers (empfohlen: Ihre primäre Markenfarbe).
• Background color — Hintergrund des Splash-Screens beim App-Laden (üblicherweise weiß oder sehr hell).

Endpoint-URLs

Das Plugin bedient zwei kritische Endpoints:

• https://ihre-seite.com/pwasp-manifest.json — das Web App Manifest
• https://ihre-seite.com/pwasp-service-worker.js — der Service Worker

Manifest

Der Tab Manifest steuert das Verhalten der installierten App:

• Display mode — standardmäßig standalone (empfohlen, App-ähnliches Erlebnis). Andere Optionen: fullscreen, minimal-ui, browser.
• Orientation — any, portrait oder landscape. Auf Mobilgeräten ist portrait für Shops oft am besten.
• Start URL — Pfad, an dem die App beim Start geöffnet wird. Standardmäßig /. Sie können auf /shop zeigen, um direkt den Katalog zu öffnen.
• Scope — von der App kontrollierter URL-Bereich. Meist /. Nur einschränken, wenn Sie die PWA nur in einem Unterordner verwenden.
• Categories — Hinweise für Web-App-Stores (Chrome, Edge). Beispiel: shopping,business.
• Shortcuts — aktivieren, um Shop / Warenkorb / Mein-Konto-Shortcuts zu generieren, die per Long-Press auf das Home-Bildschirm-Icon zugänglich sind.

App-Icons

Der Tab Icons ermöglicht die Zuordnung Ihrer Icons aus der WordPress-Mediathek. Fünf Formate werden verwaltet:

• Icon 192×192 (any purpose) — erforderlich. Wird auf Android und in Suchmaschinenergebnissen verwendet.
• Icon 512×512 (any purpose) — erforderlich. Splash-Screen-Icon beim Start.
• Maskable 192×192 — optional. Mit 10 % innerer Sicherheitszone für adaptive Android-Icons (runde, quadratische, tropfenförmige Formen).
• Maskable 512×512 — optional. Gleiches Prinzip für den Splash-Screen.
• Apple Touch Icon 180×180 — für iOS. Quadratisch, ohne abgerundete Ecken (iOS fügt sie automatisch hinzu).

Solange kein Icon konfiguriert ist, verwendet das Plugin mitgelieferte Standard-Icons (DataFirefly-Branding). Ersetzen Sie sie vor dem Produktivbetrieb.

Offline-Modus und Cache-Strategie

Der Tab Offline & Cache konfiguriert das Service-Worker-Verhalten:

Strategien

• Network first (empfohlen) — der Browser versucht das Netzwerk zuerst, dann greift er auf den Cache zurück, wenn offline. Maximale Frische von Preisen und Beständen.
• Cache first — der Cache antwortet sofort, das Netzwerk aktualisiert im Hintergrund. Schneller, kann aber leicht veraltete Preise anzeigen.

Strategien gelten nur für HTML-Seiten. Andere Ressourcentypen haben feste optimale Strategien:

• CSS / JS / Fonts → cache-first (sie ändern sich nur bei Versionsupdates)
• Produktbilder → stale-while-revalidate (sofortige Anzeige aus dem Cache, Refresh im Hintergrund)

Cache-Umfang

Drei Kontrollkästchen erlauben das Aktivieren/Deaktivieren des Caches pro Typ:

• Cache HTML pages — Produktseiten, Kategorie, Startseite, Beiträge
• Cache CSS / JS / fonts — das Grundgerüst Ihres Themes
• Cache images — Produktbilder, Blog-Beitragsbilder

Offline-Seite

Zwei Optionen:

• Standardbildschirm verwenden — minimalistischer, ins Plugin integrierter Bildschirm (Icon, Nachricht, Erneut-versuchen-Button) in Ihren Markenfarben.
• Benutzerdefinierte Seite verwenden — wählen Sie eine bestehende WordPress-Seite. Sie wird bei der Service-Worker-Installation vorgecacht und bei Netzwerkausfall bereitgestellt.

Installations-Banner

Der Tab Install Banner steuert die Installationsförderung:

• Delay (page views) — Anzahl der Seitenaufrufe vor der Anzeige. Standardmäßig 3: der Nutzer hat minimales Interesse gezeigt, ohne beim ersten Besuch belästigt zu werden.
• Banner title / text / CTA / Dismiss — vollständig anpassbare Texte, per .pot übersetzbar.

Verhalten:

• In Chrome, Edge, Opera, Samsung Internet: das Banner erscheint, wenn der Browser signalisiert, dass die Site installierbar ist (beforeinstallprompt). Ein Klick auf das CTA öffnet den nativen Installationsdialog.
• In iOS Safari: das Banner zeigt automatisch die Anweisung „Teilen antippen, dann Zum Home-Bildschirm“ (Apple bietet keine programmatische Installations-API).
• Ablehnung 7 Tage gemerkt — wenn der Nutzer das Banner schließt, erscheint es eine Woche lang nicht wieder.
• Automatische Erkennung — wenn die App bereits installiert ist (Standalone-Modus erkannt), wird das Banner nicht mehr angezeigt.

Push-Benachrichtigungen: die VAPID-Schlüssel

Push-Benachrichtigungen verwenden das VAPID-Protokoll (Voluntary Application Server Identification), einen W3C-Standard. Bei der Plugin-Aktivierung wird automatisch ein ECDSA-P-256-Schlüsselpaar generiert:

• Öffentlicher Schlüssel — mit den Browsern der Abonnenten geteilt (via JavaScript). 65 Bytes, base64url-codiert.
• Privater Schlüssel — wird nie übertragen, dient zum Signieren jeder Sendung. 32 Bytes.

Der Tab Push Notifications zeigt Ihren öffentlichen Schlüssel im Klartext und die Anzahl aktiver Abonnements. Sie können ihn für eventuelle externe Tests kopieren.

Schlüssel-Neugenerierung

Der Button Regenerate keys generiert ein neues Paar. Diese Operation ist destruktiv:

VAPID subject

VAPID subject-Feld: Kontaktadresse im Format mailto:sie@beispiel.com oder https://beispiel.com/kontakt. Einige Push-Dienste (insbesondere Mozilla) nutzen sie, um Sie bei erkanntem Missbrauch von Ihrem Server zu kontaktieren. Voreingestellt mit der WordPress-Admin-E-Mail.

Opt-in-Prompt und DSGVO

Der Abschnitt Opt-in prompt konfiguriert die vor dem nativen Berechtigungsdialog angezeigte Voraufforderung:

• Show opt-in prompt — aktiviert die angepasste Voraufforderung. Empfohlen: der native Dialog allein hat eine hohe Ablehnungsrate und blockiert jede neue Anfrage für 30 Tage.
• GDPR consent required — löst nie den nativen Dialog aus ohne expliziten Klick des Nutzers auf Ihr CTA. In Europa für DSGVO-Konformität erforderlich.
• Delay (seconds) — Wartezeit vor Anzeige. Standardmäßig 10 Sekunden: dem Nutzer Zeit lassen zu erkunden, bevor die Berechtigung angefragt wird.
• Prompt title / text / CTA / Dismiss — vollständig anpassbare Texte.

Automatische Trigger

Das Plugin liefert drei Automatisierungen, die direkt an WooCommerce-Hooks angebunden sind. Jede ist unabhängig aktivierbar.

Bestellstatus

Hook: woocommerce_order_status_changed.
Der identifizierte Kunde (nicht Gäste) erhält eine Benachrichtigung bei jedem Statusübergang seiner Bestellung. Titel: „Bestellung #1042 aktualisiert“. Text: „Status: Versendet“. Klick → Bestellverfolgungsseite.

Die Benachrichtigung verwendet ein eindeutiges tag pro Bestellung (order-1042): aufeinanderfolgende Updates ersetzen das vorherige, statt sich zu stapeln.

Neue Bestellung (Admin)

Hook: woocommerce_new_order.
Alle Benutzer mit der Rolle administrator oder shop_manager und Push-Abonnement erhalten eine Benachrichtigung bei jeder neuen Bestellung. Titel: „Neue Bestellung erhalten“. Text: „Bestellung #1042 — 189,00 €“. Klick → Bestellbearbeitungsbildschirm.

Die Admin-URL ist HPOS-aware: wenn Ihr WooCommerce High-Performance Order Storage nutzt, verweist der Link auf das neue Schema (admin.php?page=wc-orders). Sonst auf das alte (post.php?post=X).

Wieder auf Lager

Hooks: woocommerce_product_set_stock und woocommerce_variation_set_stock.
Wenn ein Produkt von „ausverkauft“ auf „auf Lager“ wechselt, sendet das Plugin eine Benachrichtigung an alle Besucher, die sich in seine Warteliste eingetragen hatten. Titel: „Wieder auf Lager!“. Text: „Sneakers Leder Premium Limited Edition ist wieder verfügbar“. Produktbild als Vorschau, falls verfügbar.

Jeder Eintrag wird nach erfolgreichem Versand als notified_at markiert, um Duplikate bei schwankendem Bestand zu vermeiden.

Broadcast-Composer

Menü: WooCommerce → PWA Broadcast. Oberfläche, um eine manuelle Benachrichtigung an alle aktiven Abonnenten zu senden (Marketing-Kampagnen, Ankündigungen, etc.).

Felder:

• Title — Titel der Benachrichtigung (max. 100 Zeichen empfohlen)
• Message — Text der Benachrichtigung (max. 200 Zeichen empfohlen)
• Open URL — Seite, auf der der Nutzer bei Klick landet (standardmäßig die Startseite)
• Image URL — großes Bild, das in der Benachrichtigung angezeigt wird (nur Android, iOS zeigt es nicht)

Eine Live-Vorschau zeigt eine ungefähre Darstellung der Benachrichtigung rechts auf dem Bildschirm.

Zwei Buttons:

• Send broadcast — Versand an alle aktiven Abonnenten (Bestätigung erforderlich)
• Send test to me — Versand nur an Ihre eigenen Abonnements. Nützlich, um die Darstellung vor einem Massen-Broadcast zu validieren.

Warteliste Wieder-auf-Lager (JavaScript-API)

Um Besuchern zu ermöglichen, sich in die Warteliste eines ausverkauften Produkts einzutragen, rufen Sie aus Ihrem Theme auf:

window.PWASP.addToWaitlist(productId)
  .then(result => {
    if (result.success) {
      alert('Sie werden benachrichtigt, sobald es wieder auf Lager ist!');
    }
  });

Verhalten:

1. Wenn der Nutzer noch nicht für Push abonniert ist, öffnet sich der native Berechtigungsdialog.
2. Sobald das Abonnement serverseitig registriert ist, wird der Eintrag zur Produkt-Warteliste hinzugefügt.
3. Bei erkanntem Wieder-auf-Lager wird automatisch ein Push gesendet.

Sie können diese API aus jedem benutzerdefinierten Button oder über ein Mu-Plugin, das an woocommerce_single_product_summary hakt, aufrufen.

Andere exponierte JS-APIs

// Manuell abonnieren (z. B. aus einem benutzerdefinierten Button)
window.PWASP.subscribePush();

// Abbestellen ("Mich abmelden"-Button)
window.PWASP.unsubscribePush();

REST-API

Das Plugin exponiert sechs Endpoints unter dem Namespace pwasp/v1:

• POST /wp-json/pwasp/v1/subscribe — registriert ein Abonnement. Body: Browser-PushSubscription-Objekt.
• POST /wp-json/pwasp/v1/unsubscribe — entfernt ein Abonnement. Body: { endpoint: "..." }.
• POST /wp-json/pwasp/v1/test — Testversand an den aktuellen Nutzer (Auth erforderlich, Capability manage_woocommerce).
• POST /wp-json/pwasp/v1/broadcast — Broadcast an alle Abonnenten (Auth erforderlich).
• POST /wp-json/pwasp/v1/regenerate-vapid — regeneriert die VAPID-Schlüssel (Auth erforderlich).
• POST /wp-json/pwasp/v1/waitlist — fügt zu einer Warteliste hinzu. Body: { subscription_id, product_id }.

Authentifizierung: WordPress-X-WP-Nonce für öffentliche Endpoints, Capability manage_woocommerce für Admin-Endpoints.

Kompatibilität und Sonderfälle

HPOS (High-Performance Order Storage)

Das Plugin deklariert seine HPOS-Kompatibilität formal an WooCommerce via FeaturesUtil::declare_compatibility. Sie sehen die Checkbox angehakt unter WooCommerce → Einstellungen → Erweitert → Funktionen.

Cache-Plugins

Fügen Sie die folgenden Ausschlüsse in Ihrem Cache-Plugin hinzu:

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

Einige Plugins (WP Rocket, LiteSpeed) bieten auch eine Option, Service-Worker-JavaScript-Dateien nicht zu cachen — aktivieren Sie sie, falls verfügbar.

iOS und Safari

Support nach Version:

• iOS 16.4 und höher — Installation via „Zum Home-Bildschirm“ und Push-Benachrichtigungen (nur für installierte PWAs)
• iOS 15 und 16.3 — Installation möglich, Push-Benachrichtigungen nicht verfügbar
• iOS 14 und darunter — Installation möglich, keine Benachrichtigungen

Auf iOS funktionieren Push-Benachrichtigungen nur, wenn der Nutzer die PWA zuerst auf seinem Home-Bildschirm installiert hat. Das ist eine Einschränkung von Apple, nicht des Plugins.

Unterordner und Multisite

Das Plugin funktioniert bei WordPress-Installation im Root (beispiel.com) oder in einem Unterordner (beispiel.com/shop/). Endpoints werden dynamisch über home_url() aufgelöst. In Multisite aktivieren Sie das Plugin pro Site — jede Site hat ihr eigenes VAPID-Schlüsselpaar und ihre eigene Abonnentenbasis.

Fehlerbehebung

„Der Service Worker ist nicht registriert“

1. Prüfen Sie, dass Ihre Site auf HTTPS läuft (https:// und nicht http://).
2. Öffnen Sie die Browser-Konsole (F12 → Tab Application → Service Workers). Gibt es eine Fehlermeldung?
3. Testen Sie die URL https://ihre-seite.com/pwasp-service-worker.js in einem Tab. Die Datei muss JavaScript zurückgeben, keine 404-Seite und nicht die WordPress-Startseite.
4. Bei 404: gehen Sie zu Einstellungen → Permalinks und klicken Sie auf Änderungen speichern, um die Rewrite-Regeln zu aktualisieren.

„Benachrichtigungen kommen nicht an“

1. Prüfen Sie unter WooCommerce → PWA Subscribers, dass Ihr Abonnement gelistet und im Status active ist.
2. Nutzen Sie den Button Send test to me im Broadcast-Composer. Erhalten Sie die Benachrichtigung?
3. Falls nicht: der Berechtigungsdialog wurde möglicherweise abgelehnt. In Chrome: öffnen Sie das Schloss in der Adressleiste → Benachrichtigungen → Zulassen.
4. Unter Windows/macOS: prüfen Sie, dass Chrome/Firefox nicht im „Nicht stören“-Modus ist.

„VAPID-Schlüssel-Regenerierung fehlgeschlagen“

Wahrscheinliche Ursache: die PHP-Erweiterung openssl ist auf Ihrem Hosting nicht verfügbar, oder die ECDSA-Schlüsselgenerierung ist blockiert. Prüfen Sie über eine phpinfo.php-Datei, dass der Abschnitt openssl vorhanden ist und die Kurve prime256v1 unterstützt wird. Kontaktieren Sie ggf. Ihren Hoster.

Deinstallation

Entfernen über Plugins → Installierte Plugins → Löschen:

• Die drei SQL-Tabellen werden gelöscht
• Plugin-Optionen werden entfernt
• Geplante Cron-Tasks werden abgebrochen
• In die Mediathek hochgeladene Icons bleiben (sie können anderswo verwendet werden)

Support

Für Fragen oder Störungen öffnen Sie ein Ticket aus Ihrem DataFirefly-Konto. Antwort innerhalb von 24 Arbeitsstunden.