Alert Users When Shared Data Changes
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');