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

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

Пит ЛеПейдж

Что такое API значков приложений?

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

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

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

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

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

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

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

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

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

Попробуйте это

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

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

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

API Badge состоит из двух методов 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 значков не поддерживается в Android, Android отображает только точку вместо числового значения.

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

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

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

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

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

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

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

Веб-пуш API

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

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

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

Сочетание того и другого

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

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

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

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

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

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

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

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

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

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

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

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

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

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