Alert Users When Shared Data Changes


The Events API and KV sharing are in beta. Method shapes, limits, and behavior may change between releases.

In Send Live Updates to Other Users, a scorekeeper shares a game with fans, and each fan sees the score change while their page is open. Most fans won't keep the page open for a whole game. They want an alert when the game ends, or when a team scores.

This recipe adds that. Each fan's app subscribes to the game with a handler that Puter runs for the fan, even while your app is closed. The handler decides whether a change is worth an alert, and calls notify() for the fan. Each fan picks which changes they want, and the scorekeeper's page never has to reach the fans. When the person making a change should decide who hears about it, as in a chat, notify through the share instead, as Notify Chat Members of New Messages shows.

This recipe uses the prefix, handle and label from Send Live Updates to Other Users. Your site also needs to serve /puter-sw.js, as Reach a User When Your App Is Closed shows.

Mark the End of the Game

The scorekeeper writes the score as before, and adds final: true when the game ends:

await puter.kv.set(`${prefix}score`, { home: 2, away: 1, final: true });

Publish the Handler

Publish a handler that alerts on the final score, and on every goal for fans who asked for that, with puter.events.handlers.publish(). Publishing is a developer step, so run this once yourself, signed in to your site as the app's owner. The browser console is enough. To skip it, pass the same function as handler to each fan's onPersistent() call instead, which stores it in the fan's own user scope:

await puter.events.handlers.publish('alertScore', async ({ event, user, ctx }) => {
    if (event.op !== 'set') return;
    const score = 'value' in event ? event.value : await user.kv.get('score', { handle: ctx.handle });
    if (!score || (!score.final && ctx.alerts !== 'goals')) return;

    await user.notifications.notify({
        title: score.final ? `Final: ${ctx.label}` : ctx.label,
        text: `${score.home} - ${score.away}`,
        channel: 'scores',
        group: `game:${ctx.handle}`,
        target: `/games/${ctx.handle}`,
    });
});

Puter runs the handler later, in your app's events worker, so it can't use variables from around it. Everything it needs comes from event, user (the fan), and ctx, the values each fan's subscription is created with. Run Code in the Background explains handlers in more detail.

An event leaves out the score when it reaches many fans, so the handler reads it through the share then. The group makes a new alert for the game replace the fan's earlier one instead of adding another.

Say What an Alert Shows

On every page load, register a handler for the scores channel with puter.notifications.onPush():

await puter.notifications.onPush('scores', (n) => ({
    title: n.title,
    body: n.text ?? '',
    url: n.target ?? '/',
}));

While your app is open, an alert reaches this handler in the page, and the page shows it only when its tab is hidden or its window isn't focused. While your app is closed, the same handler runs in your service worker to decide what the push shows.

Follow a Game

The fan subscribes to the game's score key with puter.events.onPersistent(). A persistent subscription is saved to the fan's account and keeps running after they close your app. The fan's choice of alerts goes in context, which the handler gets as ctx:

const subject = `kv:${handle}:score`;

async function findFollow () {
    const subs = await puter.events.list();
    return subs.find((sub) => sub.subject === subject && sub.handlerName === 'alertScore'
        && sub.suspendedReason !== 'permission_revoked');
}

async function followGame (alerts) {
    if (!await puter.perms.request('backgroundEvents')) return false;

    const context = { alerts, label, handle };
    const existing = await findFollow();
    if (existing) await puter.events.update(existing.subId, { context });
    else await puter.events.onPersistent({ subject, handlerName: 'alertScore', includeValue: true, context });
    return true;
}

Running a handler while the fan is away needs their permission, which puter.perms.request() asks for with the backgroundEvents resource. It doesn't prompt when the fan already allowed it. When the fan already follows the game, puter.events.update() changes their choice of alerts on the existing subscription, so pressing a button twice doesn't add a second one.

Give the fan two buttons. Browsers only show their permission prompt from a click, so each one calls puter.notifications.enable() first:

for (const alerts of ['final', 'goals']) {
    document.getElementById(`alert-${alerts}`).addEventListener('click', async () => {
        const pushes = await puter.notifications.enable();
        const following = await followGame(alerts);
        console.log(pushes && following ? `Alerts on: ${alerts}` : 'Alerts are off');
    });
}

Stop Following

When the game is over, or the fan presses an "Unfollow" button, remove the subscription with puter.events.unsubscribe():

async function unfollowGame () {
    const existing = await findFollow();
    if (existing) await puter.events.unsubscribe(existing.subId);
}

When the scorekeeper stops sharing the game, the fan's subscription stops on its own. It stays in puter.events.list() with suspendedReason: 'permission_revoked' until it's deleted 30 days later.

Full Code

The handler, published once by the app's owner:

await puter.events.handlers.publish('alertScore', async ({ event, user, ctx }) => {
    if (event.op !== 'set') return;
    const score = 'value' in event ? event.value : await user.kv.get('score', { handle: ctx.handle });
    if (!score || (!score.final && ctx.alerts !== 'goals')) return;

    await user.notifications.notify({
        title: score.final ? `Final: ${ctx.label}` : ctx.label,
        text: `${score.home} - ${score.away}`,
        channel: 'scores',
        group: `game:${ctx.handle}`,
        target: `/games/${ctx.handle}`,
    });
});

The fan's page:

await puter.notifications.onPush('scores', (n) => ({
    title: n.title,
    body: n.text ?? '',
    url: n.target ?? '/',
}));

const subject = `kv:${handle}:score`;

async function findFollow () {
    const subs = await puter.events.list();
    return subs.find((sub) => sub.subject === subject && sub.handlerName === 'alertScore'
        && sub.suspendedReason !== 'permission_revoked');
}

async function followGame (alerts) {
    if (!await puter.perms.request('backgroundEvents')) return false;

    const context = { alerts, label, handle };
    const existing = await findFollow();
    if (existing) await puter.events.update(existing.subId, { context });
    else await puter.events.onPersistent({ subject, handlerName: 'alertScore', includeValue: true, context });
    return true;
}

async function unfollowGame () {
    const existing = await findFollow();
    if (existing) await puter.events.unsubscribe(existing.subId);
}

for (const alerts of ['final', 'goals']) {
    document.getElementById(`alert-${alerts}`).addEventListener('click', async () => {
        const pushes = await puter.notifications.enable();
        const following = await followGame(alerts);
        console.log(pushes && following ? `Alerts on: ${alerts}` : 'Alerts are off');
    });
}

The worker, at /puter-sw.js:

importScripts('https://js.puter.com/push-sw.js');
← All recipes