Манифест веб-приложения

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

Каждое PWA должно включать в себя один манифест для каждого приложения, который обычно размещается в корневой папке и связан со всеми HTML-страницами, с которых можно установить PWA. Его официальное расширение — .webmanifest , поэтому вы можете назвать свой манифест примерно так: app.webmanifest .

Добавление манифеста веб-приложения в PWA

Чтобы создать манифест веб-приложения, сначала создайте текстовый файл с объектом JSON, содержащим как минимум поле name со строковым значением:

приложение.вебманифест:

{
   "name": "My First Application"
}

Но создания файла недостаточно: браузеру также необходимо знать, что он существует.

Ссылка на ваш манифест

Чтобы браузер знал о манифесте вашего веб-приложения, вам необходимо связать его с вашим PWA с помощью HTML-элемента <link> и атрибута rel , установленного для manifest на всех HTML-страницах вашего PWA. Это похоже на то, как вы связываете таблицу стилей CSS с документом.

индекс.html:

<html lang="en">
  <title>This is my first PWA</title>
  <link rel="manifest" href="/app.webmanifest">

Отладка манифеста

Чтобы убедиться, что манифест настроен правильно, вы можете использовать Inspector в Firefox и DevTools в каждом браузере на базе Chromium.

Для браузеров Chromium

В инструментах разработчика

  1. На левой панели в разделе «Приложение» выберите «Манифест» .
  2. Проверьте поля манифеста, проанализированные браузером.

Для Firefox

  1. Откройте Инспектор.
  2. Перейдите на вкладку «Приложение».
  3. Выберите параметр «Манифест» на левой панели.
  4. Проверьте поля манифеста, проанализированные браузером.

Проектирование вашего опыта PWA

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

Основные поля

Первый набор полей представляет основную информацию о вашем PWA. Они используются для создания значка и окна установленного PWA и определения способа его запуска. Они есть:

name
Полное имя вашего PWA. Он появится вместе со значком на главном экране, панели запуска, доке или меню операционной системы.
short_name
Необязательно, более короткое имя вашего PWA, используемое, когда недостаточно места для отображения полного значения поля name . Не превышайте 12 символов, чтобы свести к минимуму возможность усечения.
icons
Массив объектов-значков с полями src , type , sizes и дополнительными purpose , описывающими, какие изображения должны представлять PWA.
start_url
URL-адрес, который PWA должен загрузить, когда пользователь запускает его с установленного значка. Рекомендуется указывать абсолютный путь, поэтому, если домашняя страница вашего PWA является корнем вашего сайта, вы можете установить для этого параметра значение «/», чтобы открывать ее при запуске приложения. Если вы не укажете начальный URL-адрес, браузер может использовать в качестве начального URL-адрес, с которого было установлено PWA. Это может быть глубокая ссылка, например сведения о продукте вместо главного экрана.
display
Один из fullscreen , standalone , minimal-ui или browser , описывающий, как ОС должна отображать окно PWA. Подробнее о различных режимах отображения вы можете прочитать в главе «Дизайн приложения» . В большинстве случаев использования реализуются standalone .
id
Строка, которая однозначно идентифицирует это PWA среди других, которые могут размещаться в том же источнике. Если он не установлен, start_url будет использоваться в качестве резервного значения. Имейте в виду, что, изменяя start_url в будущем (например, при изменении значения строки запроса), вы можете лишить браузер возможности обнаруживать, что PWA уже установлено.

Иконки

Значок вашего PWA — это его визуальная идентичность на устройствах ваших пользователей после установки, поэтому важно определить хотя бы один. Поскольку свойство icons представляет собой коллекцию объектов значков, вы можете определить несколько значков в разных форматах, чтобы обеспечить удобство работы со значками для ваших пользователей. Каждый браузер выберет один или несколько значков в зависимости от своих потребностей и операционной системы, в которой он установлен, значки будут ближе к необходимым спецификациям.

Если вам нужно выбрать только один размер значка, он должен быть 512 на 512 пикселей. Однако рекомендуется предоставить изображения большего размера, включая изображения размером 192 на 192, 384 на 384 и 1024 на 1024 пикселя.

"icons": [
   {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   }
]

Если вы не предоставите значок или значки не соответствуют рекомендуемым размерам, на некоторых платформах вы не пройдете критерии установки . На других платформах значок будет создан автоматически, например, на основе снимка экрана PWA или с использованием общего значка.

Маскируемые значки

Некоторые операционные системы, такие как Android, адаптируют значки к разным размерам и формам. Например, в Android 12 разные производители или настройки могут менять форму значков с кругов на квадраты или на квадраты с закругленными углами. Для поддержки таких типов адаптивных значков вы можете предоставить маскируемый значок, используя поле purpose .

Для этого предоставьте квадратный файл изображения, основной значок которого находится в «безопасной зоне» — круге с центром в значке и радиусом 40 процентов ширины значка. (См. изображение ниже.) Устройства, поддерживающие маскируемые значки, будут маскировать ваш значок по мере необходимости.

Безопасная зона отмечена кругом радиусом 40 процентов в центре квадратного значка.

Вот пример маскируемого значка, представленного в нескольких часто используемых формах:

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

Значок, который не подходит для маскируемого значка.

Это изображение можно было бы использовать с дополнительными отступами.

Значок с большим количеством полей подходит для масок.

Маскируемые значки должны иметь размер не менее 512 на 512 пикселей. Создав один из них, вы можете добавить его в свою коллекцию icons , чтобы улучшить взаимодействие с поддерживаемыми устройствами:

"icons": [
   {
      "src": "/icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "/icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   },
   {
      "src": "/icons/512-maskable.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "maskable"
   },
]

В большинстве случаев, если маскируемый значок отображается плохо, вы можете улучшить его, добавив дополнительные поля. Maskable.app — это бесплатный онлайн-инструмент для тестирования и создания маскируемой версии вашей иконки.

Если ваш значок служит общим и маскируемым целям, вы можете установить в поле purpose "any maskable" . Подробности см. в документации по манифесту веб-приложения MDN .

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

theme_color
Цвет по умолчанию для приложения, иногда влияющий на то, как ОС отображает сайт (например, цвет окна и строки заголовка на рабочем столе или цвет строки состояния на мобильных устройствах). Этот цвет может быть переопределен элементом HTML theme-color <meta> .
background_color
Цвет заполнителя, который будет отображаться в фоновом режиме приложения перед загрузкой его таблицы стилей. Safari на iOS и iPadOS, а также большинство настольных браузеров в настоящее время игнорируют это поле.
scope
Изменяет область навигации PWA, позволяя вам определить, что отображается, а что нет в окне установленного приложения. Например, если вы ссылаетесь на страницу за пределами области действия, она будет отображаться в браузере приложения, а не в окне PWA. Однако это не изменит область действия вашего сервис-воркера.

На следующем изображении показано, как поле theme_color используется для строки заголовка на настольном устройстве при установке PWA.

Тот же PWA, установленный на рабочем столе, с другим цветом темы.

При определении цветов в манифесте, например, в theme_color и background_color , вы должны использовать цвета с именами CSS, например, salmon или orange , цвета RGB, например #FF5500 , или цветовые функции без прозрачности, такие как rgb() или hsl() . Дополнительную информацию можно найти в главе «Дизайн приложения» .

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

Заставки

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

Android использует значения theme_color , background_color и icon для создания заставки.

Когда вы устанавливаете PWA на Android, устройство создает заставку с информацией, полученной из вашего манифеста, как показано на следующей схеме.

Заставка PWA на Android, принимающая разные значения из манифеста.

С другой стороны, Safari на iOS и iPadOS не использует манифест веб-приложения для создания заставок. Вместо этого они используют изображение, связанное с собственным элементом <link> аналогично тому, как они обрабатывают значки. Более подробную информацию можно найти в главе «Улучшение» .

Расширенные поля

Следующий набор полей предлагает дополнительную информацию о вашем PWA. Все они не являются обязательными.

lang
Языковой тег, определяющий основной язык значений манифеста, например en для английского, pt-BR для бразильского португальского языка или in для хинди.
dir
Направление отображения полей манифеста с поддержкой направления (таких как name , short_name description ). Допустимые значения: auto , ltr (слева направо) и rtl (справа налево).
orientation
Желаемая ориентация приложения после установки. Игра может настроить запрос только альбомной ориентации. Принимаются несколько значений , но если они включены, то обычно это явно portrait или landscape .

Рекламные поля

Четвертый набор полей позволяет вам предоставлять рекламную информацию о вашем PWA, например, в процессах установки, списках и результатах поиска.

description
Объяснение того, что делает PWA.
screenshots
Массив объектов скриншотов с src , type и sizes (аналогично объекту icons ), предназначенный для демонстрации PWA. Ограничений по размеру нет.
categories
Массив категорий, к которым должно принадлежать PWA, чтобы их можно было использовать в качестве подсказок для списков, при необходимости из списка известных категорий . Эти значения обычно пишутся строчными буквами.
iarc_rating_id
Код сертификации Международной коалиции возрастных рейтингов для PWA, если он у вас есть. Он предназначен для определения того, для какого возраста подходит ваше PWA.

Вы можете увидеть эти рекламные поля в действии уже сегодня. Например, на Android, если PWA можно установить и вы указали значения хотя бы для полей description и screenshots , диалоговое окно установки трансформируется из простой информационной панели «Добавить на главный экран» в более богатое диалоговое окно установки, подобное один из магазина приложений.

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

Посмотрите эти рекламные поля в действии:

Поля возможностей

Наконец, существует ряд полей, связанных с различными возможностями, которые ваш PWA может использовать в поддерживаемых браузерах, например поля shortcuts , share_target , display_override , о которых мы рассказываем в главе «Возможности» . Существуют также поля, такие как related_apps и prefer_related_apps (дополнительную информацию см. в главе «Обнаружение ») для подключения вашего PWA к установленным приложениям, часто из магазина приложений.

В будущем может появиться множество новых полей, когда браузеры добавят больше возможностей в Progressive Web Apps.

Ресурсы