oPWA v1.0.0

Plugin constants

JS-side checks (live in browser)

PHP-side checklist

• Icons generated (192px and 512px URLs configured)
• Offline fallback URL set and the page exists in WordPress
• VAPID keys generated

Global caching strategies

Custom route builder

Add per-URL rules with regex patterns. Each row has:

• Pattern — JavaScript regex matched against request.url
• Strategy — one of 5 strategies
• TTL (seconds) — max age for cached entries (0 = no expiry)
• Max entries — cap on cache storage entries (0 = unlimited)

Custom routes are serialised to JSON in opwa_settings['custom_routes'].

Preset configurations

Other SW options

VAPID wizard

Push composer

Trigger types

Public JS API

JSwindow.opPWA.showBanner();  // Show install banner programmatically
window.opPWA.dismiss();     // Dismiss banner

Stat cards (all-time)

Performance

Analytics & Privacy

Advanced

Cache store names

Bumping sw_version causes the old caches to be deleted on the next SW activate event. Each strategy also supports maxAge (seconds) and maxEntries caps.

wp opwa clear-cache

Bumps sw_version by 1, forcing all clients to delete and re-create caches on next SW activation.

BASHwp opwa clear-cache
# Success: Cache cleared. New SW version: 4

wp opwa send-push

Send a push notification to all subscribers.

BASHwp opwa send-push --title="New post" --body="Check out our latest article" --url="https://site.com/post"
# Success: Done. Sent: 142 / Failed: 3 / Total: 145

wp opwa list-subscribers

BASHwp opwa list-subscribers
wp opwa list-subscribers --format=json
wp opwa list-subscribers --format=csv
# Columns: ID, Device, User ID, Subscribed, Endpoint (truncated)

wp opwa generate-icons

Generate all PWA icon sizes from a WordPress attachment ID. Must be PNG/JPG at least 512×512.

BASHwp opwa generate-icons 42
# Success: Icons generated: 72x72, 96x96, 128x128, 144x144, 152x152, 192x192, 384x384, 512x512, maskable

wp opwa generate-vapid

BASHwp opwa generate-vapid        # Prompts for confirmation
wp opwa generate-vapid --yes  # Skip confirmation
# Success: VAPID keys generated and saved.
# Public key: BFi2R7...

wp opwa status

Display a summary of current plugin configuration.

BASHwp opwa status

POST /wp-json/opwa/v1/beacon

Record an analytics event from the front-end.

JSON// Request body
{
  "event":     "page_view",
  "sw_active": true,
  "url":       "https://site.com/blog/"
}

// Response
{ "ok": true }

POST /wp-json/opwa/v1/subscribe

Register a push subscription endpoint.

JSON// Request body
{
  "endpoint": "https://fcm.googleapis.com/fcm/send/…",
  "keys": { "p256dh": "BN…", "auth": "zq…" }
}

// Response
{ "ok": true, "id": 17 }

POST /wp-json/opwa/v1/unsubscribe

Remove a push subscription.

JSON// Request body
{ "endpoint": "https://fcm.googleapis.com/fcm/send/…" }

// Response
{ "ok": true }

Filters

opwa_manifest_data

Modify the manifest array before it is JSON-encoded and served.

PHPadd_filter( 'opwa_manifest_data', function( array $manifest ): array {
    $manifest['categories'] = [ 'news', 'blog' ];
    $manifest['prefer_related_applications'] = false;
    return $manifest;
} );

opwa_service_worker_routes

Modify or extend the array of custom routes before the SW is generated.

PHPadd_filter( 'opwa_service_worker_routes', function( array $routes ): array {
    $routes[] = [
        'pattern'     => '/api/.*',
        'strategy'    => 'network-only',
        'max_age'     => 0,
        'max_entries' => 0,
    ];
    return $routes;
} );

opwa_sw_extra_code

Append raw JavaScript to the generated service worker.

PHPadd_filter( 'opwa_sw_extra_code', function( string $code ): string {
    $code .= "\nself.addEventListener('message', e => {
    if (e.data === 'MY_MSG') { /* … */ }
});";
    return $code;
} );

opwa_precache_urls

PHPadd_filter( 'opwa_precache_urls', function( array $urls ): array {
    $urls[] = home_url( '/offline-assets/hero.webp' );
    $urls[] = home_url( '/offline-assets/logo.svg' );
    return $urls;
} );

opwa_push_payload

Modify the push notification payload before it is encrypted and sent.

PHPadd_filter( 'opwa_push_payload', function( array $payload, object $subscriber ): array {
    if ( $subscriber->user_id ) {
        $payload['actions'] = [ [ 'action' => 'view', 'title' => 'View now' ] ];
    }
    return $payload;
}, 10, 2 );

opwa_analytics_beacon_data

PHPadd_filter( 'opwa_analytics_beacon_data', function( array $data ): array {
    // Strip URL to path-only for privacy
    if ( isset( $data['url'] ) ) {
        $data['url'] = parse_url( $data['url'], PHP_URL_PATH );
    }
    return $data;
} );

opwa_icon_sizes

PHPadd_filter( 'opwa_icon_sizes', function( array $sizes ): array {
    return array_filter( $sizes, fn( $s ) => in_array( $s, [ 192, 512 ], true ) );
} );

Actions

opwa_after_subscribe

Fires after a new push subscriber is successfully stored.

PHPadd_action( 'opwa_after_subscribe', function( int $subscriber_id, string $endpoint ): void {
    // e.g., send a welcome notification
}, 10, 2 );

opwa_after_push_send

Fires after a push campaign completes.

PHPadd_action( 'opwa_after_push_send', function( array $result, array $payload ): void {
    // $result = [ 'sent' => 140, 'failed' => 2, 'total' => 142 ]
    error_log( 'Push sent: ' . wp_json_encode( $result ) );
}, 10, 2 );

opwa_after_cache_clear

PHPadd_action( 'opwa_after_cache_clear', function( int $new_version ): void {
    do_action( 'my_plugin_purge_cdn' );
} );

opwa_on_activate

Fires after the plugin runs its full activation routine (tables created, defaults set).

PHPadd_action( 'opwa_on_activate', function(): void {
    // One-time setup for your own plugin
} );

opwa_subscribers

Unique index on MD5 hash of endpoint to prevent duplicates.

opwa_campaigns

opwa_analytics

One row per calendar date. Uses INSERT … ON DUPLICATE KEY UPDATE so concurrent requests safely increment counters.

Nonce protection

All admin AJAX endpoints verify wp_verify_nonce( $nonce, 'opwa_admin' ) and check current_user_can('manage_options') before processing.

Input sanitisation

VAPID private key storage

The VAPID private key PEM is stored in wp_options. Access requires the manage_options capability. If your site has untrusted admin users, consider encrypting the PEM at rest.

Push payload security

All push payloads are end-to-end encrypted (AES-128-GCM) before transmission. Only the subscriber's browser can decrypt the payload. The beacon endpoint writes aggregated counts only — no raw URL storage.

Service worker not registering

• Verify the site is served over HTTPS (or localhost).
• Check browser DevTools → Application → Service Workers for errors.
• Ensure no other plugin intercepts requests to /sw.js. The SW is served at init priority 1 via WordPress, not as a real file.
• If using a CDN, ensure /sw.js and /manifest.webmanifest are excluded from the CDN cache.

Push notifications not received

Icons not generating

• Verify the PHP GD extension is active: php -m | grep gd
• The source attachment must be at least 512×512 pixels.
• The wp-content/uploads/opwa-icons/ directory must be writable.

ECDH / encryption errors

• PHP < 8.1 requires the GMP extension for the P-256 fallback: php -m | grep gmp
• PHP 8.1+ uses openssl_pkey_derive() natively.
• OpenSSL must be compiled with EC curve support: openssl ecparam -list_curves | grep prime256v1

Other issues