OneSignal WordPress Push Notifications: Setup for v3

5/5 - (9 votes)

OneSignal lets a WordPress publisher send browser push notifications to visitors who have opted in. You can use it to announce genuinely useful new articles or offers, but it is not a guaranteed traffic source: visitors must allow notifications, browser support varies, and frequent or irrelevant messages encourage people to unsubscribe.

Important update: OneSignal’s WordPress plugin changed substantially in version 3. The older screenshots in the original version of this tutorial show a different settings interface, including an obsolete non-HTTPS setup. The steps below follow OneSignal’s current WordPress documentation and the official plugin listing. Check the vendor’s instructions again if its interface changes.

Before you install: requirements and decisions

  • HTTPS: your WordPress website needs a working HTTPS origin. Do not follow an old instruction to enable a non-HTTPS setup.
  • OneSignal account: you will create or select a OneSignal app and connect it to WordPress.
  • Permission strategy: decide when an opt-in prompt makes sense. Asking before a visitor has understood your site is usually a poor experience.
  • Editorial policy: decide which types of content warrant a push. Not every correction, bulk article refresh or scheduled edit needs a notification.
  • Privacy and consent: review the service’s data handling, your privacy notice and requirements for the jurisdictions in which you operate.

Step 1. Install the official OneSignal WordPress plugin

  1. In WordPress, open Plugins → Add New and search for OneSignal – Web Push Notifications.
  2. Confirm the developer and listing at WordPress.org, install it and activate it.
  3. Open its setup screen in WordPress. Keep the tab open while configuring the corresponding OneSignal app.

Do not install several web-push plugins simultaneously unless you have a specific, tested reason: competing service workers and prompts can interfere with each other.

Step 2. Create the OneSignal app and connect your site

  1. Sign in to the OneSignal dashboard and create an app, or select the existing app for your website.
  2. Open the app’s web-push configuration and choose the WordPress Plugin or Website Builder integration, selecting WordPress where prompted.
  3. Enter the site’s real HTTPS URL. Pay attention to www versus non-www: the browser push subscription belongs to a particular origin.
  4. Set the site name and upload an appropriate notification icon if requested. Review the image dimensions in OneSignal’s current instructions.
  5. Copy the app’s App ID and REST API Key into the corresponding fields of your WordPress plugin setup, then save.

Keep the REST API key private. Do not paste it into a public support post, article screenshot, front-end HTML or source repository. Labels and the exact menu path may move, so use the official WordPress integration guide alongside this checklist.

Step 3. Configure the opt-in prompt in OneSignal

In the current integration, the web permission prompts are configured in the OneSignal dashboard, not by following the old WordPress plugin screenshots. Choose the prompt style and timing, then test it on desktop and mobile. Browser-native permission dialogs vary; you cannot force a visitor to subscribe.

Make the promise specific: for example, ‘Get an alert when a new tutorial is published’ is clearer than ‘Allow notifications.’ Avoid repeatedly interrupting people who decline. If you use topics or segments, give subscribers a meaningful choice about the messages they receive.

Step 4. Send a test notification

  1. Open the published site in a normal supported browser window using HTTPS; complete the opt-in.
  2. In OneSignal, check that the subscription appears in your audience or subscription records.
  3. Use the dashboard’s message composer to send a test push to the appropriate test audience.
  4. Confirm the title, icon, target URL and click destination; test again on the browsers and devices that matter to your readers.

An incognito window, blocked browser permissions, another installed push service or a mismatch between the configured URL and real site origin can invalidate the test. If delivery fails, start with OneSignal’s current troubleshooting instructions rather than reinstalling the plugin blindly.

Step 5. Decide whether WordPress should notify subscribers on publish

The current WordPress integration can send notifications when a post is published or updated, and a post-editor control allows notification content to be customized. Review the automatic-send setting carefully: a site that republishes or refreshes dozens of older articles could otherwise send subscribers a stream of unwanted updates. Choose a deliberate send workflow, check the post’s notification option, and confirm the intended audience before publishing.

Use descriptive push copy that accurately reflects the linked article. A short, truthful title is preferable to manufactured urgency, and the landing page should match the promise made in the notification.

Step 6. Track useful outcomes

Monitor subscriptions, successful deliveries, notification clicks and the actions visitors take after returning to the site. If you use UTM parameters, confirm the destination URL actually contains them and that your analytics tools don’t double-count visits. Changes in article traffic can also come from search, email and seasonality; an increase after installation is not by itself proof that push generated it.

Start with a restrained send schedule. Compare unsubscribes and downstream engagement, not just an impressive subscriber count. Keep email, RSS or other subscription options where appropriate for visitors who do not want browser notifications.

Upgrading from the legacy OneSignal WordPress plugin

Version 3 changed the integration and moved much of the configuration into OneSignal’s dashboard. Before upgrading an existing setup, back up WordPress, record your current App ID, review any custom OneSignal JavaScript and follow the vendor’s migration instructions. The plugin changelog warns that older direct SDK modifications may break under the newer web SDK.

Do not manually upload a second service worker or move the service-worker path while using the plugin unless OneSignal’s current documentation explicitly instructs you to. After migration, verify that existing subscribers remain recognized, that new opt-ins work, and that a test notification arrives before enabling broad sends. If your site uses custom post types or a custom notification title, test those paths separately.

Common OneSignal WordPress problems

The permission prompt never appears

Check HTTPS, the exact configured origin, browser permission state, ad/script blockers and whether another push plugin is installed. A browser that previously denied permission may not show the prompt again until that permission is changed in browser settings.

Subscribers appear, but notifications do not arrive

Check that you selected the correct OneSignal app, have an active test subscription, targeted the right audience and supplied a valid URL. Compare delivery status in the dashboard before changing code.

Every old post edit sends an alert

Inspect automatic publish/update notification options in the WordPress plugin and the individual post’s send control. Use manual sends for editorially significant updates rather than broadcasting routine maintenance.

Do I need an API key on the public page?

No. The REST API key belongs in the private configuration fields that the plugin requires, never in your page copy or a client-side snippet.

OneSignal WordPress setup FAQ

Does OneSignal web push work on an HTTP-only site?

The current WordPress integration documentation requires HTTPS. Fix the certificate and redirect configuration before setting up push.

Can subscribers receive pushes while they are away from my site?

In supported browsers and devices, browser push can be delivered after visitors leave the page, subject to their permission and device/browser notification settings. Delivery is not guaranteed for every subscriber.

Is OneSignal the same as an email newsletter?

No. A browser push subscription and an email subscription are separate channels with different permission, reach and retention properties. Consider offering both rather than treating push as a replacement.

Next step: open the official OneSignal WordPress setup guide, connect a test app, and verify a single opt-in and notification before enabling automatic sends to your real audience.