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

Muitos navegadores permitem ativar e promover a instalação do Progressive Web App (PWA) diretamente na interface do usuário do PWA. A instalação (às vezes chamada de "Adicionar à tela inicial") facilita para os usuários a instalação do PWA nos dispositivos móveis ou desktop. A instalação de um PWA o adiciona à tela de início de um usuário, permitindo que ele seja executado como qualquer outro app instalado.

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

Botão "Instalar app" fornecido no PWA do Spotify
Botão "Instalar app" fornecido no PWA do Spotify

Ao considerar se você quer promover a instalação, é melhor pensar em como os usuários normalmente usam seu PWA. Por exemplo, se houver um conjunto de usuários que usam o PWA várias vezes em uma semana, eles poderão se beneficiar da conveniência de iniciar o app na tela inicial de um smartphone ou no menu "Iniciar" em 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 ou minimal-ui instalados.

Pré-requisitos

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

Promover instalação

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

  1. Ouça o evento beforeinstallprompt.
  2. Salve o evento beforeinstallprompt para que ele possa ser usado para 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.

Ouvir o evento beforeinstallprompt

Se o App Web Progressivo 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 instalação no app, forneça um botão ou outro elemento de interface em que o usuário possa clicar para instalar o app. Quando o elemento for clicado, chame prompt() no evento beforeinstallprompt salvo (armazenado na variável deferredPrompt). Ele mostra ao usuário uma caixa de diálogo de instalação modal, pedindo que ele confirme que quer instalar o 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 dispensá-lo, você precisará esperar até que o evento beforeinstallprompt seja disparado novamente, normalmente logo após a resolução da propriedade userChoice.

Detecta quando o PWA foi instalado

Você pode usar a propriedade userChoice para determinar se o usuário instalou seu app pela interface do usuário. No entanto, se o usuário instalar seu PWA usando a barra de endereço ou outro componente do navegador, o userChoice não vai ajudar. Em vez disso, você precisa detectar o evento appinstalled. Ele é acionado sempre que o PWA é instalado, independentemente do mecanismo usado para instalá-lo.

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 possibilita aplicar estilos diferentes, dependendo de como o app foi iniciado. Por exemplo, sempre oculte o botão de instalação e forneça um botão "Voltar" quando iniciado como um PWA instalado.

Acompanhe como o PWA foi lançado

Para acompanhar como os usuários iniciam seu PWA, use matchMedia() para testar a consulta de mídia display-mode. O Safari no iOS ainda não é compatível com isso. Por isso, é necessário marcar navigator.standalone. Ele retorna um booleano indicando se o navegador está sendo executado no modo independente.

function getPWADisplayMode() {
  const isStandalone = window.matchMedia('(display-mode: standalone)').matches;
  if (document.referrer.startsWith('android-app://')) {
    return 'twa';
  } else if (navigator.standalone || isStandalone) {
    return 'standalone';
  }
  return 'browser';
}

Monitorar quando o modo de exibição mudar

Para rastrear se o usuário muda entre standalone e browser tab, detecte as mudanças na consulta de mídia display-mode.

window.matchMedia('(display-mode: standalone)').addEventListener('change', (evt) => {
  let displayMode = 'browser';
  if (evt.matches) {
    displayMode = 'standalone';
  }
  // Log display mode change to analytics
  console.log('DISPLAY_MODE_CHANGED', displayMode);
});

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

Para aplicar uma cor de plano de fundo diferente para um PWA quando iniciado como um PWA instalado, use um 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 incluir novos ícones? Consulte Como o Chrome lida com atualizações no manifesto do app da Web para saber quando e como essas alterações são refletidas no Chrome.