PWA Push
Notifications

01 Overview

PWA Push Notifications by XaniaCode turns any WordPress installation into an installable Progressive Web App capable of sending rich, image-based push notifications to subscribers — even when the browser is closed.

The plugin implements the Web Push Protocol (RFC 8292) with VAPID authentication entirely server-side, requiring no third-party push service or external API account. Subscribers are stored locally in your database, and all cryptography is handled by the bundled xania-webpush library.

02 Requirements

Verify your hosting environment meets all of the following before installing:

03 Installation

Manual Upload (Recommended)

1. 1
   Upload the plugin folder

   Extract the ZIP and upload the pwa-push-notifications folder to your server at:

   /wp-content/plugins/pwa-push-notifications/

2. 2
   Activate through WordPress admin

   Go to Plugins → Installed Plugins, locate PWA Push Notifications, and click Activate. The plugin creates its subscriber database table automatically on activation.

3. 3
   Navigate to PWA Push in the sidebar

   A new top-level menu item — PWA Push — will appear in the WordPress admin sidebar.

4. 4
   Generate VAPID keys

   On the Dashboard screen, click Generate VAPID Keys. This is required before any subscription or notification will work. See Section 04 for details.

5. 5
   Activate your license (or start the trial)

   The 14-day trial starts automatically the first time you open the plugin's admin pages — no key required. For an active license, see Section 07.

6. 6
   Visit your site over HTTPS

   Front-end visitors will now see the install/subscribe banner. The service worker is registered and the PWA manifest is served automatically.

What the Plugin Installs

The activation routine creates:

Uninstalling

Deleting the plugin via Plugins → Delete triggers the bundled uninstall.php script, which removes the subscribers table and all plugin options from the database, leaving no orphan data behind.

04 VAPID Keys

VAPID (Voluntary Application Server Identification) is the authentication mechanism that proves to browser push services that push requests originate from your server. The plugin implements VAPID per RFC 8292 using P-256 / prime256v1 ECDSA key pairs.

Generating Keys

1. 1
   Go to PWA Push → Dashboard

   The VAPID status panel at the top of the dashboard shows whether keys are currently set.

2. 2
   Click "Generate VAPID Keys"

   The plugin generates a new P-256 ECDSA key pair using PHP's openssl extension and stores both the public key (base64url) and private PEM securely in the WordPress options table.

3. 3
   Set the VAPID subject

   The subject should be either a mailto: address or an https: URL identifying your organisation. This is embedded in VAPID JWT tokens and is visible to browser push services.

   Example subjects

   mailto:admin@example.com
   https://example.com

How Keys Are Used

The public key is embedded in the front-end JavaScript (pwaPush.publicKey) and passed to the browser's PushManager.subscribe() call as the applicationServerKey. The private key PEM is used server-side to sign JWT tokens attached to each push request.

05 General Settings

Navigate to PWA Push → Settings to configure all plugin options. Settings are grouped into tabs.

Frontend Behaviour

WooCommerce Integration

06 Appearance

The plugin ships with six admin theme presets selectable under Settings → Appearance. Themes are applied only to the plugin's own admin pages and do not affect the rest of the WordPress admin or the front end.

Custom Colour Variables

When the Custom theme is selected, you can set six CSS variables independently via the WordPress colour picker:

07 License

The plugin includes a license manager that gates the notification-sending functionality. VAPID key management and subscriber collection work regardless of license status.

Trial Period

A 14-day local trial starts automatically the first time you open any plugin admin page — no license key is required. During the trial you can send notifications and test all features.

Activating a License

1. 1
   Go to PWA Push → License

   The license screen shows current status, expiry, and trial remaining time.

2. 2
   Enter your license key and click Activate

   The plugin contacts xaniacode.com/api/v1/license/activate with your key and the current site URL to register the activation.

3. 3
   Confirmation

   On success the license status updates to Active and the notification composer becomes fully available.

Background Validation

A WP-Cron job runs daily to re-validate the license against the XaniaCode server. Transient server failures do not deactivate the plugin — the last known valid state is preserved until a definitive invalid response is received.

Deactivating a License

Click Deactivate on the License screen. This contacts xaniacode.com/api/v1/license/deactivate and frees the activation slot so you can move the license to another site.

08 Sending Notifications

Notifications can be sent manually from the Dashboard or programmatically via the PHP API. An active license or trial is required to send.

Manual Send (Dashboard)

The notification composer on the Dashboard page accepts the following fields:

Subscriber Segmentation

The Target field lets you send to subsets of your subscriber list:

Dead Endpoint Cleanup

When the push service returns HTTP 404 or 410 for a subscriber endpoint (meaning the subscription has expired or been revoked), the plugin automatically removes that subscriber from the database. This keeps your subscriber list clean without any manual intervention.

09 Subscribers

Navigate to PWA Push → Subscribers to view and manage all active push subscriptions.

Subscriber Data

Front-End Opt-In Flow

The plugin follows browser best-practice for permission requests:

1. 1
   Install banner appears

   A non-intrusive banner slides in offering to install the app and/or subscribe to notifications. The banner is dismissed and not shown again for 7 days if the user clicks "Not now".

2. 2
   User gesture triggers permission request

   Clicking "Install" or "Subscribe" counts as a user gesture, satisfying Chrome's requirement that permission prompts be triggered by user interaction.

3. 3
   Browser shows the native permission prompt

   If the user grants permission, the endpoint and keys are sent to the server via an AJAX call secured with a WordPress nonce.

10 WooCommerce Integration

When WooCommerce (≥ 8.0) is active and you enable the integration under Settings → WooCommerce, the plugin hooks into order lifecycle and stock events to dispatch push notifications automatically.

Supported Events

Guest Checkout Auto-Linking

When a guest completes checkout, the plugin checks whether their billing email matches a registered WordPress user. If a match is found within a 60-minute window and the IP addresses align, the subscription is automatically linked to that user account — ensuring customer-targeted notifications reach returning guests who then log in.

Admin Capability

Admin notifications are dispatched to all subscribers who have the capability set in wc_admin_capability. The default is manage_woocommerce, but you can change this to manage_options or edit_shop_orders depending on who should receive store alerts.

11 Diagnostic

Navigate to PWA Push → Diagnostic to run a comprehensive suite of environment and health checks. This page is essential for troubleshooting why push notifications may not be working.

Check Groups

Caching Conflicts

The diagnostic also detects common caching and optimisation plugins that might cache sw.js with the wrong headers or an incorrect Cache-Control value. Detected plugins include: WP Rocket, LiteSpeed Cache, W3 Total Cache, WP Super Cache, and others.

Exporting a Diagnostic Report

Click Export Diagnostic Report on the Diagnostic page to download a plain-text summary of all check results. Include this file when submitting a support ticket to XaniaCode.

=== XaniaCode PWA Push Notifications — Diagnostic Report ===
Generated: 2026-04-29 14:32:01
Plugin version: 1.0.0

--- ENVIRONMENT ---
✅  PHP version — 8.2.12
✅  OpenSSL extension — loaded
✅  HTTPS — secure context detected
⚠️  GMP extension — not loaded (bcmath fallback active)

--- CONFLICTS ---
✅  No competing PWA plugins detected
⚠️  WP Rocket active — ensure sw.js is excluded from caching

12 Developer API

The plugin exposes a clean PHP API on the XC_PWA_Notifications class for sending notifications from custom code — themes, other plugins, or WP-CLI scripts.

Accessing the Instance

$plugin        = XC_PWA_Plugin::instance();
$notifications = $plugin->notifications;
$subscribers   = $plugin->subscribers;

dispatch() — Send to a list of subscribers

The lowest-level dispatch method. Pass an array of subscriber rows from the database and a payload array:

$result = $notifications->dispatch(
    $subscribers,   // array of subscriber rows
    [
        'title' => 'Hello from my plugin',
        'body'  => 'Something interesting happened.',
        'icon'  => 'https://example.com/icon.png',
        'url'   => 'https://example.com/event/',
        'image' => 'https://example.com/hero.jpg', // optional
        'badge' => 'https://example.com/badge.png', // optional
    ]
);

// $result shape:
// [
//   'sent'     => int,
//   'failed'   => int,
//   'failures' => [ ['id'=>int, 'status'=>int, 'error'=>string], ... ],
//   'skipped'  => bool,  // true when license is inactive
// ]

send_to_user() — Send to a specific WordPress user

$notifications->send_to_user( $user_id, [
    'title' => 'Your report is ready',
    'body'  => 'Click to download.',
    'url'   => admin_url( 'admin.php?page=my-reports' ),
] );

send_to_capability() — Send to all users with a capability

$notifications->send_to_capability( 'manage_options', [
    'title' => 'Admin alert',
    'body'  => 'Disk usage has exceeded 90%.',
    'url'   => admin_url(),
] );

Custom WP-CLI Integration Example

// Send a notification from a custom WP-CLI command.
WP_CLI::add_command( 'pwa notify', function( $args ) {
    $plugin = XC_PWA_Plugin::instance();
    $subs   = $plugin->subscribers->get_by_target( 'all' );

    $result = $plugin->notifications->dispatch( $subs, [
        'title' => $args[0] ?? 'Test',
        'body'  => $args[1] ?? 'Hello from CLI',
        'url'   => home_url(),
    ] );

    WP_CLI::success( "Sent: {$result['sent']}  Failed: {$result['failed']}" );
} );

13 FAQ

14 Security

The plugin was designed with security as a first-class concern. Key measures: