Detectando uso do PWA

Tempo de leitura: 4 minutos

Detectando uso do PWA: Para que um Progressive Web App (PWA) ofereça uma experiência verdadeiramente nativa, ele precisa saber em que contexto está sendo executado. Detectar se o PWA está em modo de navegador ou instalado (standalone) permite personalizar a interface, remover elementos redundantes e garantir uma transferência de sessão suave após a instalação.

1. 🔍 Detectando o Modo de Exibição

A detecção é feita principalmente através de consultas de mídia (Media Queries) e propriedades específicas do objeto navigator.

A. Consulta de Mídia (`matchMedia`)

Este é o método mais moderno e recomendado, suportado por navegadores baseados em Chromium (Android, Desktop) e Safari (iOS/iPadOS). Ele verifica o valor do campo display definido no seu Web App Manifest.

Consulta de Mídia	Retorno true em…
`(display-mode: standalone)`	Modo de aplicativo instalado (sem barra de endereço do navegador).
`(display-mode: fullscreen)`	Modo de tela cheia imersiva (sem barras do sistema, se aplicável).
`(display-mode: minimal-ui)`	Experiência de aplicativo com controles mínimos de navegação do navegador.
`(display-mode: browser)`	O PWA está sendo executado em uma aba de navegador normal.

JavaScript

if (window.matchMedia('(display-mode: standalone)').matches) {
  // A PWA está instalada. 
  // Ocultar o botão "Instalar" ou a barra de navegação duplicada.
  console.log('Modo: Standalone (Instalado)');
}

B. Propriedade `navigator.standalone` (Específico para iOS)

Em dispositivos iOS/iPadOS, o Safari usa a propriedade não-padrão navigator.standalone para indicar que a PWA foi aberta a partir do ícone da tela inicial.

JavaScript

if ('standalone' in navigator && navigator.standalone) {
  console.log('Modo: Standalone (Instalado em iOS)');
}

Combinação de Detecção

Para uma cobertura ampla, combine ambas as verificações:

JavaScript

const isStandalone = window.matchMedia('(display-mode: standalone)').matches || 
                     ('standalone' in navigator && navigator.standalone);

if (isStandalone) {
  // Personalização para modo de aplicativo
} else {
  // Personalização para modo de navegador
}

2. 🤝 Instalação e Transferência de Sessão

Quando um usuário instala um PWA enquanto navega em uma aba, ele espera que o aplicativo instalado (o modo standalone) mantenha o estado de login e navegação.

A. Armazenamento Persistente

Para garantir uma transição suave, você deve usar APIs de armazenamento que não são isoladas entre o modo de navegador e o modo instalado (exceto no iOS, conforme abaixo).

LocalStorage / SessionStorage: Armazenar tokens de autenticação ou estados simples.
IndexedDB: Armazenar dados estruturados de sessão e conteúdo offline.

B. Transferência Imediata Após a Instalação (Chrome/Android)

Quando o usuário aceita o prompt de instalação, o navegador dispara o evento appinstalled. Você pode usar esse evento para:

Redirecionar: Se o usuário estiver em um fluxo de checkout, você pode redirecioná-lo para a tela inicial do PWA (o start_url do Manifest) assim que o aplicativo for instalado.
Limpeza: Limpar cookies temporários ou prompts de “Instalar”.

JavaScript

window.addEventListener('appinstalled', () => {
  console.log('PWA instalado. Redirecionando para a home do app...');
  // Oculta o prompt de instalação
  deferredPrompt = null; 
  // Opcional: Redirecionar para o start_url
  // window.location.href = '/'; 
});

3. ⚠️ Isolamento de Armazenamento no iOS/iPadOS

O ecossistema da Apple trata o PWA instalado como um aplicativo separado do Safari, resultando em um isolamento de armazenamento.

Implicação: Dados armazenados no Safari (o navegador) não são acessíveis quando a PWA é aberta em modo Standalone (o aplicativo instalado).

Solução

A melhor prática é garantir que o usuário faça login novamente (se necessário) ou, de forma mais robusta, sincronizar dados importantes com o servidor após a instalação.

Token na URL: Uma técnica avançada é transferir um token de sessão de uso único via URL (se for seguro fazê-lo) e usá-lo no modo standalone para buscar o token permanente do usuário no servidor.

4. 🔗 Outras Detecções e Integrações

A. Detectando a Primeira Visita

Utilizar o localStorage é a maneira mais simples de determinar se o usuário já esteve no PWA:

JavaScript

if (localStorage.getItem('user_id')) {
  // Usuário retornado.
  // Pode-se iniciar o processo de carregamento de dados sincronizados.
} else {
  // Primeiro acesso ou novo usuário.
  localStorage.setItem('user_id', generateUniqueId()); 
}

B. Aplicativos Relacionados (`related_applications`)

Este campo no Manifest é usado para informar ao navegador sobre a existência de versões nativas. Se o PWA não oferecer uma experiência ideal, o navegador pode sugerir a instalação do aplicativo nativo (ex: o aplicativo da Play Store) em vez da PWA.

JSON

"related_applications": [{
    "platform": "play",
    "url": "https://play.google.com/store/apps/details?id=com.meuapp.nativo",
    "id": "com.meuapp.nativo"
}]

✅ Conclusão Detectando uso do PWA

Detectando uso do PWA: A detecção do modo de exibição, através de matchMedia('(display-mode: standalone)') e navigator.standalone, é fundamental para personalizar a interface e otimizar a usabilidade do PWA. Para garantir uma experiência coesa, é crucial preservar a sessão (usando IndexedDB ou LocalStorage) e estar atento ao isolamento de armazenamento no iOS, garantindo que a transição do navegador para o aplicativo instalado seja transparente e sem perdas de dados para o usuário.

Toda jornada tem um início, e o início para se tornar um desenvolvedor web é dominar as seguintes tecnologias, que você encontra aqui mesmo: