For AI agents: llms.txt is a short guide that sends you to the rules your problem needs, and rules.json holds every rule of this playbook as JSON.

How to do it

Subscribe with userVisibleOnly: true, which the Push API uses to promise that every push is made visible. Safari does not support invisible pushes, and it revokes the site's permission when a push shows nothing. On Android, FCM may lower the priority of high-priority messages that show no notification. So call showNotification() inside event.waitUntil(), even when the payload is empty or the item is already read. Then show a short line such as "You have new activity". Fetch other data when the app opens instead. The full text lives in the server-side inbox.

Examples

Using these examples: they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

JavaScript example

self.addEventListener('push', event => {
  const message = readPayload(event.data);
  event.waitUntil(self.registration.showNotification(message.title ?? 'You have new activity', {
    body: message.body ?? '',
    tag: message.topic,
    data: { path: message.path ?? '/notifications' },
  }));
});

function readPayload(data) {
  try { return data?.json() ?? {}; } catch { return {}; }
}

Python example

def fcm_message(token: str, title: str, body: str, high_priority: bool) -> dict:
    message = {"token": token, "notification": {"title": title, "body": body}}
    if high_priority:
        message["android"] = {"priority": "high"}
    return {"message": message}

def test_high_priority_messages_are_visible():
    for kind in PUSH_TEMPLATES:
        message = render_fcm(kind, SAMPLE_DATA[kind])["message"]
        if message.get("android", {}).get("priority") == "high":
            assert "notification" in message

How to check

A unit test runs the service worker's push handler with a normal payload, an empty payload and a broken payload. Each run calls showNotification once. A server test finds no high-priority FCM message without a notification block.

Sources

• W3C Push API
• Apple, Sending web push notifications in web apps and browsers
• Firebase, Android message priority

Related rules

• Store every notification in a server-side inbox in Notifications