Web Push setup

HoneyNotify can add browser notifications to a typical website, WordPress, Magento, Drupal, Joomla, or a custom JavaScript application. Every path uses the same standards-based Push API subscription and the same HoneyNotify audience, notification, targeting, and analytics features.

What you need#

Before editing the website:

1. Create or select an application in the HoneyNotify dashboard.
2. Open Channels & Setup, choose Web, and generate the Web Push credentials.
3. Copy the VAPID public key. The corresponding private key stays encrypted in HoneyNotify.
4. Create a Public client API key beginning ps_public_ and copy it when shown.

The website must use HTTPS, except for browser development on localhost. Never embed a ps_live_ server key in a website or CMS setting. Public client keys are restricted to device registration and event reporting.

Typical Site setup#

Use this approach for a normal HTML, PHP, or server-rendered site.

The quickest route is Generate code snippet for me in the Web channel's Typical Site panel. HoneyNotify creates a new restricted ps_public_ key, creates Web Push credentials when the channel is not configured yet, and produces a one-time, ready-to-paste snippet containing both public values. Copy it before leaving the page because the complete client key is not stored for later display.

The generated snippet imports the SDK from HoneyNotify's hosted module URL:

import { HoneyNotify } from 'https://app.honeynotify.com/cdn/honeynotify-v1.js';

You must still download honeynotify-sw.js and put it at the root of the site:

/honeynotify-sw.js

Browsers require a service worker to be served by the website origin it controls, so the worker cannot be registered directly from HoneyNotify's hosted URL. The root location lets it control every page on the origin. If it is hosted in a subdirectory, its default scope is limited to that subdirectory.

To self-host the SDK as well, download both honeynotify.js and honeynotify-sw.js, upload the module to /assets/, and change the generated import to /assets/honeynotify.js.

Add a clear opt-in button:

<button id="honeynotify-subscribe" type="button">Enable notifications</button>

Then initialise HoneyNotify as an ES module. Request permission only in response to the button click:

<script type="module">
  import { HoneyNotify } from 'https://app.honeynotify.com/cdn/honeynotify-v1.js';

  const honeyNotify = new HoneyNotify({
    baseURL: 'https://api.honeynotify.com',
    clientKey: 'ps_public_replace_me',
    vapidPublicKey: 'replace_with_the_dashboard_public_key',
    serviceWorkerPath: '/honeynotify-sw.js',
  });

  document.querySelector('#honeynotify-subscribe').addEventListener('click', async () => {
    const deviceId = await honeyNotify.requestPermissionAndRegister({
      externalUserId: window.currentCustomer?.id,
      tags: {
        source: 'website',
        plan: window.currentCustomer?.plan ?? 'visitor',
      },
    });

    if (deviceId) {
      console.log('HoneyNotify Web device registered', deviceId);
    }
  });
</script>

requestPermissionAndRegister() returns null when permission was not granted. It returns the HoneyNotify device ID when registration succeeds and stores that ID in browser local storage.

For a site with a Content Security Policy, allow https://app.honeynotify.com in script-src and https://api.honeynotify.com in connect-src. Self-host the SDK if you do not want to allow the hosted script origin.

WordPress Plugin#

Download the ready-made HoneyNotify WordPress plugin ZIP, or download the same ZIP from the Web channel in the HoneyNotify dashboard. In WordPress:

1. Open Plugins → Add New Plugin → Upload Plugin.
2. Select the ZIP, install it, and activate HoneyNotify Web Push.
3. Open Settings → HoneyNotify.
4. Enter the site name, https://api.honeynotify.com, the ps_public_ client key, and the VAPID public key.
5. Enable the automatic footer button or place [honeynotify_subscribe] in a page, post, or widget.

The plugin serves /honeynotify-sw.js at the site root, loads the HoneyNotify Web SDK, and registers a Web device after the visitor clicks the opt-in button. It never needs or accepts the Web Push private key or a HoneyNotify server sending key.

If WordPress is behind a proxy or CDN, confirm that /honeynotify-sw.js returns JavaScript rather than an HTML cache or redirect. Clear WordPress rewrite rules by visiting Settings → Permalinks if that route returns 404 after moving the site.

Magento Module#

Download the HoneyNotify Magento module ZIP for Magento 2:

1. Extract the archive into <magento-root>/app/code; it creates HoneyNotify/WebPush.
2. Run bin/magento module:enable HoneyNotify_WebPush and bin/magento setup:upgrade.
3. In production mode, run bin/magento setup:static-content:deploy, then run bin/magento cache:flush.
4. Open Stores → Configuration → Services → HoneyNotify.
5. Enable the module and enter the ps_public_ client key and VAPID public key.

The module adds a storefront opt-in button and serves /honeynotify-sw.js with root scope. It does not require or accept the VAPID private key or a server sending key.

Drupal Module#

Download the HoneyNotify Drupal module ZIP for Drupal 10 or 11:

1. Extract it into web/modules/custom, or install it using your normal Composer/deployment workflow.
2. Enable HoneyNotify Web Push from Extend, or run drush en honeynotify.
3. Open Configuration → Web services → HoneyNotify and enter the public client and VAPID keys.
4. Enable the automatic opt-in button, or place the HoneyNotify subscribe block in a theme region.

The module provides the root service-worker route and attaches the SDK only when configured.

Joomla Plugin#

Download the HoneyNotify Joomla plugin ZIP for Joomla 4 or 5:

1. Open System → Install → Extensions and upload the ZIP.
2. Open System → Manage → Plugins and enable System - HoneyNotify Web Push.
3. Enter the ps_public_ client key, VAPID public key, site name, and button label in the plugin settings.
4. Visit the HTTPS site, click the opt-in button, and confirm the new Web device in HoneyNotify Audience.

The plugin loads the bundled SDK and serves /honeynotify-sw.js with permission to control the site root.

Custom Code#

The Web SDK constructor accepts:

Registration accepts externalUserId, an optional verified identityToken, and a tags object. Do not mint identity tokens in browser code. Fetch a short-lived token from your authenticated backend as described in the SDK integration guide.

Track standard or custom events:

await honeyNotify.track('opened', { notificationId: 'notification-uuid' });
await honeyNotify.track('checkout_completed', {
  metadata: { order_id: 'order_7815' },
});

Unsubscribe the browser and disable its HoneyNotify device:

await honeyNotify.unsubscribe();

Send a Web Push notification#

Sending happens from your trusted backend or the HoneyNotify dashboard, not from browser code. This server-side example targets one registered Web device:

curl --request POST https://api.honeynotify.com/v1/notifications \
  --header "Authorization: Bearer ps_live_replace_me" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: web-welcome-device-42-v1" \
  --data '{
    "title": "Welcome to HoneyNotify",
    "body": "Browser notifications are now enabled.",
    "click_url": "https://example.com/account/notifications",
    "target": {
      "type": "device",
      "device_id": "replace_with_registered_device_id"
    },
    "data": {
      "source": "web-onboarding"
    }
  }'

Use a unique idempotency key for each logical send and reuse it only when retrying that same send. You can also target a user, tag, segment, or all active devices. See Notifications for the full payload and targeting rules.

Browser and service-worker behaviour#

• Permission prompts must be initiated from a user gesture and may be permanently blocked by the visitor.
• Web Push requires the Notification API, Push API, and Service Worker API.
• The service worker must be served as JavaScript from the same origin as the website.
• A VAPID key replacement requires browsers to create subscriptions using the new public key. Plan key rotation rather than changing production keys casually.
• Browser push endpoints are provider tokens. HoneyNotify stores the subscription and disables it when the push service reports that it has expired.

Test the complete flow#

1. Use a supported desktop or Android browser on the HTTPS site.
2. Click the opt-in button and allow notifications.
3. Confirm a Web device appears under Audience in HoneyNotify.
4. Send to that single device before testing a broader audience.
5. Put the browser in the background and confirm the notification is displayed.
6. Click the notification and confirm the configured URL opens.
7. Test denial, an already granted permission, unsubscribe, and an expired subscription.

Safari on iPhone and iPad has additional installed-web-app requirements imposed by the browser. Test each browser family you intend to support rather than assuming one successful browser proves all of them.