Web push

Use this to send notifications to a browser: Chrome, Edge, Firefox, and Safari. It is standard Web Push. You do not need a Firebase project or an Apple certificate.

There is no key to type. Add the connection, and FounderHQ makes the key pair. The private key stays in FounderHQ.

Connect

1. Open Sequences → Settings, press Connect channel, then choose Push.
2. Select Web push. Give the connection a name and a contact email. Browser makers use the email if there is a problem with your notifications. Your visitors never see it.
3. Click Connect web push. FounderHQ shows the public key of the connection.

You can copy the key again later: open the menu of the connection in Sequences settings and select Copy public key.

Set up your site

Your site must have the FounderHQ Web SDK first: see Web SDK. Web push works only on a site with HTTPS. http://localhost also works, for a test on your own computer.

Do four things on your site:

1. Copy the public key. It is on the connection in Sequences settings. It is safe to put in your site's code.

2. Add the service worker file. Make a file with the one line below and serve it from your own site at /founderhq-push-sw.js. A browser accepts a push service worker only from the origin of the page, so this small file must be on your site. The line loads the FounderHQ code, and you get each update with no work.

   // /founderhq-push-sw.js
   importScripts("https://i.getfounderhq.com/founderhq-push-sw.js");

3. Ask for the permission. Call requestWebPushPermission when the person clicks your own button. Browsers refuse a prompt that no click started. You decide where the button is and when it shows; the SDK shows no interface of its own.

4. Register the browser. Call registerWebPush after identify, on every page load.

founderhq.identify("user_42");

// On every page load. It does nothing until the permission is granted.
founderhq.registerWebPush({ applicationServerKey: "YOUR_PUBLIC_KEY" });

// On your "Turn on notifications" button.
button.addEventListener("click", async () => {
  const { status } = await founderhq.requestWebPushPermission({
    applicationServerKey: "YOUR_PUBLIC_KEY",
  });
  if (status === "registered") hideTheButton();
});

requestWebPushPermission shows the browser's prompt and then registers the browser. It does not ask again when the person already allowed or blocked notifications. Both functions return a promise with a status:

The promise never rejects. The SDK only ends a push subscription that it made. A subscription from another push product on your site always stays.

iPhone and iPad have web push only for a site that the person added to the Home Screen. Three things are necessary:

• iOS or iPadOS 16.4 or later.
• Your site has a web app manifest with "display": "standalone".
• The person added your site to the Home Screen and opens it from there.

In a normal Safari tab the status is unsupported.

If your site already has a service worker

A site can have only one service worker for a scope. The SDK does not replace yours. When it finds another worker and you gave no serviceWorkerPath, registerWebPush returns failed with the reason service_worker_exists, and nothing changes.

Do two things:

1. Load the FounderHQ code from the first line of your own worker. You then do not need the /founderhq-push-sw.js file.
2. Give the SDK the path of your worker.

// sw.js: this must be the first line.
importScripts("https://i.getfounderhq.com/founderhq-push-sw.js");

founderhq.registerWebPush({
  applicationServerKey: "YOUR_PUBLIC_KEY",
  serviceWorkerPath: "/sw.js",
});

The line must be first, so that the FounderHQ code runs before yours. Your own push and notificationclick code then does not get a FounderHQ notification, and you do not show it a second time. Every other push still goes to your code.

Does your framework register the worker, or is your worker a module? A module worker cannot use importScripts. Save a copy of the FounderHQ code on your site as /founderhq-push-sw.js, and use import "/founderhq-push-sw.js" as the first line of your worker. Then give the SDK the registration, and the SDK registers nothing:

founderhq.registerWebPush({
  applicationServerKey: "YOUR_PUBLIC_KEY",
  serviceWorkerRegistration: await navigator.serviceWorker.ready,
});

Did your site use /founderhq-push-sw.js as its worker before, and now has its own worker on the same scope? Add the importScripts line. Without it no worker shows a FounderHQ notification, so on the next visit the SDK ends that browser's FounderHQ subscription and removes the browser from the contact.

The FounderHQ file only shows FounderHQ notifications and opens their links. It does not cache pages. It has no fetch handler, so it does not change how your pages load.

One connection keeps its key pair. A browser subscription works only with the key it was made with. If you add a new web push connection and use its key, the SDK subscribes each browser again on its next visit. A browser that does not come back gets no more pushes.

A browser belongs to one site: the subscription of app.example.com is not the subscription of www.example.com.

Send

A browser is one more device of the person. A push step in a sequence and a push broadcast reach it with no other change. To send to browsers only, open Devices on the push step or the broadcast and turn off iPhone and Android.

Show a push in your page while the person is there

A notification from the browser is for a person who is away. For a person who has your site in view, you can show the push in your own page.

Put fhq_when_visible with the value page in the data of the push template. When that push arrives and a tab of your site is in view, no browser notification shows. The tab gets a message, and your page shows it:

navigator.serviceWorker.addEventListener("message", (event) => {
  if (event.data?.type !== "founderhq:push") return;
  const { title, body, link, data } = event.data;
  showInMyPage({ title, body, link, data });
});

With no tab in view, the browser notification shows as usual. A push with no fhq_when_visible always shows the browser notification.

Replace or remove a notification

A push can carry a notification key: any text you choose, such as order-1042, set as notificationKey when you send from your server. A push with no key of its own is named by its message ID.

Replace. Send another push with the same key. The browser shows one notification with the new text, not two.

Remove. Call the SDK from your page when the person has seen what the notification is about. Pass the notification key, or the message ID for a push with no key:

// The person opened order 1042.
await founderhq.dismissPushNotification("order-1042");

It closes the notifications your site's FounderHQ pushes showed with that key, in this browser, and resolves with how many it closed. It sends nothing, so it works with or without consent.

A browser's notification is removed by your page only. A browser expects every push to show something, so a removal from your server reaches phones and tablets and leaves browsers alone.

What a browser shows

A push template is the same for phones and browsers. A browser uses its fields as follows:

The image and the icon must be https links.

Verify

1. Open your site in a browser, sign in, and allow notifications.
2. In FounderHQ, open the person in People. The browser shows in the list of the person's devices.
3. Open a push broadcast and send a test to that person. The notification shows in the browser in some seconds.

If the browser does not show on the person, read the status and reason that registerWebPush returns.

For opens, message content, and troubleshooting, see Push.

AI agent or LLM? Read this page as markdown