Documentation

Everything you need to go from install to your first notification. If something doesn't work, the troubleshooting page covers every problem we've hit.

Last updated October 30, 2026 · Plugin version 1.18.4

Quick start

New here? These four steps take about ten minutes.

  1. Check the requirements
  2. Install and activate
  3. Show the subscribe prompt
  4. Test, then send

Requirements

  • WordPress 6.4 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 Pro (Premium) or started a 7-day free trial via Freemius, use the download link in your Freemius 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 Pro (or started a 7-day trial), enter your Freemius license key when the activation screen asks for it.
  4. Open Push Notifications in the left-hand admin menu.

Free and Pro (Premium) are separate downloads. When you activate Pro, the Free version is switched off automatically, so you never run both. You can also start the 7-day Pro free trial or upgrade directly from inside the plugin dashboard via Freemius.

The dashboard at a glance

Open Push Notifications in the admin menu. The page has eight tabs, and switching between them is instant.

TabWhat it is for
DashboardSubscriber totals, the Revenue Tracking Dashboard (Pro), default icon, automatic sending on publish, the 3-step Automated Welcome Series (Pro), notification limit, UTM tracking, and every popup setting, grouped into sections with a jump bar.
NotificationWrite and send a notification with four layouts and a live phone preview, plus Pro options for action buttons, audience segments, A/B split testing, scheduling, repeating sends, and subscriber local timezone delivery.
CampaignsEvery notification you sent or scheduled, with delivery/click counts, per-button clicks (Pro), attributed revenue (Pro), Edit, Reuse, and Delete.
SubscribersYour 20 newest subscribers, with a Download Excel button for the full list, plus CSV import and backup, and the Push keys card for backing up your keys.
VisibilityWhere the popup and bell may appear.
CompatibilityA server health check, sending speed, WooCommerce messages, and clean-up options.
ConnectYour site connection, service worker path, notification name, and the snippets for custom sites.
HelpLinks to this website and a form to contact support.

Ask visitors to subscribe

On the Dashboard tab, under Subscription popup, How it appears, pick a display style:

StyleWhat visitors see
AutomaticA popup shows itself to first-time visitors. No button needed.
ButtonNothing appears until a visitor clicks a [wppn_subscribe_button] shortcode that you place on a page.
Floating bellA small bell sits in the corner of every page. Clicking it opens the popup.
Automatic popup + Floating bellThe popup shows once, and the bell stays so anyone who dismissed it can opt in later.

Under Position and size you choose the popup position and the bell position (eight positions each, plus the center), the popup width (280 to 480 pixels) and the bell size (40 to 72 pixels). Under Timing you set how many seconds and how many page views a visitor needs before the popup shows, how many days to wait before asking again after Later, and an optional quicker re-ask with a limit on how many times.

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

The bell changes color with the visitor's state: blue when not subscribed, green with a check when subscribed, and grey when notifications are blocked in their browser. When the bell opens the popup, it appears in the position you chose under Position and size.

Popup designs

Under Subscription popup, Design there are fourteen looks. Designs 1–3 (Classic, Bottom bar, and Gradient) are included in the Free plan; Designs 4–14 are unlocked in Pro. Click any design to preview it, press the Preview button on any tile to open the full interactive Desktop/Mobile preview window, and pick an accent colour for the buttons. The previews use your own popup text and logo.

DesignLook
1. ClassicA centered white card.
2. Bottom barA slim full-width strip, at the bottom by default. The page stays usable behind it.
3. GradientA bold purple and pink card.
4. DarkA dark card with light text.
5. Soft and roundA round logo and pill-shaped buttons.
6. Side accentA compact card with a coloured edge.
7. Hero headerA coloured header with a large logo.
8. Bottom sheetSlides up from the bottom, made for phones.
9. Minimal textClean text only, with no logo or icon.
10. Top barA slim dark banner across the top, with no logo. The page stays usable behind it.
11. Browser styleLooks like the prompt browsers show themselves, with a small bell icon.
12. Floating cardA small card in a corner with a bell icon. It does not block the page.
13. GlassFrosted dark glass. Works with or without a logo.
14. Bell iconA large bell in a colored circle that gives a short ring when it opens.

All fourteen work on phones. The popup position setting applies to every design. Top bar and Bottom bar are always full width: a top position puts them at the top of the screen, a bottom position at the bottom, and Center keeps each one on its own edge. Choosing Top center shows the normal popup card in the middle of the top edge, not a bar. Designs 9 and 10 never show a logo or icon, and designs 11, 12 and 14 show a bell icon instead of the logo.

The logo comes from your favicon. If WordPress has no Site Icon, the plugin finds the favicon your home page serves. Use Detect my favicon on the Dashboard to check it, or paste your own address into Notification Icon URL.

Customize the popup

Under Subscription popup, Customize you can change how the chosen design looks. The design previews update as you make each change.

SettingWhat it does
Logo in the popupShow your logo, show it as a transparent logo (no tile, frame or shadow behind it, best with a PNG that has a transparent background), or hide the logo in every design. Designs 11, 12 and 14 keep their bell icon. If your site has no logo, or the picture fails to load, a bell icon in your accent color takes its place.
Use my own colors and sizesA switch for the settings below. When it is off, each design keeps its own look.
Popup boxThe box color, the heading color and the description color.
Text sizesThe heading size (12 to 40 pixels) and the description size (10 to 28 pixels).
Bell icon in the popupThe icon color, the circle color and the size (16 to 96 pixels). Used by designs 11, 12 and 14, and in place of the logo when there is none.
Floating bell buttonThe button color and the bell icon color. Its size is set under Position and size.

On the dark designs (Dark, Top bar and Glass), set the heading and description colors too when you change the box color, so the text stays easy to read. The popup bell circle starts at your accent color and does not follow later accent changes, so update it if you change the accent.

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

Open the Notification tab. Choose a design: text only, text with an icon, text with a banner image, or both. Then fill in Title, Link (where a click should take the visitor), the optional icon and banner, and the Message, and press Send Notification. The phone preview updates as you type.

The Campaigns tab lists every send with its status, delivered count and clicks. Use Reuse to open a past campaign filled in again (buttons and audience included), or Delete to remove it. Small lists send at once. Larger lists are sent in the background in batches, so your site stays fast.

Banner images are shown by Chrome and Edge on Windows and Android (on Android, after pulling the notification down). Mac, iPhone, Firefox and Safari ignore the banner. Your icon or favicon shows everywhere.

No subscriber cap on Free: Starting in version 1.18, the Free plan sends to all of your subscribers with no cap. Advanced campaign tools below (scheduling, local timezone delivery, A/B testing, segments, action buttons, Welcome Series, and WooCommerce automations) are part of Push Notify Premium.

Schedule, repeat & send in subscriber's local timezone (Pro)

On the Notification tab in Pro, choose how and when your campaign goes out:

  • Send now: Dispatches immediately (included in both Free and Pro).
  • Schedule for later (site timezone, Pro): Pick a date and time in your site's timezone, up to one year ahead. Scheduled campaigns appear in the Campaigns tab with a Scheduled status, where you can Edit them, Send now, or Cancel them.
  • Repeat (Pro): Repeat a scheduled campaign every day, week or month, with an optional end date. Each time a run starts, the plugin creates the next one as a new scheduled campaign. Missed runs are skipped instead of sent in a burst, and repeat runs do not count against your notification limit.
  • Send at each subscriber's local time (Pro): Choose a target local hour (for example 10:00 AM). The plugin captures each subscriber's UTC timezone offset when they subscribe (with country/site timezone fallback) and delivers the notification when that local hour arrives in each subscriber's own timezone.

Scheduled and local-timezone sends rely on WordPress's built-in scheduler (WP-Cron), which runs when your site gets a visit. For exact timing on a quiet site, ask your host to call wp-cron.php from a real server cron job every minute or two.

A/B testing (Split test campaigns, Pro)

In Push Notify Premium, tick Test two variants (Variant A vs. Variant B) on the Notification tab to split-test your campaign:

  1. Variant A uses your main Title, Message, and Banner URL.
  2. Fill in Variant B (alternate title, message, or banner image — leave any field blank to keep Variant A's value for that field).
  3. Choose your test sample size (10% to 50% of the target audience, split evenly between Variant A and Variant B) and the evaluation window (for example 1 to 24 hours).
  4. After the test window finishes, the plugin compares the click-through rate (CTR) of Variant A and Variant B and automatically sends the winning variant to the remaining subscribers.

Send to a segment (Pro)

Under Send to on the Notification tab in Pro, choose everyone or a segment. A segment can combine these filters: country, device (mobile, tablet or desktop), browser (Chrome, Edge, Firefox, Safari, Opera, Samsung Internet or other), when the person subscribed (in the last N days or more than N days ago) and the page they subscribed from. A live counter shows how many subscribers the segment reaches before you send.

Use Saved segments to name the current filters, for example “India mobile users”, and load them later (you can keep up to 50). A saved segment can also be chosen as the audience for automatic notifications: under Send Notification on Publish in the Dashboard, and in the WooCommerce settings for new order, back in stock and price drop. If you delete a saved segment that is still chosen there, those notifications are paused instead of going to everyone, and the settings page tells you. Abandoned-cart reminders always go only to the visitor who left the cart.

Device and browser are read from the browser when someone subscribes, and the plugin fills them in for existing subscribers in the background after an update. The country comes from a header your host or CDN sends (for example Cloudflare), or from the optional lookup in the Dashboard. A subscriber with no country saved cannot match a country filter. IP addresses are not stored.

Action buttons (Pro)

Under the message on the Notification tab in Pro, press Add button to add up to three buttons below the notification, for example “Get the deal”, “Shop now” or “Read more”. Each button has a name of up to 30 characters and its own link. If you leave the link blank, the button opens the campaign link. The phone preview shows the buttons as you type.

Automatic notifications (new posts and the WooCommerce triggers) can also have one custom action button in Pro, which opens the notification's own link.

In the Campaigns tab, each campaign lists its buttons and how many times each was pressed, under Clicks. Button presses are also included in the campaign's total clicks. Counting needs a visitor's browser to have loaded the updated service worker, which browsers do about once a day.

Browsers decide whether buttons appear. Chrome, Edge and Android browsers show them, and desktop Chrome and Edge usually show two, so put the most important button first. Firefox and Safari do not support notification buttons. In every case, a click on the notification itself opens your main link.

Notify on new posts & Automated Welcome Series

Auto-Send on Publish (Free & Pro): On the Dashboard tab, under Sending, tick Send Notification on Publish and choose which content types should notify (Posts only by default). Each new item is sent using its title and excerpt. Password-protected items are skipped so nothing private goes out. In Pro, you can also attach a saved segment and an action button to auto-send on publish.

Under the same section, Set Notification Limit caps how many notifications can go out per day, week or month. Under Link tracking, UTM Tracking adds utm_source, utm_medium and utm_campaign to every link so the visits show in Google Analytics.

Automated Welcome Series (Pro): On the Dashboard tab under Welcome series (Automated drip sequence), configure up to 3 automatic notifications that go out after a visitor subscribes (for example: Step 1 after 5 minutes, Step 2 after 1 day, and Step 3 after 3 days). Each step has its own enable toggle, delay (in minutes, hours, or days), title, message, link URL, and optional action button label.

WooCommerce & Revenue Tracking Dashboard (Pro)

Included in Push Notify Premium (with a 7-day free trial via Freemius): Automate your WooCommerce store notifications and see exact revenue recovered right on your Dashboard.

Revenue Tracking Dashboard: At the top of the Dashboard tab, Pro displays “Push notifications recovered $X this month” with automatic WooCommerce order attribution broken down by Abandoned carts, Campaigns, Welcome series, and All-time recovered revenue & orders. Each individual campaign in the Campaigns tab also displays its attributed revenue.

Under the Compatibility tab (or WooCommerce section), all four WooCommerce triggers are off until you switch them on, and each has an editable title and message:

TriggerWho receives itDetails
New order placedAll subscribersSent once when payment is confirmed (Processing or Completed). Never includes the buyer's name or any personal detail.
Back in stockAll subscribersSent when a product goes from out of stock to in stock.
Price dropAll subscribersSent when a price falls by at least your minimum (5% by default), so tiny price syncs stay quiet.
Abandoned cartOnly the shopper who left the cartSent after a wait you choose (60 minutes by default). Works for logged-out shoppers. Cart contents are read on your server from WooCommerce.

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

Visibility

The Visibility tab chooses where the popup and floating bell may appear. You can hide them on chosen pages (one per line, with * as a wildcard, such as /shop/*), on the home page, for logged-in visitors, or on phones or computers. The [wppn_subscribe_button] shortcode is never hidden, because you placed it on purpose.

Sending speed

On the Compatibility tab, under 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.

LevelPer batchPauseAt once, per push service
Shared505 s10
Business / managed2003 s25
Cloud4002 s40
VPS6001 s60
Dedicated1,0001 s100

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

The Subscribers tab shows your 20 newest subscribers with the browser, operating system, device (mobile, tablet or desktop), country and sign-up time, and a Delete button for each person. IP addresses are not stored. The country comes from the header your host or CDN sends (for example Cloudflare's), and an optional lookup with the free ipwho.is service, off by default, can fill in the rest. Subscribers saved by earlier versions have their saved IP address erased in the background. Under Settings, Privacy, Policy Guide in WordPress the plugin adds suggested wording for your privacy policy. Download Excel gives you a spreadsheet of every subscriber. If your server has no zip support, you get a CSV that Excel opens directly.

To restore a backup, use Export CSV backup and Import CSV. The columns are endpoint, p256dh, and auth, with user_agent, created_at, country (a two-letter code such as IN), page_url and vapid_key_id optional. An old ip_address column is ignored. Treat the backup file as private.

A CSV on its own is not enough to restore a list: subscribers only receive notifications when your site uses the same push keys as the list came from. Back up and restore explains the two files you need.

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.

Back up and restore your subscribers

A complete backup is two files. Both come from Push Notifications, Subscribers:

  1. The subscribers. Click Export CSV backup.
  2. The push keys. In the Push keys card, click Download push keys.

You need both because every subscription is tied to the push keys of the site that created it. A browser's push service refuses messages signed with a different key, so a CSV on its own can import with every subscriber listed and nobody receiving anything.

Keep both files private. The keys file contains your private key, and anyone who has it can send notifications to your subscribers. Do not email it or leave it in a public folder.

Restore after a reinstall or a move to new hosting

  1. Install the plugin on the website, at the same address (the same domain) your visitors subscribed on.
  2. Open Subscribers. In the Push keys card, open Import existing push keys, choose your keys file and click Import keys. Do this first.
  3. Under Import subscribers, choose your CSV and click Import CSV.
  4. Send a test notification to a browser you know is subscribed.

You can also paste the public and private key instead of choosing a file. The private key may be a 43-character base64url value or a PEM block. The plugin checks that the two belong together before it saves anything, and if they do not, nothing is changed.

If the site already has subscribers, importing keys asks you to tick a confirmation. People who joined with the previous keys stop receiving notifications, and they are re-subscribed in the background on their next visit if they had already allowed notifications. For a clean start, use Delete ALL subscribers before you import.

The Key ID

The Key ID is a short fingerprint of your public push key. It is shown in the Push keys card and on the Connect tab, and it is safe to share. Two sites with the same Key ID can send to the same subscribers. Each CSV backup records it in the vapid_key_id column, and when you import a CSV the plugin tells you if its subscribers were created with a different key than your site uses.

What does not work

  • A different website address. A visitor's browser ties each subscription to the address they subscribed on. If your site moves to a new domain, visitors need to subscribe again.
  • Subscribers from a hosted push service. Hosted services usually do not give out their private key, and without it nobody can send to those subscribers. Show your subscribe prompt again and let visitors subscribe, ideally while both services run side by side for a few weeks.
  • Lost keys. If the plugin's data was deleted and you have no keys file, the keys cannot be recovered. Earlier subscribers cannot be reached, so visitors need to subscribe again.

Moving from another self-hosted push plugin on the same address is possible if you can get that plugin's public and private key and an export with endpoint, p256dh and auth columns. Import the keys first, then the CSV.

Custom and headless sites

The plugin runs on WordPress, so a site that is not built on WordPress uses one WordPress site as its control room, also called the hub. Your custom site only shows the subscribe popup. Subscribers are saved in WordPress, and you send from WordPress. Everything below is on Push Notifications, Custom Sites.

One-time setup on the WordPress site

  1. Use a WordPress site with HTTPS. An easy choice is a small new WordPress on a subdomain such as push.yourdomain.com.
  2. Install and activate the latest Push Notify there (version 1.10.3 or newer).
  3. Go to Push Notifications, Custom Sites.
  4. In Allowed domains, type your custom site's address, such as https://yourdomain.com. Add https://www.yourdomain.com too if you use it. Then save. Use https:// and no slash at the end.
  5. Click Download service-worker.js. This small file is what lets browsers show notifications.

On the custom website

  1. Upload service-worker.js to the main folder of your site (often public_html), next to index.html. It must open at https://yourdomain.com/service-worker.js. It can't live on the WordPress site, because browsers only accept it from your own domain.
  2. Copy the one line shown on the Custom Sites page. It looks like <script src="https://push.yourdomain.com/wp-json/wppn/v1/embed.js" async></script>. Paste that line, and only that line, just before </body> on every page.

Test it

Open your website and click Allow on the popup. Then check that the subscriber count went up on the WordPress site, and send a test from the Push Notifications page. If the popup doesn't appear, refresh with Ctrl+F5, and see troubleshooting.

Options for the script line

Visitors see the same popup, bell or button you set up on the hub. You can change how it looks on the custom site by adding these to the script tag:

  • data-prompt="bell" uses a different style on that site (auto, button, bell or both).
  • data-logo="https://yourdomain.com/logo.png" shows your own logo in the popup. Without it, the popup shows the hub's Site Icon (Settings, General, Site Icon), or the plugin's bell icon if none is set.
  • data-wppn-subscribe on any button of your own turns it into a subscribe button.
  • 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.

Sending notifications

  • By hand: write the message in WordPress and press send.
  • Automatically: your site's own code can send a notification using an API key, made on the same Custom Sites page. The next two sections show how.

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" } }
TypeSend it whenData
new_postYou publish somethingtitle, excerpt, url, post_id
new_orderAn order is paidorder_id, items, total, url
back_in_stockA product returnsproduct, url
price_dropA price fallsproduct, old_price, new_price, url
cart_update, cart_clearA cart changes, or is paidcart_id, items, url

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.

Custom and headless site integration (embed.js, CORS allow-list, and the REST Send/Event API) is included in Push Notify Premium. Subscribers from all connected sites share one list on your WordPress hub. 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 on the Compatibility tab before you delete the plugin. The Compatibility tab also has a button to delete send history older than 90 days, and the Subscribers tab has one to delete all subscribers. Both act immediately and can't be undone. Before you delete anything, download your push keys and a CSV backup (see Back up and restore): without the keys, a subscriber list cannot be restored.

For developers

Send a notification from your own code

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

Filters

FilterWhat it changes
wppn_modal_title, wppn_modal_body, wppn_modal_allow_label, wppn_modal_later_labelThe popup text
wppn_autosend_post_typesPost types that send automatically on publish. Default is array( 'post' ).
wppn_max_subscribers_per_sendThe safety ceiling on how many subscribers one send can reach (1,000,000 by default)
wppn_detected_hosting_presetOverride the auto-detected hosting level. Lets a host add-on select dedicated.
wppn_rate_limit_window_seconds, wppn_rate_limit_max_requestsThe subscribe route's per-visitor rate limit (20 requests per 600 seconds by default)
wppn_country_lookup_enabled, wppn_country_lookup_urlSwitch off, or change, the optional country lookup used when the host sends no country header.
wppn_trust_x_forwarded_forTrust the forwarded IP header when rate limiting behind a proxy. Off by default.
wppn_allowed_endpoint_host_suffixesExtra push-service host names to allow, on top of Google, Mozilla, Microsoft, and Apple

Still stuck?

Most problems come from a caching plugin or a site that is not on HTTPS. The troubleshooting page covers both, step by step.