Guides

Send notifications

Copy page

Ask at the right moment, remember who said yes, send from your server, and open the right screen when a notification is tapped.

#1. Ask when it helps

game.js

async function waitForOpponent(room) {
  if (!Lia.notificationsAllowed) {
    try {
      const { allowed } = await Lia.requestNotifications();
      if (allowed) await api("/api/notify-me", { allowed: true });
    } catch (error) {
      // "notifications_off": your app can't send them; carry on without.
    }
  }
  showWaiting(room);
}

// They can also turn them on or off from your app's ⋯ menu.
Lia.on("notificationsChanged", function (data) {
  api("/api/notify-me", { allowed: data.allowed });
});

Lia doesn't tell your server when someone allows notifications, so tell it yourself, as above. Or keep it simpler: send when you have something to say, and treat not_allowed as a "no".

#2. Send from your server

server.js

async function notify(playerId, text, startParam) {
  try {
    return await lia("POST", "/notifications", { playerId, text, startParam });
  } catch (error) {
    const code = error.data?.error;
    if (code === "not_allowed") return db.setNotify(playerId, false); // they said no or stopped
    if (code === "rate_limited") return db.retryLater(playerId, error.data.retryAt); // retryAt may be missing
    if (code === "bad_text") console.warn("Lia refused the text:", error.data.problem);
    throw error;
  }
}

await notify(opponent, "@amara played. Your move.", "room-a81c2e09f4");

#3. Open the right screen

JavaScript

function route(startParam) {
  if (startParam?.startsWith("room-")) openRoom(startParam);
}
Lia.init().then(function () { route(Lia.startParam); Lia.ready(); });
Lia.on("startParam", function (data) { route(data.startParam); });

#Writing them

Up to 180 characters, one line. Lia shows it under your app's name, so don't start with it.
No links, phone numbers or scammy words. Lia refuses them with bad_text and a problem of link, phone or scam. The startParam is how you link into your app.
Make each one count. Your app can send one person 3 a day (unless the Lia team changed it), an hour apart, and all apps together 6 a day. Spend them on things the person wants to know.
Write in their language. Keep each player's Lia.language on your server when they open your app, and send in it.

#Testing

Testers get test notifications from your test key every 30 seconds and at least 20 a day, and they don't count toward their daily total from all apps. See Testing.