Badging API: границы уведомлений PWA

Значок PWA может показать, что есть ожидающая работа, не открывая запрос разрешения, но это не канал доставки и не разрешение. BotBrowser способен повторить авторизованную страницу с navigator.setAppBadge() и navigator.clearAppBadge() и записать видимую ветвь возможностей; он не добавляет поддержку Badging API, не доставляет Web Push и не доказывает безопасность частного счётчика. Для потока через worker см. жизненный цикл и приватность Web Push; путь общего контента описан в Web Share Target PWA.

TL;DR

• setAppBadge() запрашивает число или точку на ярлыке приложения; clearAppBadge() удаляет это состояние.
• Значок является подсказкой отображения. Он не запрашивает разрешение уведомлений, не будит worker, не доставляет push и не подтверждает прочтение.
• Используйте ограниченный счётчик, полезный человеку. Уменьшайте большие значения, исключайте идентификаторы и чувствительные категории, очищайте после фактического подтверждения работы.
• Проверяйте navigator.setAppBadge и navigator.clearAppBadge; при отсутствии API показывайте честную запасную индикацию внутри приложения.
• Разделяйте badge, Notification, PushManager и серверные записи доставки.

Contents

• Определить контракт значка
• Выбрать число, точку и момент очистки
• Построить запасную индикацию
• Разделить значок, push и уведомления
• Минимизировать счётчики и проверить границы
• Practical conclusion

Определить контракт значка

Спецификация W3C Badging предоставляет setAppBadge() и clearAppBadge() у Navigator. Они относятся к представлению приложения в лаунчере или переключателе задач, а не к DOM. ОС может показать число, точку или ничего в зависимости от установки, браузера и настроек. Успешный promise означает принятие запроса браузером, а не подтверждение пикселей лаунчера.

Число должно суммировать работу, которую пользователь может выполнить. navigator.setAppBadge(3) не создаёт три уведомления и не доказывает получение трёх сообщений. Вызов без аргумента просит нечисловой badge. Точка подходит, когда точное значение неизвестно или излишне раскрывает данные. Справочники MDN для setAppBadge() и clearAppBadge() описывают API, но не обещают одинаковый вид на всех платформах.

Назначьте одного владельца состояния. Страница, worker и фоновая синхронизация не должны считать из разных снимков. Храните только source, countKind, count, updatedAt, revision и outcome; не сохраняйте заголовки, идентификаторы или текст. Устаревшая ревизия не должна вернуть 4 после очистки в другой вкладке.

Выбрать число, точку и момент очистки

Число 7 полезно, если направляет действие. Внутренние retries и скрытые события не являются работой пользователя. Ограничьте значение 99, затем используйте точку или собственную метку 99+. Обзор Badging API от Chrome показывает типичный сценарий PWA, но не определяет семантику продукта.

Очищайте при переходе состояния, а не по таймеру. Вызывайте clearAppBadge() после действия или авторитетной записи нового состояния. Открытие входящих не всегда означает прочтение. Если прочитано два из пяти элементов, получите 3 из авторитетного состояния, а не вычитайте два из кэша. Поздние вызовы должны отбрасываться по монотонной revision. При выходе, смене аккаунта или потере авторизации очистите badge и удалите локальное состояние аккаунта.

async function applyBadge(state) {
  const { revision, count, acknowledged, supported } = state;
  if (!supported || typeof navigator.setAppBadge !== 'function') {
    return { revision, outcome: 'unsupported', fallback: 'in-app-status' };
  }
  if (acknowledged || count === 0) {
    if (typeof navigator.clearAppBadge !== 'function') {
      return { revision, outcome: 'clear-unsupported', fallback: 'in-app-status' };
    }
    await navigator.clearAppBadge();
    return { revision, outcome: 'cleared' };
  }
  if (state.countKind === 'dot') {
    await navigator.setAppBadge();
    return { revision, outcome: 'dot' };
  }
  const bounded = Math.min(Math.max(0, count), 99);
  await navigator.setAppBadge(bounded);
  return { revision, outcome: 'number', count: bounded };
}

Построить запасную индикацию

Проверяйте оба метода при вызове:

const canBadge = 'setAppBadge' in Navigator.prototype && 'clearAppBadge' in Navigator.prototype;

Безопасный контекст, установленный режим, версия браузера, интеграция ОС и управляемая политика могут изменить результат. Руководство MDN Badging API описывает доступность, но не разрешает имитировать значок лаунчера изменением чужой иконки.

При отсутствии API показывайте тот же ограниченный статус в приложении: доступный счётчик, обновлённый заголовок или видимую метку. Сохраняйте ту же семантику очистки. Web Push не является запасным путём: ему нужны подписка, worker, разрешение и сервер, а фоновая доставка не гарантирована. Для поддержки достаточно { "capability": "absent", "fallback": "in-app-status" }; не записывайте текст приватного диалога.

Разделить значок, push и уведомления

API системных уведомлений запрашивает разрешение, а Badging API этого диалога не открывает. Web Push предоставляет возможность доставки через worker, а не состояние badge. MDN: API уведомлений, Push API и руководство Push MDN описывают разные поверхности.

Поверхность	Запрашивает	Не доказывает	Владелец
Badging API	локальное число или точку	пиксели, доставку, прочтение	согласованное состояние
System API	разрешение и системный экран	внимание или прочтение	страница или worker
Web Push	возможность доставки	время прихода или состояние	push и worker

Push может обновить минимизированную запись, а активная страница может согласовать badge. Число должно исходить из авторитетного unread-состояния, а не из количества push-событий. Не очищайте после показа уведомления: показ не является подтверждением.

Минимизировать счётчики и проверить границы

Число на экране блокировки или в записи экрана раскрывает данные. Предпочтите точку, диапазон (1, 2-5, 6-20) или максимум. Считайте после авторизации и до вызова; не передавайте id пользователя или диалога как аргумент. Ограниченная запись ниже проверяет только выбор ветви:

const record = {
  fixtureId: 'badge-boundary-01',
  countKind: 'bounded',
  count: 3,
  revision: 18,
  outcome: 'pending',
};

try {
  if (typeof navigator.setAppBadge !== 'function') {
    record.outcome = 'unsupported';
  } else if (record.count === 0 && typeof navigator.clearAppBadge === 'function') {
    await navigator.clearAppBadge();
    record.outcome = 'cleared';
  } else if (record.count > 0) {
    await navigator.setAppBadge(Math.min(record.count, 99));
    record.outcome = 'number-requested';
  } else {
    record.outcome = 'clear-unsupported';
  }
} catch (error) {
  record.outcome = error.name === 'NotAllowedError' ? 'policy-error' : 'api-error';
}

Повторите fixture с присутствующими и отсутствующими методами, после подтверждения и после отклонённого promise. Сохраняйте browserVersion, context, revision, countKind и outcome, исключая данные аккаунта. BotBrowser может захватить эти ветви в авторизованном контексте; он не может заставить лаунчер рисовать число, выдать разрешение, доставить push или подтвердить безопасность реального счётчика. После изменения браузера, manifest или worker сравните первое изменившееся поле.

{
  "fixtureId": "badge-boundary-01",
  "context": "installed-pwa",
  "revision": 18,
  "countKind": "bounded",
  "requestedCount": 3,
  "outcome": "number-requested"
}

Публичные источники

• Спецификация W3C Badging
• MDN: Badging API
• MDN: Navigator.setAppBadge()
• MDN: Navigator.clearAppBadge()
• Chrome Developers: Badging API
• MDN: API уведомлений
• W3C Push API
• MDN: Push API
• MDN: PWA installation
• BotBrowser: согласованность автоматизации

Practical conclusion

Используйте setAppBadge() для ограниченного числа или точки, а clearAppBadge() после подтверждения либо согласования состояния. Проверяйте оба метода, держите доступную запасную индикацию и записывайте только возможности, ревизию и результат. Badge, разрешение уведомлений и доставка Web Push независимы. BotBrowser повторяет синтетическую машину состояний, но лаунчер и решение о приватности находятся за пределами fixture. Сначала определите владельца счётчика и событие очистки.