Documentation

Requirements

• WordPress 5.8 or newer
• PHP 7.4 or newer, with the OpenSSL extension (nearly every host has it on)
• A site that runs on HTTPS. Browsers don't allow push notifications on plain HTTP, on any site.

You don't need Composer, an outside service, or an API key. The plugin creates its own encryption keys when you activate it.

Install and activate

Get the free plugin from the download page. If you bought Premium, use the download link in your Freemius purchase email.

1. In WordPress, go to Plugins, Add New Plugin, Upload Plugin.
2. Choose the zip file you downloaded, click Install Now, then Activate.
3. If you bought Premium, enter your license key when the activation screen asks for it.
4. Open Push Notifications in the left-hand admin menu.

Free and Premium are separate downloads. When you activate Premium, the Free version is switched off automatically, so you never run both.

Ask visitors to subscribe

Under Subscription prompt, pick a Prompt style:

You can also set the bell size and position, the popup size and position (eight positions each), the delay before the popup appears (5 seconds by default), and whether to ask again visitors who chose Later, how long to wait, and how many times.

Every piece of text is editable: the popup headline and description, the Allow and Later buttons, the thank-you card, and the three status messages (while connecting, if permission wasn't granted, and on an unexpected error).

Test your setup

1. Open your site in a normal browser window (not Incognito) on the exact address visitors use, with https://.
2. Wait for the popup, or click the bell, and choose Allow.
3. You should see the thank-you card, and the bell turns green. The subscriber count in the admin goes up by one.
4. Send yourself a test notification (next section).

If the popup doesn't appear, or nothing arrives, go to Troubleshooting. Caching plugins are the usual cause.

Send a notification

On the Push Notifications page, fill in Title, Message, and Link URL (where a click should take the visitor), then send.

The same page shows subscriber growth, a history of your sends, and your subscriber list. Small lists send at once. Larger lists are sent in the background in batches, so your site stays fast.

Notify on new posts

Tick Automatically notify subscribers when a new post is published under Subscription prompt. Each new post is then sent using its title and excerpt. Password-protected posts are skipped so nothing private goes out. Custom post types are off by default; a developer can turn them on with the filter below.

WooCommerce

When WooCommerce is active, a WooCommerce section appears. All four triggers are off until you switch them on, and each has an editable title and message.

Templates accept these placeholders: {product}, {total}, {old_price}, {new_price}, and {items}.

Sending speed

Under Advanced, Server Performance & Delivery Speed, leave Auto-detect (recommended) on. The plugin reads your server's memory and time limits every time it sends and picks a speed to match. If your server comes under strain mid-send, each batch shrinks and slows down on its own.

Auto-detect chooses from Shared up to VPS. Dedicated is never picked automatically, because a large VPS looks identical to a dedicated server from inside PHP. Choose it yourself only if you know it's true.

Import and export subscribers

In the Subscribers section you can export your list as a CSV, or import one to move subscriptions from another push provider or another site. The columns are endpoint, p256dh, and auth, with user_agent and created_at optional.

Very large files are imported in passes. If your server's time limit stops one early, the plugin tells you. Upload the same file again and it carries on, without creating duplicates.

Custom and headless sites

The plugin runs on WordPress, so a site that is not built on WordPress uses one WordPress site as its hub. The hub stores the subscribers and sends the notifications. A small hub on a subdomain such as push.yourdomain.com is fine. Both sites need HTTPS. Everything below is on Push Notifications, Custom Sites.

Install in three steps

1. In Allowed domains, add your custom site exactly as the browser shows it, such as https://yourdomain.com, with no trailing slash. Save.
2. Click Download service-worker.js and upload it to the root of your custom site, so it opens at https://yourdomain.com/service-worker.js. Browsers only allow this file on the site's own domain.
3. Paste the one line shown on the page before </body> on every page. It looks like <script src="https://your-hub.com/wp-json/wppn/v1/embed.js" async></script>.

Visitors then see the same popup, bell or button you set up on the hub. Add data-prompt="bell" to use a different style on that site, or data-wppn-subscribe on any button of your own. If your site already has a service worker, add importScripts('/service-worker.js'); at the top of it and set data-sw to your own file.

Send from your site's own code

Choose Create API key. It is shown once, so copy it to your server's settings. Never put it in page JavaScript. Test it:

curl "https://your-hub.com/wp-json/wppn/v1/ping" -H "Authorization: Bearer YOUR_API_KEY"

If your host removes the Authorization header, send the key as X-WPPN-Key instead. Then send a notification to everyone:

POST /wp-json/wppn/v1/send
{ "title": "New article", "body": "Ten slow-cooker soups", "url": "https://yourdomain.com/soups" }

Automatic notifications

Your code reports what happened, and the hub applies the same editable messages as the WooCommerce triggers. WooCommerce is not needed.

POST /wp-json/wppn/v1/event
{ "type": "price_drop", "data": { "product": "Linen throw", "old_price": 58, "new_price": 42, "currency": "$", "url": "https://yourdomain.com/p/linen-throw" } }

Send an order_id or post_id and a retry never notifies twice. Price drops under your minimum percentage are skipped. For abandoned carts, call WPPNEmbed.linkCart(cartId) in the visitor's browser, where cartId is a random 16 to 64 character string your site keeps for that shopper. Your server sends cart_update with the same id, and the reminder reaches only that shopper after the delay you set.

Subscribers from all connected sites share one list, and the Free plan limit of 200 per send applies to the whole list. iPhone and iPad only allow web push for sites added to the Home Screen, so a custom site needs its own web app manifest for that.

Uninstall

By default, deleting the plugin keeps your data, so an accidental deactivate never loses subscribers. To remove everything (subscribers, send history, encryption keys, and settings), tick the delete-on-uninstall option under Advanced before you delete the plugin. Under Advanced you'll also find buttons to delete send history older than 90 days, and to delete all subscribers. Both act immediately and can't be undone.

For developers

Send a notification from your own code

do_action( 'wppn_send_notification', 'Title', 'Message', 'https://example.com/page' );

Filters