Overview

Web push lets you send browser notifications to visitors even when they're not on your site. Notifications are delivered through the browser's push service (e.g. Firefox Push, Apple Push, FCM), so they reach the user's device whether the browser is open or in the background. You must be subscribed to the Professional plan to send web push notifications.

Web push is built on top of the Spreeflo SDK. If you haven't added the SDK to your site yet, start with the Web Tracking & Analytics guide first.

Set up web push

In the dashboard, go to Marketing > Web Push and click Enable Web Push. The setup wizard walks through three steps:

Site setup — confirm the website URL and provide a default notification icon and site name.

Opt-in prompt — choose how visitors are asked for permission (bell, dialog, or the browser's native prompt).

Service worker — download spreeflo-sw.js and upload it to your site's web root so it's accessible at https://yoursite.com/spreeflo-sw.js. The wizard verifies the file is reachable before completing setup.

The service worker file is hosted at https://spreeflo.com/cdn/sdk/spreeflo-sw.js. Download it and upload it to your site's web root so it's reachable at https://yoursite.com/spreeflo-sw.js.

Download spreeflo-sw.js

Once setup is complete, the SDK on your site automatically detects the service worker on each page load and enables web push. If the file is missing or returns a non-JavaScript content type, the SDK silently disables web push without breaking the rest of tracking.

Opt-in prompts

Browsers only let you ask for notification permission once per visitor — if they decline, you can't ask again from the native prompt. Spreeflo provides three opt-in patterns to maximise the chance of acceptance:

Bell — a small floating bell icon anchored to a corner of the page. Visitors click it when they're ready to subscribe; nothing pops up unsolicited.

Dialog — a customisable in-page modal asking the visitor to opt in. Only after they accept the dialog does the browser's native permission prompt appear.

Native — the browser's built-in permission prompt is shown directly, with no soft prompt in front of it.

The prompt type, copy, colors, position, and timing rules (e.g. show after N pages, after N seconds, or after a scroll threshold) are all configured in the Web Push > Settings modal. The SDK's prompt manager reads this config from the server on init, so changes go live without re-deploying the SDK on your site.

Triggering prompts from code

You can also trigger the opt-in flow yourself — for example, from a "Get notified" button on your site:

document.getElementById("notify-me").addEventListener("click", async () => {
  const subscribed = await Spreeflo.webpush.showPrompt();
  if (subscribed) {
    console.log("Visitor subscribed to push notifications");
  }
});

showPrompt renders the soft prompt configured in the dashboard (bell, dialog, or native) and resolves to true if the visitor ends up subscribed.

If you want to skip the soft prompt and go directly to the browser's native permission dialog, call requestPermission:

await Spreeflo.webpush.requestPermission();

Use this only behind a clear user gesture (e.g. a button click). Browsers may block or auto-deny native permission requests that aren't tied to user interaction.

Subscription management

The SDK exposes a Spreeflo.webpush module for inspecting and managing the visitor's subscription state:

Method	Returns	Description
`isSupported()`	boolean	Returns `true` if the browser supports service workers, push, and notifications.
`isAvailable()`	boolean	Returns `true` if the SDK detected your service worker file at site root.
`getPermissionStatus()`	string	Returns `"granted"`, `"denied"`, or `"default"`.
`isSubscribed()`	Promise<boolean>	Resolves to `true` if a push subscription currently exists for this visitor.
`requestPermission()`	Promise<PushSubscription \| null>	Shows the browser's native prompt and subscribes the visitor on accept.
`showPrompt(options?)`	Promise<boolean>	Shows the configured soft prompt; resolves to `true` if the visitor subscribes.
`unsubscribe()`	Promise<boolean>	Removes the visitor's push subscription, both locally and on the Spreeflo server.

A typical "Manage notifications" toggle on a settings page might look like:

const toggle = document.getElementById("push-toggle");

toggle.checked = await Spreeflo.webpush.isSubscribed();

toggle.addEventListener("change", async () => {
  if (toggle.checked) {
    await Spreeflo.webpush.requestPermission();
  } else {
    await Spreeflo.webpush.unsubscribe();
  }
});

Anonymous vs identified subscribers

Visitors can subscribe before they're identified — their subscription is stored against the SDK-generated visitor ID. When you later call Spreeflo.identify, the existing subscription is automatically linked to the contact, so journeys that target identified contacts can reach them without re-prompting.

Sending notifications

Notifications are created and sent from Marketing > Web Push in the dashboard. Each notification has a name (for your reference), an active flag, and a payload composed of:

Title — the bold headline shown at the top of the notification (required).

Body — the message text below the title.

Icon and Image — small thumbnail and optional large hero image.

Click URL — where the visitor lands when they click the notification.

Action buttons — up to two extra buttons, each with its own label and URL.

Behavior flags — requireInteraction to keep the notification visible until dismissed, silent for no sound.

Default values for icon, badge, and site name are pulled from the Appearance card in Web Push > Settings, so individual notifications only need to override what's different.

Tracking clicks and dismissals

The service worker fires a tracking ping back to Spreeflo when a visitor clicks or dismisses a notification, so delivery, click, and dismiss counts show up on each notification's Analytics view in the dashboard.

Use in journeys

Web push integrates with the journey sequence builder so you can react to push activity the same way you react to email activity:

Send Web Push action — send a notification to the contact at any point in a journey. Use this for re-engagement, flash sales, back-in-stock alerts, or new content announcements.

Check Web Push Activity process — branch the sequence on whether the contact's last notification was Delivered or Clicked. If neither activity is observed, the flow defaults to the Else branch.

See the Campaign and Journey Automation guide for the full list of sequence components.

Disable or reconfigure

From Web Push > Settings you can:

Disable Web Push — pauses sends and overlays the notification list with a "disabled" state. Existing subscriptions are kept.

Enable Web Push — resumes sending after a previous disable.

Reconfigure Setup — re-runs the setup wizard if you've moved your site or replaced the service worker file.

Tip: If Spreeflo.webpush.isAvailable() returns false on your site, the SDK couldn't find spreeflo-sw.js at the root. Re-check that the file is uploaded to your site's web root (not under a subfolder) and that it's served with a JavaScript content type.

Need Immediate Help? Contact our support team at support@spreeflo.com or check our other guides for more information.