Руководство по манифесту веб-приложения
Манифест веб-приложения (site.webmanifest) — это файл JSON, который сообщает устанавливаемым браузерам имя вашего приложения, цвета, режим отображения и размеры значков, которые следует использовать на главном экране. Связывание его с помощью `<link rel='manifest' href='/site.webmanifest'>` включает приглашение на установку Chrome и Edge PWA на рабочем столе и Android. Соедините его с значками PNG размером 192×192 и 512×512 — оба экспортированы favicon generator — для полной настройки значка PWA.
Манифест веб-приложения представляет собой текстовый файл JSON, обслуживаемый с MIME-типом `application/manifest+json`. Он размещается по любому URL-адресу, который вы выберете, но соглашением является /site.webmanifest в корне домена. Вы связываете его с HTML, используя `<link rel='manifest' href='/site.webmanifest'>` внутри элемента `<head>`. Браузер считывает манифест, когда оценивает, показывать ли приглашение на установку или как отобразить приложение после установки.
Массив значков — это наиболее важная часть манифеста, связанная с значками. Каждая запись определяет источник (URL-адрес изображения), размеры (размеры в пикселях), тип (тип MIME) и, возможно, цель («любой», «маскируемый» или «любой маскируемый»). Укажите как минимум 192×192 PNG для значка запуска и 512×512 PNG для заставки. Без них Chrome не будет отображать приглашение на установку.
Значок размером 192×192 используется Android Chrome в средстве запуска приложений, переключателе последних приложений и на панели уведомлений, когда PWA отправляет push-уведомление через Интернет. Это должен быть PNG, доступный по объявленному URL-адресу без перенаправлений и обслуживаемый с правильными заголовками CORS, если он находится в домене, отличном от вашего манифеста. favicon generator экспортирует android-chrome-192x192.png, готовый к прямому использованию.
Значок размером 512×512 используется для заставки PWA, отображаемой при загрузке приложения после запуска на главном экране, предварительного просмотра диалогового окна установки в Chrome и Edge на рабочем столе, а также средства запуска приложения Chrome ОС. Отсутствие записи размером 512×512 в манифесте не блокирует установку, но приводит к появлению общего значка браузера на заставке. Всегда включайте его для более удобной установки.
Маскируемые значки — это усовершенствование, специфичное для Android. Адаптивная система значков Android применяет к значкам приложений геометрические маски (круг, прямоугольник, капля, скругленный прямоугольник), форма которых зависит от производителя устройства. Края стандартного «любого» значка могут быть обрезаны этими масками. «Маскируемый» значок включает в себя отступы безопасной зоны — основные изображения должны находиться в пределах 80% центра изображения (круг безопасной зоны) — чтобы можно было применить любую маску без обрезки логотипа.
Чтобы объявить маскируемый значок в манифесте, добавьте вторую запись того же размера с `'purpose': 'maskable'`: `{ "src": "/android-chrome-512x512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }`. Вы также можете объединить: `'purpose': 'any maskable'` в одной записи. Создайте маскируемый значок с дополнительными отступами, используя опцию маскируемого экспорта генератора.
Поля name и short_name определяют, как ваше приложение будет помечено на главном экране и в панели приложений. `name` — это полное имя приложения, отображаемое во время запроса на установку. `short_name` — это метка под значком на главном экране. Не превышайте 12 символов, чтобы избежать усечения на экранах меньшего размера. Оба поля необходимы для появления приглашения на установку.
Поле theme_color устанавливает цвет адресной строки браузера Android Chrome, когда пользователь переходит на ваш сайт (а не только тогда, когда установлен PWA). Он также устанавливает цвет панели инструментов в автономном режиме PWA. Используйте основной цвет бренда в качестве шестнадцатеричного значения. Добавьте соответствующий `<meta name='theme-color' content='#YOUR_COLOR'>` в свой HTML для браузеров, которые не читают theme_color манифеста.
Поле background_color управляет цветом фона экрана-заставки, отображаемым между запуском PWA и первой отрисовкой содержимого вашего приложения. Установите его в соответствии с фоном вашего приложения (обычно белым или основным цветом бренда), чтобы избежать резкой вспышки. Если цвет фона не соответствует фактическому фону вашего приложения, пользователи увидят скачок цвета во время запуска.
Поле отображения определяет, как PWA будет выглядеть после установки. `standalone` скрывает адресную строку браузера и кнопки навигации, благодаря чему приложение выглядит как родное. `minimal-ui` сохраняет минимальную панель навигации. `fullscreen` удаляет все, включая строку состояния. `browser` показывает полный пользовательский интерфейс браузера. Для большинства PWA правильным выбором является `standalone`. Приглашение на установку не появляется, если для дисплея установлено значение `browser`.
Поле start_url указывает, какой URL-адрес открывается, когда пользователь запускает установленный PWA с главного экрана. Всегда включайте это — без него Android открывает URL-адрес, по которому был обнаружен манифест, который может быть страницей с глубокими ссылками, а не вашей домашней страницей. Используйте `'start_url': '/'` для большинства сайтов или конкретный URL-адрес, если ваше приложение должно запускаться по определенному маршруту.
Отладка проблем манифеста в Chrome DevTools проста. Откройте DevTools (F12), перейдите на вкладку «Приложение» и нажмите «Манифест» на левой панели. Chrome показывает проанализированное представление вашего манифеста, все ошибки анализа, сбои при получении значков, а также контрольный список «Устанавливаемость», в котором объясняется, почему может не отображаться приглашение на установку. Общие проблемы включают в себя не найденные значки (404), неправильный тип MIME или отсутствие значка 192×192.
Для корректной подачи манифеста требуются две конфигурации на стороне сервера. Во-первых, файл должен быть отправлен с `Content-Type: application/manifest+json`. Во-вторых, если ваши значки находятся в CDN или имеют другое происхождение, чем в манифесте, ответы значков должны включать соответствующие заголовки CORS (`Access-Control-Allow-Origin: *` или ваш домен). Отсутствие заголовков CORS в файлах значков приведет к тому, что браузер будет считать манифест недействительным.
Для платформ, которые автоматически создают манифест, убедитесь, что сгенерированный файл содержит фактические размеры и цвета значков. Next.js создает манифест на основе экспорта /app/manifest.ts. Приложение Create React создает файл /public/manifest.json. Vite не генерирует манифест по умолчанию — создайте его вручную. В любом случае обновите массив значков, чтобы он ссылался на фактические файлы фирменных значков, а не на значки-заполнители по умолчанию.
Как это работает
- 1
Создание значков PNG размером 192×192 и 512×512.
Загрузите свой логотип PNG или SVG размером 512×512 на [favicon generator](tool:favicon-generator). В пакет загрузки входят файлы android-chrome-192x192.png и android-chrome-512x512.png, готовые к прямому использованию.
- 2
Создать site.webmanifest
Создайте файл JSON с минимумом: `name`, `short_name`, `icons` (192 и 512 записей), `theme_color`, `background_color` и `display: 'standalone'`. Пакет генератора включает предварительно заполненный шаблон манифеста.
- 3
Отправьте манифест с правильным типом MIME.
Настройте свой сервер для обслуживания файлов .webmanifest с `Content-Type: application/manifest+json`. В Apache добавьте `AddType application/manifest+json .webmanifest` в .htaccess. В Nginx добавьте тип MIME в mime.types.
- 4
Свяжите манифест в HTML
Добавьте `<link rel='manifest' href='/site.webmanifest'>` внутри вашего `<head>`. Также добавьте <meta name='theme-color' content='#YOUR_COLOR'> для браузеров, которые не читают манифест theme_color.
- 5
Проверьте с помощью Chrome DevTools.
Откройте Chrome DevTools > Приложение > Манифест. Убедитесь, что ошибки не отображаются и все значки исчезли. Проверьте раздел «Установка», чтобы узнать, какие именно критерии соответствуют или не выполняются для запроса на установку PWA.
- 6
Проверьте приглашение на установку
На Android Chrome перейдите на свой сайт. Если все критерии соблюдены, Chrome отображает баннер установки или опцию «Добавить на главный экран» в меню браузера. После установки убедитесь, что цвет фона заставки и значок главного экрана отображаются правильно.
Попробовать сейчас
Создайте пакет значков PWA.
Генератор фавиконовЧастые вопросы
Требуется ли манифест веб-приложения для базового веб-сайта?+
Нет — только если вы хотите, чтобы на рабочем столе Android и Chrome/Edge на рабочем столе отображался запрос на установку PWA на главном экране. Только favicon.ico обрабатывает вкладки браузера. Добавьте манифест, если хотите расширить возможности установки на мобильных устройствах и настольных компьютерах.
Какие размеры значков указаны в манифесте веб-приложения?+
Минимум: 192×192 (лаунчер Android) и 512×512 (заставка и предварительный просмотр установки). Добавьте маскируемые варианты обоих размеров для адаптивной поддержки значков Android и 384×384, если вам требуется дополнительная плотность покрытия.
В чем разница между theme_color и background_color в манифесте?+
theme_color устанавливает цвет адресной строки браузера и панели инструментов. Background_color устанавливает цвет фона экрана-заставки, отображаемый перед первой отрисовкой вашего приложения. Настройте оба варианта в соответствии с вашим брендом, чтобы обеспечить беспрепятственную установку и запуск.
Почему Chrome не отображает приглашение на установку моего PWA?+
Наиболее распространенные причины: отсутствие или недействительный манифест, отсутствие значка 192×192, значки, возвращающие 404, манифест не обслуживается с правильным типом MIME или сайт не обслуживается по HTTPS. Используйте Chrome DevTools > Приложение > Манифест, чтобы узнать точную причину сбоя при установке.
Что такое маскируемый значок и нужен ли он мне?+
Маскируемый значок включает в себя отступы безопасной зоны, поэтому Android может применять круглые или изогнутые маски, не обрезая логотип. Он нужен вам, чтобы значок на главном экране выглядел правильно на устройствах Android, в которых используются неквадратные адаптивные формы значков. Объявите его с помощью `'purpose': 'maskable'` в массиве значков манифеста.
Могу ли я использовать значки SVG в манифесте веб-приложения?+
Chromium поддерживает SVG в некоторых контекстах значков манифеста, но PNG является универсальным безопасным значением по умолчанию для пользовательских интерфейсов кросс-браузерной установки. Всегда включайте записи PNG 192 и 512. Вы можете добавить к ним запись SVG без какого-либо вреда.
Как проверить, действителен ли мой веб-манифест?+
Откройте Chrome DevTools (F12) > Приложение > Манифест. Chrome отображает ошибки анализа, сбои при получении значков и полный контрольный список установки. Устраните все обнаруженные проблемы, а затем повторно проверьте приглашение на установку, используя опцию «Добавить на главный экран» в адресной строке Chrome.