Web push

Before you start

1. In the console, open Apps, add an app and open it. Under Browsers (Web Push), click Make Web Push keys.
2. Under Allowed origins, enter every origin that will ask for permission, for example https://www.example.com, and click Save origins. A development app may also use http://localhost:3000. A browser on any other origin is refused.

1. Load the SDK

The file comes from our CDN. A versioned file never changes once it is published, so its integrity hash keeps matching:

<script src="https://cdn.bolrach.com/sdk/push/web/1.6.2/bolrach-push.js"
        integrity="sha384-enzs4J3HyLIX6qGJqtDMpZdaH1VoeYbLSFPK4Hm6d9pN7SwlXHKJul8kDV63cqi8"
        crossorigin="anonymous"></script>

There is also a latest URL that follows each release, but an integrity hash cannot pin it. Use the versioned one in production.

2. Host the service worker

A browser runs a service worker only from the page's own origin. Save this one line as /bolrach-push-sw.js at the site root:

importScripts("https://cdn.bolrach.com/sdk/push/web/1.6.2/bolrach-push-sw.js");

If you would rather not type it, the app page in the console has a Download bolrach-push-sw.js button. That one line pulls in our worker, which draws each notification, tells us it was received and opened, and quietly renews the subscription whenever the browser swaps it out.

3. Ask, then sign the person in

A prompt that appears as the page loads tends to get blocked. Chrome and Firefox both suppress them, and Safari refuses unless a click started it. We have had better luck tying the request to a button the visitor pressed themselves, something like Notify me about replies.

<button id="notify">Notify me about replies</button>
<script>
  BolrachPush.initialize("YOUR_APP_ID", { api: "https://api.bolrach.com/push/v1" });

  document.querySelector("#notify").addEventListener("click", async () => {
    const result = await BolrachPush.requestPermission();
    if (result.permission !== "granted") return; // they said no; do not ask again on this visit
    await BolrachPush.login("user_8123");        // your own id for the signed-in person
  });

  BolrachPush.onNotification((n) => console.log("shown", n.title));
  BolrachPush.onClick((e) => console.log("clicked", e.url));
</script>

On a shared family computer, sign-out matters. Call BolrachPush.logout() there and that browser stops receiving the last person's notifications. A browser nobody has signed in on still has an anonymousId, and when someone does log in, its history moves to them.

4. Send the first one

Your server sends to the same user id that went into login, and every browser and phone that person registered gets it:

curl -X POST "https://api.bolrach.com/push/v1/messages" \
  -H "Authorization: Bearer $BOLRACH_PUSH_KEY" \
  -H "Idempotency-Key: welcome-user_8123" \
  -H "Content-Type: application/json" \
  -d '{"app_id":"YOUR_APP_ID","target":{"type":"user","id":"user_8123"},
       "title":"You are in","body":"Replies to your posts will show up here.",
       "url":"https://www.example.com/inbox"}'

The app page in the console also has Send a test, which goes to the devices registered so far.

If nothing arrives