Muitos navegadores permitem que você ative e promova a instalação do Progressive Web App (PWA) diretamente na interface do usuário. A instalação (às vezes chamada de Adicionar à tela inicial) permite que os usuários instalem seu PWA em dispositivos móveis 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, é possível fornecer seu próprio fluxo de instalação personalizado diretamente no app.
Ao considerar se você quer promover a instalação, considere como os usuários normalmente
usam o 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 para computadores. 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 mostrar que o Progressive Web App pode ser instalado e fornecer um fluxo de instalação personalizado no app:
- Ouça o evento
beforeinstallprompt. - Salve o evento
beforeinstallpromptpara que ele possa acionar o fluxo de instalação mais tarde. - 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 ou tocar para instalar o app. Quando o usuário clicar ou
tocar no elemento, 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, solicitando
que ele confirme se 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á aguardar até que o evento beforeinstallprompt
seja disparado novamente, normalmente logo após a propriedade userChoice
ser resolvida.
Detecta quando o PWA foi instalado
Você pode 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 o 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, que é acionado sempre que o PWA está instalado, seja qual for o 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, é possível configurá-lo
para sempre ocultar o botão de instalação e fornecer 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 esse recurso. Por isso, verifique navigator.standalone, que 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.