How to Install Push Agent on WordPress

This guide shows you how to add web push notifications to a WordPress website with the free Push Agent plugin. The plugin adds the Push Agent script to every page and creates the service worker file for you, so you don’t need to edit any code.

Before you start

• WordPress 4.7 or newer and PHP 5.6 or newer.
• Your website must use HTTPS. Browsers only allow push notifications on secure sites (localhost works for testing).
• A Push Agent account. It’s free, and the steps below show how to create one.

Step 1: Create your free Push Agent account

Go to app.pushagent.net and click Create an account. Sign up with Google, or enter your name, email address and a password of at least 8 characters. The Free plan needs no credit card, and every new account gets all Growth features free for 14 days.

If you signed up with your email address, open the activation email from Push Agent and click the link in it. Then sign in at app.pushagent.net.

Step 2: Add your website

In the Push Agent dashboard, open Websites and click Add website. Enter your business name and your website address, including https://, and choose your business type and language. You can also upload a website icon: it is shown on your notifications, so use a square image of at least 192 × 192 pixels.

Step 3: Copy your access token

Open Integration in the dashboard. On the right you see your website’s access token. Click the copy button next to it.

Step 4: Install the Push Agent plugin

In your WordPress admin, go to Plugins → Add New Plugin and search for Push Agent. Click Install Now, then Activate.

You can also download the plugin from the Integration page of your Push Agent dashboard (Download WordPress plugin) and upload it under Plugins → Add New Plugin → Upload Plugin.

Note: Already using an older version of the plugin? Update it from the Plugins page. Your access token is kept, and subscribers from the old version move over silently the next time they visit your site.

Step 5: Paste your access token

After activation, a Push Agent menu appears in your WordPress admin. Open Push Agent → Settings, paste your access token into the Access token field and click Save settings.

On the same screen you can choose how many seconds after a page loads the “Allow notifications” card appears for new visitors. On the Free plan the card always appears after 3 seconds; custom timing and your own card text are available on the Starter plan and higher. You set the card’s text in your Push Agent dashboard under Websites.

Leave Create pushagent-sw.js automatically switched on. The plugin then puts the small service worker file that browsers need in your site’s root folder. If that folder isn’t writable, the plugin serves the file through WordPress instead.

The API key field is optional. You only need it for WooCommerce order updates and to see your subscriber numbers inside WordPress. See Set up WooCommerce order notifications.

Step 6: Check the setup and verify

Open Push Agent → Dashboard. The setup checklist and health check show what is done and what still needs attention.

Finally, go back to the Integration page of your Push Agent dashboard and click Verify integration. Push Agent checks your homepage for the script and the service worker.

Test it

Open your website in a private browser window and wait a few seconds. The “Allow notifications” card appears. Click Allow, and you are your site’s first subscriber. Now send a test notification from the Push Agent dashboard.

Troubleshooting

Visitors don't see the "Allow notifications" card

Wait for the delay you set, and use a private window. Browsers only show the card on https:// sites. If you already allowed or blocked notifications on your site, it won’t appear again: reset the permission from the padlock icon in the address bar.

The dashboard says pushagent-sw.js is missing

Your root folder isn’t writable, or WordPress is installed in a sub-folder. Download pushagent-sw.js from the Integration page of your Push Agent dashboard and upload it to the root folder of your domain, usually the same folder as wp-config.php.

You use a caching plugin or Cloudflare

Clear the cache once after saving the settings. The Push Agent script is marked so Rocket Loader and optimisation plugins leave it alone.

Multisite

Activate the plugin on each site and enter that site’s own access token. The service worker is served per site.