Skip to content

Push notification guidelines ​

A push takes attention from outside the tile. Send one when this person would want their phone to ring: it is their turn, someone acted on them (invited, mentioned, challenged, beat their record), or something they asked to hear about happened. For anything else, update the preview or the unread count instead. People who get noise mute the room or turn off the app's notifications for good.

What the platform already does ​

  • Some pushes are automatic. setTurn pushes the new turn-holder, notifyUsersAddedToTile pushes the people you add, and setLeaderboardScore pushes the other active members on a new high score unless you pass { notifyOnHighScore: false }. Do not add a notifyActivity({ push }) for the same event. To use your own copy or audience, turn the automatic push off first.
  • notifyActivity does not push the sender for their own action. It removes the sender's push, and so do notifyUsersAddedToTile and the setLeaderboardScore high-score notify. Do not write your own filter for these calls.
  • setTurn pushes each person it marks, the caller too. Any mutator whose next turn-holder can be the person who acted must pass push: false when that turn-holder is ctx.userId. Examples: a start, reset, rematch or seat claim where the opener moves first, and a pass, skip, timeout or forfeit that gives the turn back.
  • One push value applies to every user in a setTurn call. To mark a set that includes the caller (a simultaneous turn), mark the others first with a push, then mark the caller with setTurn(ctx, { userIds: [ctx.userId], replace: false, push: false }).
  • The app hides a push from a person who is using it. It shows an in-app banner instead, unless the person already looks at this tile. A muted room gets neither. Do not check presence yourself.
  • A mutation can run more than once. Send the push from the mutation that commits the event, and only when the state changed, so a replay does not push again.

Rules ​

  1. One push per event per person.
  2. Send to the smallest audience that cares: the next player, the invited or mentioned person, the person whose record fell. Push to every member only when each one would act on it or would be sorry to miss it. In a large room, a push for each member's result is noise; use unread: "increment" without push for it.
  3. Never throttle, batch, delay, or merge the turn push. A player whose turn it is gets a push every time, in every match.
  4. No timers that push again and again. A nudge is one action by a waiting player, with a cooldown that the server enforces, and it stops when the turn changes. Never push again only because the earlier push was not opened.
  5. No generic "come back and play" pushes.
  6. Say what happened and why it matters to this person. "Jacob took your bishop" is better than "It's your turn."

Before you finish ​

Tell the creator each push the tile can send, who gets it, and about how many one busy person can get in a day across all their rooms.