workbox-google-analytics

Se você estiver criando um aplicativo que funciona off-line, entender como os usuários estão interagindo com ele quando não têm conectividade é crucial para otimizar essa experiência.

Provedores de análises, como o Google Analytics, exigem uma conexão de rede para enviar dados aos servidores. Isso significa que, se a conectividade não estiver disponível, essas solicitações vão falhar e essas interações não serão incluídas nos relatórios de análise. Será como se nunca tivesse acontecido.

O Workbox do Google Analytics resolve esse problema para os usuários do Google Analytics usando a capacidade do Service Worker de detectar solicitações com falha.

O Google Analytics recebe todos os dados via solicitações HTTP para o Measurement Protocol, o que significa que um script do Service Worker pode adicionar um gerenciador de busca para detectar solicitações com falha enviadas ao Measurement Protocol. Ele pode armazenar essas solicitações no IndexedDB e tentar novamente mais tarde quando a conectividade for restaurada.

O Workbox do Google Analytics faz exatamente isso. Ele também adiciona gerenciadores de busca para armazenar em cache os scripts analytics.js e gtag.js, para que eles também possam ser executados off-line. Por fim, quando as solicitações com falha são repetidas, o Google Analytics da Workbox também define (ou atualiza) automaticamente o qt no payload da solicitação para garantir que os carimbos de data/hora no Google Analytics reflitam o tempo da interação original do usuário.

Ativar o Google Analytics no Workbox

Para ativar o Google Analytics no Workbox, chame o método initialize():

import * as googleAnalytics from 'workbox-google-analytics';

googleAnalytics.initialize();

Esse é o único código necessário para enfileirar e repetir solicitações com falha no Google Analytics, além de ser a maneira mais simples de fazer o Google Analytics funcionar off-line.

No entanto, se você estiver usando apenas o código acima, as solicitações repetidas serão indistinguíveis das solicitações bem-sucedidas na primeira tentativa. Isso significa que você vai receber todos os dados de interação dos usuários off-line, mas não saberá quais interações ocorreram enquanto eles estavam off-line.

Para resolver esse problema, use uma das opções de configuração descritas abaixo para modificar ou anotar os dados enviados na solicitação repetida.

Como modificar quais dados são enviados

Se você quiser diferenciar solicitações repetidas das que não foram repetidas, especifique as opções de configuração parameterOverrides ou hitFilter.

Essas opções permitem modificar os parâmetros do Measurement Protocol que são enviados na solicitação repetida. Use a opção parameterOverrides quando você quiser definir o mesmo valor de um parâmetro específico para cada nova tentativa de solicitação. A opção hitFilter precisa ser usada nos casos em que o valor de um parâmetro específico precisa ser calculado no tempo de execução ou derivado do valor de outro parâmetro.

Os exemplos abaixo mostram como usar as duas opções.

Exemplos

Usar uma dimensão personalizada para acompanhar interações on-line e off-line.

O Google Analytics não tem uma dimensão integrada para interações on-line e off-line. No entanto, você pode criar sua própria dimensão exatamente para essa finalidade usando um recurso chamado dimensões personalizadas.

Para rastrear solicitações repetidas pelo service worker usando uma dimensão personalizada com o Google Analytics do Workbox, siga estas etapas:

1. Crie uma nova dimensão personalizada no Google Analytics. Nomeie como "Network Status" e defina o escopo como "hit", já que qualquer interação pode ser off-line.

2. Anote o índice atribuído à dimensão recém-criada e transmita-o como o nome do parâmetro para a opção de configuração parameterOverrides no código do Google Analytics da caixa de trabalho.

   Por exemplo, se esta for sua primeira dimensão personalizada, o índice dela seria 1, e o nome do parâmetro seria cd1. Se o índice fosse 8, seria cd8:

   import * as googleAnalytics from 'workbox-google-analytics';
   
   googleAnalytics.initialize({
     parameterOverrides: {
       cd1: 'offline',
     },
   });
   

3. (Opcional) Como os valores em parameterOverrides são aplicados apenas a solicitações repetidas ("off-line"), você também pode definir um valor padrão "on-line" para todas as outras solicitações. Embora não seja estritamente necessário, isso tornará seus relatórios mais fáceis de ler.
   
   Por exemplo, se você tiver usado o snippet de acompanhamento padrão da analytics.js para instalar o Google Analytics, poderá adicionar a linha ga('set', 'dimension1', 'online') para usar um valor padrão de 'online' na sua dimensão personalizada "Status da rede" em todas as solicitações que não forem reproduzidas pelo service worker.

   <script>
     (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
     (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
     m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
     })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
   
     ga('create', 'UA-XXXXX-Y', 'auto');
   
     // Set default value of custom dimension 1 to 'online'
     ga('set', 'dimension1', 'online');
   
     ga('send', 'pageview');
   </script>
   

Como usar uma métrica personalizada para rastrear as solicitações de tempo gastas na fila

Se você quiser saber quanto tempo passou entre o momento em que uma interação off-line ocorreu, o momento em que a conectividade foi restaurada e a solicitação foi repetida, é possível rastrear isso usando uma métrica personalizada e a opção de configuração hitFilter:

1. Crie uma nova métrica personalizada no Google Analytics. Dê um nome a ela, como "Tempo de fila off-line", defina o escopo como "hit" e o tipo de formatação como "Tempo" (em segundos).

2. Use a opção hitFilter para receber o valor do parâmetro qt e divida-o por 1.000 (para convertê-lo em segundos). Em seguida, defina esse valor como um parâmetro com o índice da métrica recém-criada. Se esta for sua primeira métrica personalizada, o nome do parâmetro será 'cm1':

   import * as googleAnalytics from 'workbox-google-analytics';
   
   googleAnalytics.initialize({
     hitFilter: (params) => {
       const queueTimeInSeconds = Math.round(params.get('qt') / 1000);
       params.set('cm1', queueTimeInSeconds);
     },
   });
   

Como testar a caixa de trabalho do Google Analytics

Como o Google Analytics do Workbox usa a sincronização em segundo plano para reproduzir eventos, o teste pode não ser intuitivo. Leia mais em Como testar a sincronização em segundo plano da caixa de trabalho.

workbox-google-analytics.initialize(
  options?: GoogleAnalyticsInitializeOptions,
)