SW Shopware 6 Intermediate

DfPwaPush — Complete Guide

Turn your Shopware shop into an installable PWA and send self-hosted Web Push notifications (VAPID, no Firebase, no Composer dependency) for Shopware 6.5, 6.6 and 6.7.

Updated Module version 1.0.2

DfPwaPush combines two functions in a single Shopware plugin: it turns your storefront into an installable Progressive Web App (manifest, service worker, offline page, install banner) and lets you re-engage your customers with Web Push notifications that are fully self-hosted. No third-party service (no Firebase, no OneSignal), no Composer dependency: Web Push encryption (RFC 8291) and VAPID signing (RFC 8292) are implemented natively with the OpenSSL and cURL extensions already required by Shopware. All subscription data stays on your server. This guide covers installation, PWA and Push configuration, VAPID key generation, creating and sending campaigns, background execution and troubleshooting.

Installation

  1. Download the DfPwaPush-1.0.2.zip archive from your DataFirefly account.
  2. Install it via Administration → Extensions → My extensions → Upload extension, or copy the unzipped DfPwaPush folder into custom/plugins/.
  3. Run the installation and activation: 
    bin/console plugin:refresh
bin/console plugin:install --activate DfPwaPush
bin/console cache:clear
  4. On installation, the plugin creates its two tables (df_push_subscription and df_push_campaign) and registers its sending ScheduledTask.

Compatible with Shopware 6.5.x, 6.6.x and 6.7.x on a single codebase. The administration module ships precompiled and the storefront JavaScript is injected via Twig: no build is required, neither build-administration.sh nor a storefront build. Required PHP extensions: openssl and curl, both already required by Shopware. No additional Composer dependency.

HTTPS requirement

Service workers and the Web Push API only exist on a secure origin. Your shop must be served over HTTPS (only localhost is an exception in development). On an HTTP shop, the plugin stays silent on the front and logs it in the browser console.

Where to find the plugin in the administration

After activation, a Push campaigns entry appears in the Marketing menu of the administration. That is where you create, schedule and track your campaigns. All PWA and Push configuration is done in the plugin configuration, per sales channel, via Extensions → My extensions → DfPwaPush → ⋯ → Configure.

If the menu entry does not appear after an update, run bin/console assets:install && bin/console cache:clear then reload the administration with a forced refresh (Ctrl+Shift+R).

Generating the VAPID keys

Web Push relies on a VAPID key pair (the RFC 8292 standard) that authenticates your server to the browsers’ push services. Generate them with one command:

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

The keys are written directly into the plugin configuration. Use the --force option to regenerate them. You can also paste existing VAPID keys into the configuration fields.

Regenerating the VAPID keys invalidates all existing subscriptions: already-subscribed browsers will no longer receive notifications and will have to re-subscribe. Only do this knowingly.

PWA configuration

The PWA card in the configuration (adjustable per sales channel) drives your shop’s installability:

  • Enable PWA: serves the manifest and the service worker.
  • App name and short name: shown on the home screen once installed.
  • Theme color / background color: defaults to #0f172a for the theme.
  • Display mode: standalone, minimal-ui, fullscreen or browser.
  • 192 px and 512 px icons: PNG uploads, essential for installability.
  • Install banner: enables the “Add to Home Screen” prompt.

Without both the 192 px and 512 px icons set, Chrome does not consider the site installable and the install banner will never appear. This is the number-one cause of a PWA that “does nothing” on the front.

Push configuration

The Push card controls notifications:

  • Enable Web Push: activates the opt-in banner and the subscription endpoints. Enabled by default.
  • VAPID public / private key: generated by the command above.
  • VAPID subject: a mailto: address or your site URL.
  • Opt-in delay: the number of seconds before the permission banner appears (8 by default).

The service worker and storefront endpoints

All PWA resources are served dynamically by a controller, which makes them immune to the webpack-to-Vite switch in 6.7:

  • GET /df-pwa/manifest.json — the PWA manifest, generated per sales channel.
  • GET /df-pwa/sw.js — the service worker (with the Service-Worker-Allowed: / header to control the whole origin).
  • GET /df-pwa/icon/{192|512} — the PWA icons.
  • GET /df-pwa/offline — the offline fallback page, cached by the service worker.
  • POST /df-pwa/subscribe and POST /df-pwa/unsubscribe — saving and removing a subscription (XHR).

The service worker caches the offline page on installation, serves a fallback for failed navigations, and shows received notifications via the push event with a click-through to the campaign URL.

Creating and sending a campaign

  1. Go to Marketing → Push campaigns → Add campaign.
  2. Fill in the title, the message, and optionally a target URL and an icon.
  3. Restrict the campaign to a sales channel if needed (otherwise all subscribers are targeted).
  4. Either set a scheduled date and save, or click Send now.

“Send now” queues the campaign immediately (status scheduled with a send date set to the present moment); the scheduled task picks it up within minutes. A campaign goes through the statuses draft → scheduled → sending → sent (or failed), and the page shows the sent and failed counters.

Background sending: ScheduledTask and CLI

Campaign sending is handled by the df_pwa_push.send_campaigns ScheduledTask, run every 300 seconds. It picks up due scheduled campaigns and sends them in batches. You can also trigger sending manually:

bin/console df:pwa-push:send

Like any Shopware ScheduledTask, sending depends on an active worker. Make sure a Messenger consumer is running (bin/console messenger:consume) or that the Shopware scheduler is triggered regularly, otherwise scheduled campaigns will not go out.

Native Web Push, no dependency

DfPwaPush implements the complete Web Push stack in pure PHP, with no external library:

  • VAPID / ES256 (RFC 8292): P-256 key generation via OpenSSL and ES256 JWT signing to authenticate the server.
  • aes128gcm encryption (RFC 8291): ephemeral ECDH, HKDF derivation and AES-128-GCM encryption of the message for each subscriber.
  • Parallel sending via curl_multi in batches, with handling of the push services’ return codes.

The implementation is validated byte for byte against the official RFC 8291 test vector, which guarantees interoperability with Chrome, Firefox, Edge and Safari.

Automatic subscription cleanup

When a push service replies that a subscription no longer exists (HTTP 404 or 410 codes), the corresponding subscription is deactivated automatically. Subscriptions that fail repeatedly (5 consecutive failures) are deactivated too. Your subscriber base stays clean without intervention.

iOS and Safari compatibility

On iOS, Web Push requires iOS 16.4 or higher and the PWA to be installed on the home screen: Safari does not deliver push notifications to a plain tab. The plugin handles this case properly — the opt-in banner only appears when the Push API is actually available, so no false promise is made to your iOS visitors.

FAQ and troubleshooting

ZIP installation fails with “package minishlink/web-push missing”. This error concerned earlier versions. Since 1.0.1, Web Push is native and the plugin no longer has any Composer dependency: the current version installs on any hosting, including shared hosting.

Nothing appears to create campaigns in the back office. The administration module is precompiled since 1.0.1. After an update, run bin/console assets:install && bin/console cache:clear and reload the administration with a forced cache refresh (Ctrl+Shift+R). The entry is under Marketing → Push campaigns.

The URL /df-pwa/manifest.json returns a 500 error. Fixed in 1.0.2: the parent controller’s setTwig() method was removed in Shopware 6.7, which made all /df-pwa/* routes fail. Update to 1.0.2 or later.

Nothing happens on the storefront. Open the browser console: the plugin logs every decision with the [DfPwaPush] prefix (service worker registered or not, missing VAPID key, permission denied, iOS without an installed PWA…). Also check that the shop is on HTTPS.

The PWA install banner does not appear. Chrome only emits the beforeinstallprompt event if the site is installable, which requires the 192 px and 512 px icons set in the configuration and an active service worker. No icons, no banner.

The notification banner does not appear. Check that the VAPID keys are generated, that Web Push is enabled, and that the user has not already denied notifications. The console will show the exact reason.

What happens on uninstall? With the data-removal option, the df_push_subscription and df_push_campaign tables are dropped. Without that option, they are kept to preserve your subscribers and campaign history.

Was this page helpful?

Still stuck? Contact support