# DfPwaPush — Vollständiger Leitfaden

> DfPwaPush vereint zwei Funktionen in einem einzigen Shopware-Plugin: Es verwandelt Ihre Storefront in eine installierbare Progressive Web App (Manifest, Service Worker, Offline-Seite, Installations-Banner) und ermöglicht Ihnen, Ihre Kunden mit vollständig…

- Seite: <https://www.datafirefly.com/de/documentation/dfpwapush/>
- Sprache: de
- Aktualisiert am: 2026-06-17
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dfpwapush/index.md), [en](https://www.datafirefly.com/en/documentation/dfpwapush/index.md), [es](https://www.datafirefly.com/es/documentation/dfpwapush/index.md), [it](https://www.datafirefly.com/it/documentation/dfpwapush/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfpwapush/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfpwapush/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfpwapush/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

DfPwaPush vereint zwei Funktionen in einem einzigen Shopware-Plugin: Es verwandelt Ihre Storefront in eine **installierbare Progressive Web App** (Manifest, Service Worker, Offline-Seite, Installations-Banner) und ermöglicht Ihnen, Ihre Kunden mit vollständig selbst gehosteten **Web-Push-Benachrichtigungen** zu reaktivieren. Kein Drittanbieter-Dienst (kein Firebase, kein OneSignal), keine Composer-Abhängigkeit: Die Web-Push-Verschlüsselung (RFC 8291) und die VAPID-Signatur (RFC 8292) sind nativ mit den von Shopware ohnehin verlangten Erweiterungen OpenSSL und cURL implementiert. Alle Abonnementdaten bleiben auf Ihrem Server. Dieser Leitfaden behandelt Installation, PWA- und Push-Konfiguration, VAPID-Schlüsselgenerierung, Erstellung und Versand von Kampagnen, Hintergrundausführung und Fehlerbehebung.

## Installation

1. Laden Sie das Archiv `DfPwaPush-1.0.2.zip` aus Ihrem DataFirefly-Konto herunter.
2. Installieren Sie es über **Administration → Erweiterungen → Meine Erweiterungen → Erweiterung hochladen**, oder kopieren Sie den entpackten Ordner `DfPwaPush` nach `custom/plugins/`.
3. Führen Sie Installation und Aktivierung aus: ``` bin/console plugin:refresh bin/console plugin:install --activate DfPwaPush bin/console cache:clear ```
4. Bei der Installation erstellt das Plugin seine beiden Tabellen (`df_push_subscription` und `df_push_campaign`) und registriert seine Versand-ScheduledTask.

Kompatibel mit Shopware 6.5.x, 6.6.x und 6.7.x auf einer einzigen Codebasis. Das Administrationsmodul wird **vorkompiliert** ausgeliefert und das Storefront-JavaScript wird per Twig eingebunden: **Es ist kein Build erforderlich**, weder `build-administration.sh` noch ein Storefront-Build. Erforderliche PHP-Erweiterungen: `openssl` und `curl`, beide von Shopware ohnehin verlangt. Keine zusätzliche Composer-Abhängigkeit.

## HTTPS-Voraussetzung

Service Worker und die Web-Push-API existieren nur auf einem sicheren Origin. Ihr Shop **muss** über HTTPS ausgeliefert werden (nur `localhost` ist in der Entwicklung eine Ausnahme). In einem HTTP-Shop bleibt das Plugin im Frontend stumm und protokolliert dies in der Browser-Konsole.

## Wo Sie das Plugin in der Administration finden

Nach der Aktivierung erscheint ein Eintrag **Push-Kampagnen** im Menü **Marketing** der Administration. Dort erstellen, planen und verfolgen Sie Ihre Kampagnen. Die gesamte PWA- und Push-Konfiguration erfolgt in der Plugin-Konfiguration, pro Verkaufskanal, über **Erweiterungen → Meine Erweiterungen → DfPwaPush → ⋯ → Konfigurieren**.

Falls der Menüeintrag nach einem Update nicht erscheint, führen Sie `bin/console assets:install && bin/console cache:clear` aus und laden die Administration mit erzwungenem Cache neu (Strg+Umschalt+R).

## Generierung der VAPID-Schlüssel

Web Push beruht auf einem VAPID-Schlüsselpaar (Standard RFC 8292), das Ihren Server gegenüber den Push-Diensten der Browser authentifiziert. Generieren Sie sie mit einem Befehl:

```
bin/console df:pwa-push:vapid:generate
```

Die Schlüssel werden direkt in die Plugin-Konfiguration geschrieben. Verwenden Sie die Option `--force`, um sie zu regenerieren. Sie können auch vorhandene VAPID-Schlüssel in die Konfigurationsfelder einfügen.

Das Regenerieren der VAPID-Schlüssel **macht alle bestehenden Abonnements ungültig**: Bereits abonnierte Browser erhalten keine Benachrichtigungen mehr und müssen sich erneut abonnieren. Tun Sie dies nur bewusst.

## PWA-Konfiguration

Die Karte **PWA** in der Konfiguration (pro Verkaufskanal einstellbar) steuert die Installierbarkeit Ihres Shops:

- **PWA aktivieren**: liefert das Manifest und den Service Worker aus.
- **App-Name und Kurzname**: auf dem Startbildschirm nach der Installation angezeigt.
- **Themenfarbe / Hintergrundfarbe**: standardmäßig `#0f172a` für das Thema.
- **Anzeigemodus**: `standalone`, `minimal-ui`, `fullscreen` oder `browser`.
- **Icons 192 px und 512 px**: PNG-Uploads, **unverzichtbar** für die Installierbarkeit.
- **Installations-Banner**: aktiviert die Aufforderung „Zum Startbildschirm hinzufügen“.

Ohne die beiden Icons 192 px und 512 px betrachtet Chrome die Website nicht als installierbar und das Installations-Banner erscheint nie. Das ist die häufigste Ursache für eine PWA, die im Frontend „nichts tut“.

## Push-Konfiguration

Die Karte **Push** steuert die Benachrichtigungen:

- **Web Push aktivieren**: aktiviert das Opt-in-Banner und die Subscription-Endpunkte. Standardmäßig aktiviert.
- **Öffentlicher / privater VAPID-Schlüssel**: vom obigen Befehl generiert.
- **VAPID-Subject**: eine `mailto:`-Adresse oder die URL Ihrer Website.
- **Opt-in-Verzögerung**: Anzahl der Sekunden, bevor das Berechtigungs-Banner erscheint (standardmäßig 8).

## Der Service Worker und die Storefront-Endpunkte

Alle PWA-Ressourcen werden dynamisch von einem Controller ausgeliefert, was sie immun gegen den Wechsel von webpack zu Vite in 6.7 macht:

- `GET /df-pwa/manifest.json` — das PWA-Manifest, pro Verkaufskanal generiert.
- `GET /df-pwa/sw.js` — der Service Worker (Header `Service-Worker-Allowed: /`, um den gesamten Origin zu steuern).
- `GET /df-pwa/icon/{192|512}` — die PWA-Icons.
- `GET /df-pwa/offline` — die Offline-Ersatzseite, vom Service Worker gecacht.
- `POST /df-pwa/subscribe` und `POST /df-pwa/unsubscribe` — Speichern und Entfernen eines Abonnements (XHR).

Der Service Worker cacht die Offline-Seite bei der Installation, liefert einen Ersatz für fehlgeschlagene Navigationen und zeigt empfangene Benachrichtigungen über das `push`-Ereignis mit Klick-Weiterleitung zur Kampagnen-URL an.

## Eine Kampagne erstellen und versenden

1. Gehen Sie zu **Marketing → Push-Kampagnen → Kampagne erstellen**.
2. Füllen Sie Titel, Nachricht und optional eine Ziel-URL und ein Icon aus.
3. Beschränken Sie die Kampagne bei Bedarf auf einen Verkaufskanal (andernfalls werden alle Abonnenten angesprochen).
4. Legen Sie entweder ein **geplantes Datum** fest und speichern, oder klicken Sie auf **Jetzt senden**.

„Jetzt senden“ stellt die Kampagne sofort in die Warteschlange (Status `scheduled` mit einem Sendedatum zum aktuellen Zeitpunkt); die geplante Aufgabe übernimmt sie innerhalb weniger Minuten. Eine Kampagne durchläuft die Status `draft` → `scheduled` → `sending` → `sent` (oder `failed`), und die Seite zeigt die Zähler für erfolgreiche und fehlgeschlagene Sendungen an.

## Hintergrundversand: ScheduledTask und CLI

Der Kampagnenversand wird von der ScheduledTask `df_pwa_push.send_campaigns` übernommen, die alle 300 Sekunden läuft. Sie holt fällige geplante Kampagnen und versendet sie in Stapeln. Sie können den Versand auch manuell auslösen:

```
bin/console df:pwa-push:send
```

Wie jede Shopware-ScheduledTask hängt der Versand von einem aktiven Worker ab. Stellen Sie sicher, dass ein Messenger-Consumer läuft (`bin/console messenger:consume`) oder dass der Shopware-Scheduler regelmäßig ausgelöst wird, sonst gehen geplante Kampagnen nicht raus.

## Natives Web Push, keine Abhängigkeit

DfPwaPush implementiert den kompletten Web-Push-Stack in reinem PHP, ohne externe Bibliothek:

- **VAPID / ES256** (RFC 8292): P-256-Schlüsselgenerierung über OpenSSL und ES256-JWT-Signatur zur Authentifizierung des Servers.
- **aes128gcm-Verschlüsselung** (RFC 8291): ephemeres ECDH, HKDF-Ableitung und AES-128-GCM-Verschlüsselung der Nachricht für jeden Abonnenten.
- **Paralleler Versand** per `curl_multi` in Stapeln, mit Behandlung der Rückgabecodes der Push-Dienste.

Die Implementierung wird Byte für Byte gegen den offiziellen Testvektor des RFC 8291 validiert, was die Interoperabilität mit Chrome, Firefox, Edge und Safari garantiert.

## Automatische Bereinigung der Abonnements

Wenn ein Push-Dienst meldet, dass ein Abonnement nicht mehr existiert (HTTP-Codes 404 oder 410), wird das entsprechende Abonnement automatisch deaktiviert. Abonnements, die wiederholt fehlschlagen (5 aufeinanderfolgende Fehlversuche), werden ebenfalls deaktiviert. Ihre Abonnentenbasis bleibt ohne Eingriff sauber.

## iOS- und Safari-Kompatibilität

Auf iOS erfordert Web Push **iOS 16.4 oder höher** _und_ die Installation der PWA auf dem Startbildschirm: Safari liefert keine Push-Benachrichtigungen an einen einfachen Tab. Das Plugin behandelt diesen Fall sauber — das Opt-in-Banner erscheint nur, wenn die Push-API tatsächlich verfügbar ist, sodass Ihren iOS-Besuchern kein falsches Versprechen gemacht wird.

## FAQ und Fehlerbehebung

**Die ZIP-Installation schlägt mit „Paket minishlink/web-push fehlt“ fehl.** Dieser Fehler betraf frühere Versionen. Seit 1.0.1 ist Web Push nativ und das Plugin hat keine Composer-Abhängigkeit mehr: Die aktuelle Version lässt sich auf jedem Hosting installieren, auch auf Shared Hosting.

**Im Backend erscheint nichts zum Erstellen von Kampagnen.** Das Administrationsmodul ist seit 1.0.1 vorkompiliert. Führen Sie nach einem Update `bin/console assets:install && bin/console cache:clear` aus und laden die Administration mit erzwungenem Cache neu (Strg+Umschalt+R). Der Eintrag befindet sich unter **Marketing → Push-Kampagnen**.

**Die URL /df-pwa/manifest.json liefert einen 500-Fehler.** Behoben in 1.0.2: Die Methode `setTwig()` des übergeordneten Controllers wurde in Shopware 6.7 entfernt, wodurch alle `/df-pwa/*`-Routen fehlschlugen. Aktualisieren Sie auf 1.0.2 oder höher.

**Im Storefront passiert nichts.** Öffnen Sie die Browser-Konsole: Das Plugin protokolliert jede Entscheidung mit dem Präfix `[DfPwaPush]` (Service Worker registriert oder nicht, fehlender VAPID-Schlüssel, Berechtigung verweigert, iOS ohne installierte PWA…). Prüfen Sie auch, ob der Shop auf HTTPS läuft.

**Das PWA-Installations-Banner erscheint nicht.** Chrome löst das Ereignis `beforeinstallprompt` nur aus, wenn die Website installierbar ist, was die in der Konfiguration gesetzten Icons 192 px und 512 px und einen aktiven Service Worker erfordert. Keine Icons, kein Banner.

**Das Benachrichtigungs-Banner erscheint nicht.** Prüfen Sie, ob die VAPID-Schlüssel generiert sind, ob Web Push aktiviert ist und ob der Benutzer Benachrichtigungen nicht bereits abgelehnt hat. Die Konsole zeigt den genauen Grund.

**Was geschieht bei der Deinstallation?** Mit der Option zur Datenlöschung werden die Tabellen `df_push_subscription` und `df_push_campaign` entfernt. Ohne diese Option bleiben sie erhalten, um Ihre Abonnenten und den Kampagnenverlauf zu bewahren.