Благодарим за настройку Google I/O! Смотрите контент по запросу .

Эта страница переведена с помощью Cloud Translation API.

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

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

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

Примечание. Хотя рекомендуемым расширением является .webmanifest , любое имя файла будет работать, если оно поставляется с типом контента application/manifest+json или другим типом контента, допустимым в формате JSON, например text/json . Таким образом, многие PWA, особенно старые, вместо этого используют manifest.json .

Добавление манифеста веб-приложения в 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.

Если вы видите сообщение о том, что браузер не обнаружил манифеста и вы правильно включили в него <link> , убедитесь, что вы можете загрузить манифест в браузере и правильно ли установлен его тип контента. Вы также можете попробовать переименовать его в manifest.json .

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

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

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

Для Firefox

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

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

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

Предупреждение. До того, как была определена спецификация манифеста веб-приложения, несколько браузеров, включая Safari на iOS/iPadOS и Chrome на Android, поддерживали пользовательские элементы <meta> для описания работы приложения, например apple-mobile-web-app-capable . Не используйте эти элементы <meta> сегодня; это больше не рекомендуется и может навредить процессу установки, если браузер не сможет правильно загрузить манифест; опыт, который вы получите в качестве запасного варианта, может быть разным и неожиданным.

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

Первый набор полей представляет основную информацию о вашем 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 до сентября 2021 года, прочтите рекомендации по добавлению свойства id сейчас в разделе Уникальная идентификация PWA с помощью свойства id манифеста веб-приложения .

Иконки

Значок вашего 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 .

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

Следующий набор полей предлагает дополнительную информацию о вашем 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.