Как предоставить собственный опыт установки в приложении

Pete LePage

Многие браузеры позволяют включать и продвигать установку вашего прогрессивного веб-приложения (PWA) непосредственно в его пользовательском интерфейсе. Установка (ранее называемая «Добавить на главный экран») позволяет пользователям устанавливать PWA на свое мобильное или настольное устройство. При установке PWA оно добавляется в панель запуска пользователя и может работать как любое другое установленное приложение.

В дополнение к возможности установки через браузер вы можете создать собственный процесс установки непосредственно в приложении.

Кнопка «Установить приложение» в Spotify PWA.

При рассмотрении вопроса о том, продвигать ли установку, подумайте, как пользователи обычно используют ваше PWA. Например, если есть группа пользователей, которые используют ваше PWA несколько раз в неделю, эти пользователи могут извлечь выгоду из дополнительного удобства запуска вашего приложения с главного экрана телефона или из меню «Пуск» в операционной системе настольного компьютера. Некоторые приложения для повышения производительности и развлечений также получают выгоду от дополнительного пространства на экране, создаваемого за счет удаления панелей инструментов браузера из окна в установленных режимах standalone , minimal-ui или режима window-control-overlay .

Предварительные условия

Прежде чем приступить к работе, убедитесь, что ваше PWA соответствует требованиям к установке , которые обычно включают наличие манифеста веб-приложения .

Продвигать установку

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

1. Прослушайте событие beforeinstallprompt .
2. Сохраните событие beforeinstallprompt , чтобы оно могло запустить процесс установки позже.
3. Сообщите пользователю, что ваше PWA можно установить, и предоставьте кнопку или другой элемент для запуска процесса установки в приложении.

Примечание. Событие beforeinstallprompt и событие appinstalled были перенесены из спецификации манифеста веб-приложения в отдельный инкубатор . Команда Chrome по-прежнему привержена их поддержке и не планирует прекращать или прекращать поддержку. Команда Google Web DevRel по-прежнему рекомендует использовать их для обеспечения индивидуальной установки.

Слушайте событие beforeinstallprompt

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

// Initialize deferredPrompt for use later to show browser install prompt.
let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent the mini-infobar from appearing on mobile
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  // Update UI notify the user they can install the PWA
  showInstallPromotion();
  // Optionally, send analytics event that PWA install promo was shown.
  console.log(`'beforeinstallprompt' event was fired.`);
});

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

Процесс установки в приложении

Чтобы обеспечить установку в приложении, предоставьте кнопку или другой элемент интерфейса, на который пользователь может нажать или коснуться, чтобы установить ваше приложение. Когда элемент щелкнут или коснется, вызовите prompt() для сохраненного события beforeinstallprompt (хранящегося в переменной deferredPrompt ). Он показывает пользователю модальное диалоговое окно установки, в котором ему предлагается подтвердить, что он хочет установить PWA.

buttonInstall.addEventListener('click', async () => {
  // Hide the app provided install promotion
  hideInstallPromotion();
  // Show the install prompt
  deferredPrompt.prompt();
  // Wait for the user to respond to the prompt
  const { outcome } = await deferredPrompt.userChoice;
  // Optionally, send analytics event with outcome of user choice
  console.log(`User response to the install prompt: ${outcome}`);
  // We've used the prompt and can't use it again, throw it away
  deferredPrompt = null;
});

Свойство userChoice — это обещание, которое разрешается по выбору пользователя. Вы можете вызвать prompt() для отложенного события только один раз. Если пользователь отклоняет его, вам придется подождать, пока событие beforeinstallprompt не сработает снова, обычно сразу после разрешения свойства userChoice .

Попробуйте: сделайте сайт доступным для установки с помощью события beforeinstallprompt .

Определить, когда PWA было успешно установлено

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

window.addEventListener('appinstalled', () => {
  // Hide the app-provided install promotion
  hideInstallPromotion();
  // Clear the deferredPrompt so it can be garbage collected
  deferredPrompt = null;
  // Optionally, send analytics event to indicate successful install
  console.log('PWA was installed');
});

Узнайте, как был запущен PWA

Медиа display-mode CSS указывает, как PWA было запущено: либо на вкладке браузера, либо как установленное PWA. Это позволяет применять разные стили в зависимости от того, как приложение было запущено. Например, вы можете настроить его так, чтобы кнопка установки всегда скрывалась и отображалась кнопка «Назад» при запуске установленного PWA.

Отслеживайте, как был запущен PWA

Чтобы отслеживать, как пользователи запускают ваше PWA, используйте matchMedia() для проверки медиа-запроса display-mode .

function getPWADisplayMode() {
  if (document.referrer.startsWith('android-app://'))
    return 'twa';
  if (window.matchMedia('(display-mode: browser)').matches)
    return 'browser';
  if (window.matchMedia('(display-mode: standalone)').matches || navigator.standalone)
    return 'standalone';
  if (window.matchMedia('(display-mode: minimal-ui)').matches)
    return 'minimal-ui';
  if (window.matchMedia('(display-mode: fullscreen)').matches)
    return 'fullscreen';
  if (window.matchMedia('(display-mode: window-controls-overlay)').matches)
    return 'window-controls-overlay';

  return 'unknown';
}

Отслеживайте, когда меняется режим отображения

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

// Replace "standalone" with the display mode used in your manifest
window.matchMedia('(display-mode: standalone)').addEventListener('change', () => {
  // Log display mode change to analytics
  console.log('DISPLAY_MODE_CHANGED', getPWADisplayMode());
});

Обновить пользовательский интерфейс в зависимости от текущего режима отображения.

Чтобы применить другой цвет фона для PWA при запуске в качестве установленного PWA, используйте условный CSS:

@media all and (display-mode: standalone) {
  body {
    background-color: yellow;
  }
}

Обновите значок и название вашего приложения

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