workbox-google-analytics

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

Fornecedores de análise, 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 as interações vão estar ausentes dos seus relatórios de análise. Vai ser como se eles nunca tivessem acontecido.

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

O Google Analytics recebe todos os dados por 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 solicitações no IndexedDB e as tenta novamente mais tarde, quando a conectividade estiver restauradas.

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

Ativar o Google Analytics do Workbox

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

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

googleAnalytics.initialize();

Esse é o único código necessário para enfileirar e tentar novamente solicitações com falhas no Google Analytics, e é a maneira mais simples de fazer com que o Google Analytics funcione off-line.

No entanto, se você usar apenas o código acima, as solicitações repetidas não poderão ser distinguidas das que são bem-sucedidas na primeira tentativa. Isso significa você recebe todos os dados de interação de usuários off-line, saber quais interações ocorreram enquanto o usuário estava off-line.

Para resolver esse problema, use uma das opções de configuração descritos abaixo para modificar ou anotar os dados que são enviados no fez uma nova tentativa de solicitação.

Como modificar quais dados são enviados

Se você quiser diferenciar as solicitações com e sem novas tentativas, 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. A opção parameterOverrides deve ser usada quando você quer definir o mesmo valor para um parâmetro específico em cada solicitação repetida. Use a opção hitFilter nos casos em que o valor de um parâmetro específico precisa ser calculado em 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 comparar on-line e off-line e interações. No entanto, você pode criar sua própria dimensão para exatamente esse propósito usando um recurso chamado dimensões personalizadas.

Para rastrear solicitações que foram reproduzidas pelo service worker usando uma com o Workbox Google Analytics, siga estas etapas:

  1. Crie uma nova dimensão personalizada no Google Analytics. Use um nome, como "Status da rede", e defina seu o escopo para "hit" (já que qualquer interação pode ser off-line).

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

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

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

googleAnalytics.initialize({
  parameterOverrides: {
    cd1: 'offline',
  },
});

  3. (Opcional) Como os valores em parameterOverrides são aplicados somente para solicitações repetidas ("off-line"), defina um valor padrão de "on-line" para todas as outras solicitações. Embora isso não seja estritamente necessário, ele facilita a leitura dos relatórios.

    Por exemplo, se você usou o snippet de acompanhamento padrão da analytics.js para instalar no Google Analytics, adicione a linha ga('set', 'dimension1', 'online') para usar um valor padrão de 'online' em seu "Status da rede" dimensão personalizada para todas as solicitações não 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>

Usar uma métrica personalizada para rastrear as solicitações de tempo gasto na fila

Se você quiser saber quanto tempo passou entre o momento em que uma interação off-line aconteceu e quando a conectividade foi restaurada e a solicitação foi refeita, é possível acompanhar 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 ele, como "Tempo de fila off-line", defina escopo para "hit", e defina o tipo de formatação como "Hora" (em segundos).

  2. Use a opção hitFilter para receber o valor do parâmetro qt e divida por 1.000 (para converter em segundos). Em seguida, defina esse valor como um parâmetro com o índice da métrica recém-criada. Se este for seu primeira métrica personalizada, o nome do parâmetro seria '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 o Google Analytics no Workbox

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

Tipos

GoogleAnalyticsInitializeOptions

Propriedades

  • cacheName

    string opcional

  • parameterOverrides

    objeto opcional

  • hitFilter

    void optional

    A função hitFilter é semelhante a esta: 

    (params: URLSearchParams) => {...}

    • params

      URLSearchParams

Métodos

initialize()

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

Parâmetros