Установка на домашний экран (A2HS)

Урок объясняет, как PWA устанавливается на домашний экран и как показать собственную кнопку установки.

A2HS (Add to Home Screen) — добавление PWA на домашний экран устройства, после чего оно запускается как обычное приложение, по иконке.

Как происходит установка

Когда сайт соответствует критериям PWA, браузеры на базе Chromium генерируют событие beforeinstallprompt. По умолчанию браузер сам может показать ненавязчивую подсказку об установке. Но чаще разработчики перехватывают это событие, чтобы показать свою кнопку «Установить» в удобном месте и в удобный момент.

Перехват события и кнопка

let deferredPrompt = null;

window.addEventListener('beforeinstallprompt', function (e) {
  e.preventDefault();          // отменяем авто-подсказку браузера
  deferredPrompt = e;          // сохраняем событие на потом
  showInstallButton();         // показываем свою кнопку
});

installButton.addEventListener('click', async function () {
  deferredPrompt.prompt();     // показываем системный диалог установки
  const choice = await deferredPrompt.userChoice;
  console.log('Пользователь выбрал:', choice.outcome); // 'accepted' | 'dismissed'
  deferredPrompt = null;
});

Код помечен language-text: он завязан на браузерное событие и DOM-элемент кнопки, в песочнице не исполняется. Важно: prompt() можно вызвать только в ответ на действие пользователя (клик) — нельзя показать диалог установки «сам по себе».

Событие appinstalled

После установки срабатывает событие appinstalled — туда удобно повесить аналитику или спрятать кнопку установки:

window.addEventListener('appinstalled', function () {
  hideInstallButton();
  console.log('PWA установлено');
});

Разные платформы

На iOS события beforeinstallprompt нет, поэтому показывают инструкцию: «нажмите Поделиться и выберите На экран Домой». Это типичная развилка, о которой нельзя забывать.

Как работает под капотом отложенный prompt

Зачем сохранять событие в deferredPrompt, а не вызывать prompt() сразу? Чтобы выбрать момент. Показывать диалог установки прямо на входе — навязчиво, многие закроют. Лучше дождаться, пока пользователь что-то сделал в приложении и заинтересовался, и только тогда предложить установку. Сохранённое событие позволяет вызвать диалог позже, по клику на вашу кнопку.

Частые ошибки

• Вызвать prompt() без клика. Браузер заблокирует — диалог можно показывать только по жесту пользователя.
• Не обрабатывать iOS. Там нет события установки; нужна ручная инструкция.
• Не скрывать кнопку после установки. Кнопка «Установить» висит у уже установленного приложения.
• Показывать установку слишком рано. Высокий процент отказов; лучше предлагать в подходящий момент.

Итоги

• Установку на Chromium запускает событие beforeinstallprompt; его перехватывают и сохраняют.
• Диалог prompt() вызывают только по клику пользователя.
• Событие appinstalled сигнализирует об успешной установке.
• На iOS события нет — нужна ручная инструкция «На экран Домой».