Skip to content
Sobre Blog Aprender Explorar padrões Case studies
Nesta página
  • Promovendo a instalação
    • Escute o beforeinstallprompt
    • Processo de instalação in-app
  • Detecte quando o PWA foi instalado com sucesso
  • Detecte como o PWA foi iniciado
    • Monitore como o PWA foi lançado
    • Monitore quando o modo de exibição mudar
    • Atualize a IU com base no modo de exibição atual
  • Atualizando o ícone e o nome da sua aplicação

Como fornecer sua própria experiência de instalação in-app

Feb 14, 2020 — Atualizado May 19, 2021
Available in: English, Español, Русский, 中文, 日本語 e 한국어
Appears in: Aplicações Web Progressivas
Pete LePage
Pete LePage
TwitterGitHubGlitchHomepage
Nesta página
  • Promovendo a instalação
    • Escute o beforeinstallprompt
    • Processo de instalação in-app
  • Detecte quando o PWA foi instalado com sucesso
  • Detecte como o PWA foi iniciado
    • Monitore como o PWA foi lançado
    • Monitore quando o modo de exibição mudar
    • Atualize a IU com base no modo de exibição atual
  • Atualizando o ícone e o nome da sua aplicação

Muitos navegadores possibilitam que você ative e promova a instalação do seu Progressive Web App (PWA) diretamente a partir da própria interface do usuário do seu PWA. A instalação (às vezes conhecida como "Adicionar à tela inicial") torna mais fácil para os usuários instalarem seu PWA em seus dispositivos móveis ou desktop. A instalação de um PWA adiciona-o ao inicializador do usuário, permitindo que seja executado como qualquer outra aplicação instalada.

Além da experiência de instalação proporcionada pelo navegador, é possível fornecer seu próprio processo de instalação personalizado, diretamente a partir da sua aplicação.

Botão Instalar aplicativo fornecido no Spotify PWA
Botão "Instalar aplicativo" fornecido no Spotify PWA

Ao considerar se deve ou não 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 seu PWA muitas vezes por semana, esses usuários poderão se beneficiar com a conveniência adicional de iniciar seu aplicativo a partir da tela inicial de um smartphone ou do menu Iniciar de um sistema operacional de desktop. Alguns aplicativos de produtividade e entretenimento também se beneficiam do espaço extra da tela criado pela remoção das barras de ferramentas do navegador da janela nos modos standalone ou minimal-ui

Promovendo a instalação #

Para indicar que seu Progressive Web App é instalável e para fornecer um processo de instalação in-app personalizado:

  1. Escute o evento beforeinstallprompt
  2. Salve o evento beforeinstallprompt, para que ele possa ser usado para disparar o processo de instalação posteriormente.
  3. Avise ao usuário de que seu PWA pode ser instalado e forneça um botão ou outro elemento para iniciar o processo de instalação no aplicativo.
O evento beforeinstallprompt e o evento appinstalled foram transferidos da especificação do manifesto web app para sua própria incubadora. A equipe do Chrome continua comprometida em apoiá-los e não tem planos de remover ou suspender seu uso. A equipe Web DevRel do Google continua recomendando seu uso para proporcionar uma experiência de instalação personalizada.

Escute o beforeinstallprompt #

Se seu Progressive Web App atender aos critérios de instalação necessários, o navegador disparará um evento beforeinstallprompt. Salve uma referência ao evento e atualize sua interface de usuário para indicar que o usuário pode instalar seu PWA. Isso está destacado abaixo.

// Inicialize o deferredPrompt para posteriormente mostrar o prompt de instalação do navegador.
let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
// Impede que o mini-infobar apareça em mobile
e.preventDefault();
// Guarda evento para que possa ser disparado depois.
deferredPrompt = e;
// Atualiza UI notifica usuário que pode instalar PWA
showInstallPromotion();
// Opcionalmente, enviar eventos de analytics que promo de instalação PWA foi mostrado.
console.log(`'beforeinstallprompt' event was fired.`);
});
Existem diversos padrões diferentes que você pode usar para notificar o usuário de que sua aplicação pode ser instalada e fornecer um processo de instalação na aplicação, por exemplo, um botão no cabeçalho, um item no menu de navegação ou um item em seu feed de conteúdo.

Processo de instalação in-app #

Para fornecer uma instalação in-app, forneça um botão ou outro elemento de interface no qual um usuário possa clicar para instalar sua aplicação. Quando o elemento for clicado, chame prompt() no evento beforeinstallprompt salvo (armazenado na deferredPrompt). Ele mostra ao usuário uma caixa de diálogo de instalação modal, solicitando a confirmação de que deseja instalar o PWA.

buttonInstall.addEventListener('click', async () => {
// Esconde a promoção de instalação fornecida pelo app
hideInstallPromotion();
// Mostra prompt de instalação
deferredPrompt.prompt();
// Espera usuário responder ao prompt
const { outcome } = await deferredPrompt.userChoice;
// Opcionalmente, enviar evento analytics com resultado da escolha do usuário
console.log(`User response to the install prompt: ${outcome}`);
// Usamos o prompt e não podemos usar de novo; jogue fora
deferredPrompt = null;
});

A propriedade userChoice é uma promessa que se resolve com a escolha do usuário. Você só pode chamar prompt() no evento adiado uma única vez. Se o usuário dispensá-lo, você precisará esperar até que o beforeinstallprompt seja disparado novamente. Isto ocorre geralmente logo após a resolução da propriedade userChoice.

Experimente

Torne um site instalável usando o evento beforeinstallprompt.

Detecte quando o PWA foi instalado com sucesso #

Você pode usar a propriedade userChoice para determinar se o usuário instalou sua aplicação a partir da sua interface de usuário. Mas, se o usuário instalar seu PWA a partir da barra de endereços ou outro componente do navegador, a propriedade userChoice não ajudará. Em vez disso, você precisa escutar o evento appinstalled. Ele é disparado sempre que o PWA é instalado, independentemente do mecanismo usado para instalá-lo.

window.addEventListener('appinstalled', () => {
// Esconder a promoção de instalação fornecida pela app
hideInstallPromotion();
// Limpar o deferredPrompt para que seja coletado
deferredPrompt = null;
// Opcionalmente, enviar evento de analytics para indicar instalação com sucesso
console.log('PWA was installed');
});

Detecte como o PWA foi iniciado #

A media query CSS display-mode indica como o PWA foi iniciado, em uma aba do navegador ou como um PWA instalado. Isto permite aplicar estilos diferentes, dependendo de como o aplicativo 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.

Monitore como o PWA foi lançado #

Para rastrear como os usuários iniciam seu PWA, use matchMedia() para testar a media query display-mode. O Safari no iOS ainda não suporta esse recurso, então você precisa verificar navigator.standalone: ele retorna um valor 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';
}

Monitore quando o modo de exibição mudar #

Para rastrear se o usuário muda entre standalone e browser tab, escute as mudanças na media query 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);
});

Atualize a IU com base no modo de exibição atual #

Para aplicar uma cor de fundo diferente para um PWA quando iniciado como um PWA instalado, use CSS condicional:

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

Atualizando o ícone e o nome da sua aplicação #

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

Aplicações Web Progressivas
Last updated: May 19, 2021 — Improve article
Return to all articles
Compartilhar
assinar

Contribute

  • Registrar um bug
  • Visualizar código-fonte

Conteúdo relacionado

  • developer.chrome.com
  • Atualizações do Chrome
  • Estudos de caso
  • Podcasts
  • Shows

Conectar

  • Twitter
  • YouTube
  • Google Developers
  • Chrome
  • Firebase
  • Google Cloud Platform
  • Todos os produtos
  • Termos e privacidade
  • Diretrizes da comunidade

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies.