Concepts

Players choose whether your app may notify them. Your server sends each notification, within limits Lia sets so the people who say yes stay glad they did.

#How they work

1. The person allows themYour page calls Lia.requestNotifications() at a good moment, and Lia asks in its own sheet. People can also turn your app's notifications on or off from its ⋯ menu.
2. Your server sends onePOST /notifications with the player's id, the text and an optional startParam.
3. It reaches their phoneUnder your app's name, as a push and in Lia's bell. Tapping it opens your app with your startParam.

#Asking

Ask when a notification would clearly help the person: their turn in a game, a delivery, a friend joining. Don't ask the moment your app opens.

if (!Lia.notificationsAllowed) {
  const { allowed } = await Lia.requestNotifications();
  if (allowed) tellYourServer(); // so it knows it may notify this player
}

• If they already allowed them, requestNotifications() answers { allowed: true } without asking.
• If your app may not send notifications at all (the Lia team turned them off), it fails with notifications_off.
• Lia.notificationsAllowed says where things stand, and the notificationsChanged event fires when the person changes it, from your ask or the ⋯ menu.

Lia doesn't tell your server when someone allows or stops notifications. Tell it yourself, or just send and handle not_allowed.

#Sending

{ "playerId": "p_3f9c0a6d1b2e4f5a6b7c", "text": "It's your move against @amara.", "startParam": "match-8k2d" }

See POST /notifications for every field and answer.

#Limits

Notifications are a privilege people give your app, so Lia keeps them few:

When a limit is reached, POST /notifications answers 429 rate_limited. For your app's own limits it also says when you may try again, as retryAt (milliseconds since 1970).

"A day" is the last 24 hours for your app's limits, and the person's calendar day for the total from all apps.

#Opening your app from one

A notification opens your app with its startParam (1 to 64 of letters, digits, _ and -), which your page reads from Lia.startParam. If your app is already open when the person taps it, your page hears a startParam event instead.

function route(param) {
  if (param && param.startsWith("match-")) openMatch(param);
}
Lia.init().then(function () { route(Lia.startParam); Lia.ready(); });
Lia.on("startParam", function (data) { route(data.startParam); });

#Pushes and the bell

Every notification goes to Lia's bell. It's also pushed to the person's phone when they have Lia's pushes on; POST /notifications answers pushed: false when it only reached the bell.