Rastreamento PWA: como implementar tráfego direto em 7 passos
Tráfego direto em PWA é um desafio de medição: sem URLs claras, o GA4 agrupa tudo como 'direct'. Este guia mostra como implementar rastreamento confiável em etapas práticas.
Tráfego direto em PWA é um dos maiores buracos de medição em analytics. Quando um usuário abre o app instalado, o navegador não envia referrer, e o GA4 joga tudo em "direct". Resultado: você não sabe se aquela sessão veio de um ícone na home screen, de uma notificação push ou de um link compartilhado. Este guia mostra como implementar rastreamento confiável, sem depender de suposições.
O resultado esperado é um funil claro: você identifica quantas sessões vêm do PWA instalado, quantas são de primeira abertura e qual o comportamento desses usuários. Antes de começar, garanta que o PWA já está publicado com service worker ativo e que você tem acesso ao código-fonte. O processo usa Google Analytics 4 (GA4), padrão atual de medição, e não requer bibliotecas extras.
Passo 1: Configure o GA4 no PWA
O primeiro passo é garantir que o GA4 está carregado em todas as páginas do PWA, incluindo as que abrem offline. Adicione o snippet de configuração no HTML principal, antes do fechamento da tag <head>. Para funcionar offline, o service worker deve cachear o próprio script do analytics.
Um erro comum aqui é usar apenas o gtag.js padrão sem testar em modo offline. O GA4 usa navigator.sendBeacon para enviar eventos, que funciona offline, mas se o script não estiver no cache, ele não carrega. Teste com o DevTools aberto, na aba Network, marcando "Offline".
Passo 2: Defina os parâmetros de origem
O tráfego direto não distingue a fonte. Para separar, você precisa de parâmetros personalizados. Crie uma lista fixa de origens possíveis no PWA: instalação, ícone na home screen, notificação push, link compartilhado e digitação manual da URL.
No GA4, esses valores entram como source e medium. Por exemplo, source=pwa_install e medium=app. Isso permite filtrar no relatório de aquisição sem perder o tráfego no guarda-chuva "direct".
Uma ressalva: não invente valores que não existem no seu contexto. Cada PWA tem origens próprias. O importante é que todos os acessos pós-instalação carreguem esse parâmetro.
Passo 3: Implemente o evento de instalação
O evento beforeinstallprompt é disparado quando o navegador detecta que o PWA é instalável. Capture esse momento e envie um evento personalizado ao GA4. O código é simples: ouça o evento, previna o comportamento padrão e armazene o prompt para uso posterior.
let deferredPrompt; window.addEventListener('beforeinstallprompt', (e) => { e.preventDefault(); deferredPrompt = e; gtag('event', 'pwa_install_prompt', { source: 'pwa_banner' }); });
Quando o usuário confirmar a instalação, dispare outro evento: pwa_install_accepted. Isso cria um funil de conversão: quantos viram o prompt, quantos aceitaram. Erro comum: só medir a aceitação, sem o prompt. Sem o numerador, você não calcula taxa de conversão.
Passo 4: Marque a primeira abertura pós-instalação
Após a instalação, a primeira abertura do PWA é um evento crítico. Use o localStorage para armazenar uma flag. Na primeira carga, se a flag não existir, envie pwa_first_open e então grave a flag.
if (!localStorage.getItem('pwa_first_open')) { gtag('event', 'pwa_first_open', { source: 'pwa_install' }); localStorage.setItem('pwa_first_open', 'true'); }
Esse evento responde a pergunta: a instalação realmente converteu em uso? Muitos usuários instalam, mas nunca abrem. Sem essa marcação, você não distingue entre instalação e ativação.
Passo 5: Diferencie abertura por ícone vs. link externo
O tráfego direto inclui tanto quem abre pelo ícone na home screen quanto quem digita a URL manualmente. Para separar, use o parâmetro page_location no evento session_start. Quando o PWA é aberto pelo ícone, o document.referrer é vazio.
Mas há um caso específico: em Android, ao abrir pelo ícone, o PWA roda em modo standalone, e o window.matchMedia('(display-mode: standalone)') retorna verdadeiro. Use isso para diferenciar do acesso via navegador.
if (window.matchMedia('(display-mode: standalone)').matches) { gtag('event', 'session_start', { source: 'pwa_icon', medium: 'app' }); }
Erro comum: aplicar essa lógica em todas as páginas. Aplique apenas no primeiro hit da sessão, senão você infla o contador de sessões.
Passo 6: Rastreie notificações push
Se o PWA usa notificações push, cada clique é uma origem distinta. Quando o usuário clica na notificação, o service worker recebe o evento notificationclick. Envie um evento pwa_push_click com o source e o medium apropriados.
self.addEventListener('notificationclick', (event) => { event.notification.close(); event.waitUntil( clients.openWindow(event.notification.data.url) ); });
No GA4, o evento deve ser enviado do contexto da página, não do service worker. Use clients.matchAll para enviar a mensagem à página aberta, que então dispara o gtag. Sem esse passo, o clique da notificação não aparece no analytics.
Passo 7: Valide com DebugView e relatórios
Antes de publicar, valide cada evento no GA4 DebugView. Abra o PWA em modo standalone, clique no ícone, dispare uma notificação e confira se os eventos chegam com os parâmetros corretos. O DebugView mostra em tempo real, com atraso de poucos segundos.
Depois, monte um relatório de aquisição com dimensão source. Filtre por pwa_icon, pwa_push e pwa_install. Se algum valor não aparecer, revise o código do passo anterior.
Um erro comum é esquecer de testar em diferentes dispositivos. O comportamento do PWA varia entre Android e iOS. No iOS, o beforeinstallprompt não existe, então o evento de instalação precisa ser capturado por outro método, como o appinstalled, que é disparado após a adição à home screen.
Checklist do que foi feito
Ao final, você deve ter:
- GA4 carregado e funcionando offline.
- Evento
beforeinstallpromptcapturado compwa_install_prompt. - Evento
pwa_first_openna primeira abertura. - Diferenciação entre abertura por ícone e link externo via
display-mode. - Evento
pwa_push_clickpara notificações. - Validação no DebugView com todos os parâmetros.
Com isso, o tráfego direto deixa de ser uma caixa-preta. Você sabe exatamente quantos usuários voltam pelo ícone, quantos clicam em notificações e qual o impacto real da instalação. O próximo passo é criar um relatório semanal no GA4 que compare essas origens com o tráfego direto residual, que deve diminuir conforme mais usuários usam o PWA instalado.
FAQ
Por que o tráfego direto em PWA aparece como "direct" no GA4?
Porque quando o PWA é aberto pelo ícone ou por uma notificação, o navegador não envia o cabeçalho Referer. O GA4 não tem como identificar a origem, então classifica como "direct". A solução é usar eventos personalizados com parâmetros de origem, como explicado neste guia.
O beforeinstallprompt funciona no iOS?
Não. O Safari para iOS não suporta esse evento. No iOS, a instalação é feita pelo menu "Adicionar à Tela de Início", sem prompt automático. Para rastrear, use o evento appinstalled, que dispara após a adição, ou detecte o modo standalone na primeira abertura.
Preciso de uma biblioteca extra para rastrear PWA?
Não. O GA4 padrão, com gtag.js, é suficiente. Você só adiciona eventos personalizados no código do PWA. Não é necessário usar o Firebase Analytics, a menos que você já use outros serviços do Firebase no app.
Como separar tráfego direto de PWA do tráfego direto de navegador?
Use a detecção de display-mode: standalone. Quando o PWA é aberto pelo ícone, esse modo é ativo. Já o acesso por digitação de URL no navegador roda em modo normal. No evento session_start, verifique essa condição e envie o parâmetro source correspondente.
O que fazer se o evento de instalação não aparece no DebugView?
Verifique se o service worker está cacheando o script do GA4. Se o PWA está offline, o gtag pode não carregar. Também confirme se o evento beforeinstallprompt está sendo disparado: ele só ocorre se o PWA atende aos critérios de instalabilidade do Chrome, como ter um service worker com fetch handler e um manifesto válido.
Quanto tempo leva para os eventos aparecerem nos relatórios no GA4?
Eventos em tempo real aparecem no DebugView imediatamente. Nos relatórios padrão, pode levar até 24 horas para a data completa. Para dados mais recentes, use o relatório de tempo real ou a exploração com janela de 30 minutos.