Detecção

É possível detectar se o usuário está usando seu PWA no navegador ou no modo independente. Em navegadores baseados no Chromium (Android e computador), também é possível detectar os seguintes eventos:

• Status e resultado da caixa de diálogo do convite de instalação.
• Instalação concluída.
• A navegação é transferida do navegador para a janela do PWA e vice-versa.
• Status da instalação do PWA.
• App relacionado instalado de uma app store.

Use esses dados para fazer análises, entender as preferências dos usuários e personalizar a experiência deles. Para capturar esses eventos, você pode usar ferramentas como consultas de mídia, eventos do window ou as APIs de recursos listadas aqui.

Detectando modo de exibição

Para acompanhar como os usuários iniciam seu PWA, você pode usar matchMedia() para testar a consulta de mídia display-mode.

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

Se você usar esse exemplo, faça a correspondência do modo de exibição do manifesto do seu app da Web, por exemplo, standalone, minimal-ui ou fullscreen. Também é possível corresponder várias consultas na string de consulta de mídia usando condições separadas por vírgulas.

Também é possível adicionar um parâmetro de consulta ao start_url do manifesto, que pode ser capturado com análises para rastrear estatísticas sobre quando, de que maneira e quanto do PWA está sendo usado.

Instalação do app

Quando um usuário aceita a solicitação de instalação no navegador, o evento appinstalled é disparado em navegadores baseados no Chromium. Um ótimo uso para esse manipulador de eventos é remover qualquer promoção de instalação no aplicativo que você tenha adicionado.

window.addEventListener('appinstalled', () => {
  // If visible, hide the install promotion
  hideInAppInstallPromotion();
  // Log install to analytics
  console.log('INSTALL: Success');
});

Em dispositivos Android com o WebAPK, o evento é acionado quando o usuário aceita a caixa de diálogo, e não depois que o WebAPK é criado e instalado. Pode haver um atraso de alguns segundos até que o app seja totalmente instalado.

O capítulo Comando de instalação explica como detectar se uma solicitação de instalação está disponível e quais escolhas o usuário pode fazer.

Transferência de sessão

Os usuários podem usar seu PWA no navegador e no formulário independente instalado. Em navegadores para computador, é possível transferir a navegação atual entre esses contextos usando selos ou itens de menu, como mostrado na imagem abaixo.

No Android, há um item de menu semelhante ao do computador no navegador que transfere a navegação para o app. Nesse caso, o URL atual será aberto, mas será uma nova navegação de página no app.

Na imagem abaixo, é possível conferir o item de menu no Android quando o app já está instalado.

Transferência após a instalação

Em navegadores para computador, a navegação atual é transferida imediatamente para o app durante a instalação. A guia do navegador é fechada, e o app recém-instalado é aberto, continuando o que o usuário estava fazendo.

Em navegadores para dispositivos móveis, a navegação atual permanece no navegador quando você instala o app. Se os usuários quiserem migrar para o app, eles vão precisar abrir o app manualmente e haverá uma nova navegação.

Como detectar a transferência

Para detectar a transferência entre o navegador e a janela, use uma consulta de mídia:

window.addEventListener('DOMContentLoaded', () => {
  // replace standalone with your display used in manifest
  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);
    });
});

Isolamento de armazenamento do iOS e iPadOS

No iOS e iPadOS, não há navegação ou transferência de URL entre o navegador e o ícone instalado. Mesmo se for o mesmo PWA, cada ícone do PWA que o usuário instalar terá um armazenamento próprio, isolado da guia do Safari e de outros ícones. Quando um usuário abre o ícone de instalação, nenhum armazenamento é compartilhado com o Safari. Se o PWA precisar de um login, o usuário precisará fazer login novamente. Se o app tiver sido adicionado à tela inicial várias vezes, para cada instância do PWA, o usuário terá uma sessão diferente.

Aplicativos relacionados

Um site indica uma relação com um aplicativo pelo manifesto. Para fazer isso, use o membro related_applications da especificação do manifesto do app da Web. A chave related_applications é uma matriz de objetos que representam cada aplicativo relacionado. Cada entrada contém platform, url e um id opcional.

Estes são os possíveis valores de plataforma:

• chrome_web_store: Google Chrome Web Store.
• play: apps do Google Play (Android e ChromeOS).
• chromeos_play: Play do ChromeOS.
• webapp: apps da Web.
• windows: Microsoft Store (Windows 10 e 11).
• f-droid: F-droid.
• amazon: Amazon AppStore (FireOS).

Prefiro um app relacionado

Quando o usuário instala um app, é possível redirecioná-lo para um app relacionado definindo o campo prefer_related_applications como true no manifesto. Com essa configuração, em navegadores compatíveis, os fluxos de instalação não instalarão o PWA. Em vez disso, eles acionam uma instalação da loja pelo url ou id especificado na entrada related_applications.

O aplicativo relacionado pode ser seu PWA e será instalado em uma app store. Uma vantagem dessa configuração é que, no momento, apenas os aplicativos instalados pela app store são recuperados com um backup ou quando você muda para um novo dispositivo.

{
  ...
  "related_applications:" [
     {
       "platform": "play",
       "url": "https://play.google.com/..."
     }
  ],
  "prefer_related_applications": true
}

Banners inteligentes para aplicativos da Apple

O Safari não é compatível com o assinante related_applications, mas oferece banners de apps inteligentes para aplicativos na App Store. Portanto, se você quiser promover um PWA ou outro app publicado na App Store, poderá incluir metatags no HTML do PWA para convidar o usuário a instalar o app (consulte o link fornecido) ou transferir a navegação, se já estiver instalado.

Detectar apps instalados relacionados

O método getInstalledRelatedApps() permite que seu site verifique se o app para iOS/Android/computador ou PWA está instalado no dispositivo do usuário.

Verificar se um app relacionado já está instalado ajuda a implementar recursos como ocultar solicitações de instalação personalizada ou redirecionar o usuário diretamente para o app instalado, em vez de acessar um site de uso geral. Para usar o método getInstalledRelatedApps(), o app instalado e o site precisam configurar a conexão entre si. Cada app, dependendo da plataforma, inclui metadados para reconhecer o site, e o site inclui o app instalado esperado no campo related_applications do manifesto.

Ferramentas como o BubbleWrap ou o PWA Builder, que permitem publicar o PWA em app stores, já adicionam os metadados necessários para que o site possa usar o getInstalledRelatedApps() imediatamente. Para detectar se um PWA já está instalado usando getInstalledRelatedApps(), defina webapp no campo related_applications do manifesto com o URL do manifesto:

...
"related_applications": [{
   "platform": "webapp",
   "url": "https://example.com/manifest.json",
}],
...

getInstalledRelatedApps() retorna uma matriz de objetos de apps. Se a matriz estiver vazia, isso significa que o app relacionado não está instalado.

const relatedApps = await navigator.getInstalledRelatedApps();
const PWAisInstalled = relatedApps.length > 0;

Detectar a instalação de fora do escopo do PWA

No Chrome no Android 89, é possível detectar se um PWA está instalado, mesmo fora do escopo dele. Seu PWA precisa definir um arquivo JSON na pasta /.well-known/, concedendo permissão para o outro escopo, conforme descrito neste artigo.

Recursos

• Seu app está instalado? O getInstaladoRelatedApps() vai avisar você.
• MDN: aplicativos relacionados
• MDN: evento "AppInstall"
• Apple: promoção de apps com banners de apps inteligentes