Publicado em: 14 de fevereiro de 2020
Muitos navegadores permitem ativar e promover a instalação do seu Progressive Web App (PWA) diretamente na interface do usuário. A instalação (antes chamada de "Adicionar à tela inicial") permite que os usuários adicionem seu PWA ao dispositivo móvel ou desktop. A instalação de um PWA o adiciona à tela de início 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 oferecer seu próprio fluxo de instalação personalizado diretamente no app.
Ao considerar se é necessário promover a instalação, pense em como os usuários normalmente
usam seu PWA. Por exemplo, se houver um conjunto de usuários que usam 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 com a remoção das barras de ferramentas do navegador da
janela nos modos instalados standalone, minimal-ui ou window-control-overlay.
Pré-requisitos
Antes de começar, verifique se o PWA atende aos requisitos de capacidade de instalação, que geralmente incluem um manifesto do app da Web.
Promover a instalação
Para mostrar que seu App Web Progressivo pode ser instalado e oferecer um fluxo de instalação personalizado no app:
- Detecte o evento
beforeinstallprompt. - Salve o evento
beforeinstallpromptpara que ele possa acionar o fluxo de instalação mais tarde. - Avise o usuário de que o PWA pode ser instalado e ofereç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 acionar 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
em 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 modal de instalação, pedindo
que ele confirme se quer instalar seu 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
dispensar a mensagem, você precisará esperar até que o evento beforeinstallprompt
seja acionado novamente, geralmente imediatamente após a propriedade userChoice
ser resolvida.
Detectar quando o PWA foi instalado com sucesso
É possível usar a propriedade userChoice para determinar se o usuário instalou
o app na interface. No entanto, se o usuário instalar o 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 seja usado para isso.
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 display-mode do CSS indica como o PWA foi iniciado, seja 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 iniciado
Para acompanhar como os usuários iniciam seu PWA, use o 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, ouça as 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 é iniciado como um PWA instalado, use 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 lida com atualizações no manifesto do web app para saber quando e como essas mudanças são refletidas no Chrome.