PushGenius

Web push

Reach people in Chrome, Edge, Firefox, and Safari (macOS 13+, and iOS 16.4+ for sites added to the Home Screen) with the same segments, scheduling, and delivery tracking you use for mobile. Browser subscribers show up in your audience next to iOS and Android devices, and one POST /notifications reaches all of them.

1. Enable web push

In the dashboard, open Settings → Web push, enter your site’s https:// address, and save. PushGenius generates a VAPID key pair for your app and shows the snippets below with your app ID filled in. Browsers only allow push on secure origins; http://localhost works for development.

2. Add the SDK to every page

<script src="https://api.pushgeni.us/sdk/web/v1/pushgenius.js" defer></script>
<script>
  window.PushGeniusDeferred = window.PushGeniusDeferred || [];
  PushGeniusDeferred.push(async (PushGenius) => {
    await PushGenius.initialize("YOUR_APP_ID");
  });
</script>

3. Serve the service worker from your site root

Create /pushgenius-sw.js on your own domain with this one line. Browsers require the worker to come from your origin; it loads the rest from PushGenius so you get updates automatically.

importScripts("https://api.pushgeni.us/sdk/web/v1/pushgenius-sw.js");

Already have a service worker? Add the same importScripts line to it and pass its path: PushGenius.initialize(appId, { serviceWorkerPath: "/sw.js" }). PushGenius only handles pushes it sent, so your other push handlers keep working.

4. Ask for permission

Browsers block permission prompts that don’t come from a click or tap, so call requestPermission from a button rather than on page load:

document.querySelector("#notify").addEventListener("click", async () => {
  const subscribed = await PushGenius.Notifications.requestPermission();
});

Once someone has allowed notifications, the SDK keeps their subscription in sync on every visit, including when the browser rotates the endpoint.

Users, tags, and aliases

await PushGenius.login("user-123");
await PushGenius.User.addTags({ plan: "pro", locale: "en" });
await PushGenius.User.addAlias("crm_id", "C-88412");
await PushGenius.logout();

Tags you set before login stay with the person when they sign in. If they already have a user from another browser or your mobile app, this browser joins that user, so include_aliases reaches every device they use.

Opt-out and clicks

PushGenius.User.PushSubscription.optedIn;   // true when this browser can receive
await PushGenius.User.PushSubscription.optOut();
await PushGenius.User.PushSubscription.optIn();

PushGenius.Notifications.addClickListener((event) => {
  console.log(event.notificationId, event.url, event.additionalData);
});

Clicking a notification opens its launch URL, or focuses the tab if it’s already open. Received and clicked events are reported automatically and show up in each message’s stats.

Sending to browsers

Use the regular REST API. These optional fields apply to browsers:

  • url or web_url: the page to open on click (web_url wins for browsers).
  • chrome_web_icon: the notification icon. Defaults to the icon set in Settings.
  • chrome_web_image: a large image, shown by Chrome and Edge.
  • collapse_id: a newer message with the same ID replaces the older one.
  • ttl and priority: how long the push service holds the message for an offline browser, and how urgently it delivers it.

Browsers limit a push to about 4 KB, so keep data small. Messages that don’t fit fail with a clear error instead of being cut off.

Bringing existing subscribers

Browser subscriptions are tied to the VAPID key that created them. If your previous provider gives you that key pair, turn on Use my own VAPID keys in Settings and paste it, and your existing subscribers keep receiving. If not, people who already allowed notifications are re-subscribed silently the next time they visit a page running the PushGenius SDK. They won’t see the prompt again.