How to Install Push Agent on Joomla

This guide shows you how to add web push notifications to a Joomla website with the free Push Agent system 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 your template.

Before you start

• Joomla 3.8 or newer, including Joomla 4, 5 and 6.
• Your website must use HTTPS. Browsers only allow push notifications on secure sites.
• 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: Download and install the plugin

Download the Joomla plugin from the Push Agent download page or from the Integration page of your dashboard (Download Joomla plugin). Keep the zip file as it is; don’t unzip it.

• Joomla 4, 5 and 6: go to System → Install → Extensions, open the Upload Package File tab and drop the zip file there.
• Joomla 3: go to Extensions → Manage → Install, open Upload Package File, choose the zip file and click Upload & Install.

Step 5: Paste your access token

Go to System → Manage → Plugins (Joomla 3: Extensions → Plugins) and search for Push Agent. Click System – Push Agent to open its settings.

• Access token: paste the token you copied from the Integration page.
• Ask visitors after (seconds): how long 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 is available on the Starter plan and higher.

On the Advanced tab, leave Push Agent address as https://app.pushagent.net/ and Create pushagent-sw.js automatically set to Yes. The plugin then puts the small service worker file that browsers need in your site’s root folder.

Step 6: Enable the plugin and save

Set Status to Enabled and click Save & Close. Joomla shows a message from Push Agent:

• “Push Agent is set up” means the service worker is in place and you are ready.
• If the plugin couldn’t create pushagent-sw.js because the folder isn’t writable, download pushagent-sw.js from the Integration page of your dashboard and upload it to your site’s root folder (the folder with configuration.php).

Then go back to the Integration page of your Push Agent dashboard and click Verify integration.

Test it

Open your website in a private browser window and wait a few seconds. The “Allow notifications” card appears. Click Allow, then send a test notification from the Push Agent dashboard.

Troubleshooting

The card doesn't appear

Check that the plugin is enabled and the access token is saved. Use a private window and an https:// address. If you already allowed or blocked notifications on your site, reset the permission from the padlock icon in the address bar.

You use page caching

Clear Joomla’s cache (System → Clear Cache) and any CDN cache after saving the plugin.

Updating from the old plugin

Install the new zip over the old one. Your settings are kept, and subscribers from the old version move over silently the next time they visit.