Бейджи для значков приложений

API App Badging позволяет установленным веб-приложениям устанавливать значок на значке приложения.

Пит ЛеПейдж

Что такое API для маркировки приложений?

Пример Twitter с восемью уведомлениями и другим приложением, отображающим значок в виде флага.
Пример Twitter с восемью уведомлениями и другим приложением, отображающим значок в виде флага.

API App Badging позволяет установленным веб-приложениям устанавливать значок для всего приложения, отображаемый в определенном месте операционной системы, связанном с приложением (например, на полке или главном экране).

С помощью значков можно легко уведомить пользователя о наличии новой активности, которая может потребовать его внимания, или указать небольшой объем информации, например количество непрочитанных сообщений.

Значки, как правило, удобнее для пользователя, чем уведомления, и могут обновляться гораздо чаще, поскольку не отвлекают пользователя. И, поскольку они не отвлекают пользователя, им не требуется его разрешение.

Возможные варианты использования

Примеры приложений, которые могут использовать этот API:

  • Чат, электронная почта и социальные приложения, чтобы сообщать о поступлении новых сообщений или показывать количество непрочитанных сообщений.
  • Приложения для повышения производительности, сигнализирующие о завершении длительной фоновой задачи (например, рендеринга изображения или видео).
  • В играх — для подачи сигнала о необходимости действия игрока (например, в шахматах, когда наступает очередь игрока).

Поддерживать

API App Badging работает в Windows и macOS, в Chrome 81 и Edge 81 и более поздних версиях. Поддержка ChromeOS находится в разработке и будет доступна в будущем выпуске. На Android API Badging не поддерживается. Вместо этого Android автоматически отображает значок на значке установленного веб-приложения при наличии непрочитанного уведомления, как и для приложений Android.

Попробуй это

  1. Откройте демонстрационную версию API App Badging .
  2. При появлении запроса нажмите «Установить» , чтобы установить приложение, или используйте меню Chrome для его установки.
  3. Откройте его как установленное PWA. Обратите внимание: оно должно быть запущено как установленное PWA (на панели задач или в доке).
  4. Нажмите кнопку «Установить» или «Очистить» , чтобы установить или убрать значок на значке приложения. Вы также можете указать числовое значение для значка .

Как использовать API для маркировки приложений

Чтобы использовать API App Badging, ваше веб-приложение должно соответствовать критериям установки Chrome , а пользователи должны добавить его на свои домашние экраны.

API значка состоит из двух методов navigator :

  • setAppBadge( number ) : устанавливает значок приложения. Если указано значение, установите для значка указанное значение, в противном случае отобразите простую белую точку (или другой флаг, соответствующий платформе). Установка number в 0 эквивалентна вызову clearAppBadge() .
  • clearAppBadge() : удаляет значок приложения.

Оба возвращают пустые обещания, которые можно использовать для обработки ошибок.

Значок можно установить как на текущей странице, так и в зарегистрированном сервис-воркере. Чтобы установить или снять значок (на активной странице или в сервис-воркере), вызовите:

// Set the badge
const unreadCount = 24;
navigator.setAppBadge(unreadCount).catch((error) => {
  //Do something with the error.
});

// Clear the badge
navigator.clearAppBadge().catch((error) => {
  // Do something with the error.
});

В некоторых случаях операционная система может не поддерживать точное отображение значка. В таких случаях браузер попытается предоставить наилучшее представление для данного устройства. Например, поскольку API Badging не поддерживается на Android, Android всегда отображает только точку вместо числового значения.

Не делайте никаких предположений о том, как пользовательский агент отобразит значок. Некоторые пользовательские агенты могут взять число, например, «4000», и переписать его как «99+». Если вы сами заполните значок (например, установив его равным «99»), то «+» не появится. Независимо от фактического числа, просто вызовите setAppBadge(unreadCount) и позвольте пользовательскому агенту отобразить его соответствующим образом.

Хотя API App Badging в Chrome требует установленного приложения, не следует вызывать его в зависимости от состояния установки. Вызывайте API, когда он существует, так как другие браузеры могут отображать значок в других местах. Если работает, значит работает. Если нет, значит просто нет.

Установка и очистка значка в фоновом режиме от сервисного работника

Вы также можете установить значок приложения в фоновом режиме с помощью сервис-воркера. Это можно сделать либо с помощью периодической фоновой синхронизации, либо через Push API, либо с помощью комбинации этих двух методов.

Периодическая фоновая синхронизация

Периодическая фоновая синхронизация позволяет сервисному работнику периодически опрашивать сервер, что можно использовать для получения обновленного статуса, и вызывать navigator.setAppBadge() .

Однако частота, с которой вызывается синхронизация, не совсем надежна и вызывается по усмотрению браузера.

API веб-Push

API Push позволяет серверам отправлять сообщения сервис-воркерам, которые могут выполнять код JavaScript, даже когда активная страница не запущена. Таким образом, серверная push-загрузка может обновить значок, вызвав navigator.setAppBadge() .

Однако большинство браузеров, включая Chrome, требуют отображения уведомления при получении push-уведомления. Это приемлемо для некоторых случаев (например, для отображения уведомления при обновлении значка), но делает невозможным незаметное обновление значка без отображения уведомления.

Кроме того, для получения push-уведомлений пользователи должны предоставить вашему сайту разрешение на получение уведомлений.

Комбинация обоих

Хотя это и не идеальное решение, совместное использование Push API и периодической фоновой синхронизации обеспечивает хорошее решение. Высокоприоритетная информация доставляется через Push API, отображая уведомления и обновляя значок. Менее приоритетная информация доставляется путём обновления значка либо при открытии страницы, либо посредством периодической фоновой синхронизации.

Обратная связь

Команда Chrome хочет узнать о вашем опыте работы с API App Badging.

Расскажите нам о дизайне API

Есть ли что-то в API, что работает не так, как вы ожидали? Или отсутствуют методы или свойства, необходимые для реализации вашей идеи? У вас есть вопросы или комментарии по модели безопасности?

  • Отправьте сообщение о проблеме со спецификацией в репозиторий GitHub Badging API или добавьте свои мысли к существующей проблеме.

Сообщить о проблеме с реализацией

Вы обнаружили ошибку в реализации Chrome? Или реализация отличается от спецификации?

  • Сообщите об ошибке по адресу https://new.crbug.com . Опишите её как можно подробнее, предоставьте простые инструкции по воспроизведению и выберите в качестве компонентов UI>Browser>WebAppInstalls .

Показать поддержку API

Планируете использовать API App Badging на своём сайте? Ваша публичная поддержка помогает команде Chrome расставлять приоритеты в функциях и показывает другим разработчикам браузеров, насколько важна их поддержка.

  • Отправьте твит @ChromiumDev , используя хэштег #BadgingAPI и расскажите, где и как вы его используете.

Полезные ссылки

Героическое фото Пратика Катьяла на Unsplash