Como oferecer sua própria experiência de instalação no app

Muitos navegadores permitem ativar e promover a instalação do seu Progressive Web App (PWA) diretamente na interface do usuário. A instalação (anteriormente chamada de "Adicionar à tela inicial") permite que os usuários instalem sua PWA em dispositivos móveis ou computadores. A instalação de um PWA adiciona o app ao iniciador de um usuário para que ele possa ser executado como qualquer outro app instalado.

Além da experiência de instalação fornecida pelo navegador, você pode fornecer seu próprio fluxo de instalação personalizado diretamente no app.

Botão "Instalar o app" fornecido no PWA do Spotify
O botão "Instalar app" fornecido no PWA do Spotify.

Ao considerar a promoção da instalação, pense em como os usuários normalmente usam seu PWA. Por exemplo, se um conjunto de usuários usar seu PWA várias vezes por semana, eles poderão se beneficiar da conveniência adicional de iniciar o app na tela inicial de um smartphone ou no menu "Iniciar" de um sistema operacional de computador. Alguns aplicativos de produtividade e entretenimento também se beneficiam do espaço extra na tela criado ao remover as barras de ferramentas do navegador da janela nos modos standalone, minimal-ui ou window-control-overlay instalados.

Pré-requisitos

Antes de começar, verifique se o PWA atende aos requisitos de instalabilidade, que normalmente incluem um manifesto de app da Web.

Promover a instalação

Para mostrar que seu Progressive Web App pode ser instalado e fornecer um fluxo de instalação personalizado no app:

  1. Detecte o evento beforeinstallprompt.
  2. Salve o evento beforeinstallprompt para que ele possa acionar o fluxo de instalação mais tarde.
  3. Alerte o usuário de que o PWA pode ser instalado e forneça um botão ou outro elemento para iniciar o fluxo de instalação no app.

Detectar o evento beforeinstallprompt

Se o Progressive Web App atender aos critérios de instalação necessários, o navegador vai disparar um evento beforeinstallprompt. Salve uma referência ao evento e atualize a interface do usuário para indicar que o usuário pode instalar o 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.`);
});

Fluxo de instalação no app

Para oferecer a instalação no app, forneça um botão ou outro elemento de interface que o usuário possa clicar ou tocar para instalar o app. Quando o elemento for clicado ou tocado, chame prompt() no evento beforeinstallprompt salvo (armazenado na variável deferredPrompt). Ela mostra ao usuário uma caixa de diálogo de instalação modal, pedindo que ele confirme a instalação do 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;
});

A propriedade userChoice é uma promessa que é resolvida com a escolha do usuário. Só é possível chamar prompt() no evento adiado uma vez. Se o usuário fechar, você vai precisar esperar até que o evento beforeinstallprompt seja acionado novamente, normalmente imediatamente após a propriedade userChoice ser resolvida.

Detectar quando a PWA foi instalada

É possível usar a propriedade userChoice para determinar se o usuário instalou o app na interface do usuário. No entanto, se o usuário instalar seu PWA na barra de endereço ou em outro componente do navegador, o userChoice não vai ajudar. Em vez disso, detecte o evento appinstalled, que é acionado sempre que o PWA é instalado, não importa qual mecanismo é usado para a instalação.

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');
});

Detectar como o PWA foi iniciado

A consulta de mídia CSS display-mode indica como o PWA foi iniciado, em uma guia do navegador ou como um PWA instalado. Isso permite aplicar estilos diferentes dependendo de como o app foi iniciado. Por exemplo, é possível configurar para sempre ocultar o botão de instalação e fornecer um botão "Voltar" quando iniciado como um PWA instalado.

Acompanhar como o PWA foi lançado

Para acompanhar como os usuários iniciam sua PWA, use matchMedia() para testar a consulta de mídia 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';
}

Acompanhar quando o modo de exibição muda

Para acompanhar se o usuário muda entre browser e outros modos de exibição, detecte mudanças na consulta de mídia 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());
});

Atualizar a interface com base no modo de exibição atual

Para aplicar uma cor de plano de fundo diferente a um PWA quando ele for aberto como um PWA instalado, use o CSS condicional:

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

Atualizar o ícone e o nome do app

E se você precisar atualizar o nome do app ou fornecer novos ícones? Confira Como o Chrome processa as atualizações do manifesto do app da Web para saber quando e como essas mudanças são refletidas no Chrome.