workbox-google-analytics

Si estás compilando una aplicación que funciona sin conexión, es fundamental comprender cómo los usuarios interactúan con ella cuando no tienen conectividad.

Los proveedores de estadísticas, como Google Analytics, requieren una conexión de red para enviar datos a sus servidores, lo que significa que, si no hay conectividad disponible, esas solicitudes fallarán y esas interacciones no aparecerán en tus informes de estadísticas. Será como si nunca hubieran ocurrido.

Workbox Google Analytics resuelve este problema de los usuarios de Google Analytics aprovechando la capacidad del Service Worker para detectar solicitudes con errores.

Google Analytics recibe todos los datos a través de solicitudes HTTP al Protocolo de medición, lo que significa que una secuencia de comandos de Service Worker puede agregar un controlador de recuperación para detectar las solicitudes fallidas que se enviaron al Protocolo de medición. Puede almacenar estas solicitudes en IndexedDB y volver a intentarlo más tarde una vez que se restablezca la conectividad.

Workbox Google Analytics hace exactamente esto. También se agregan controladores de recuperación para almacenar en caché las secuencias de comandos analytics.js y gtag.js, de modo que también se puedan ejecutar sin conexión. Por último, cuando se reintentan las solicitudes con errores, Workbox Google Analytics también configura (o actualiza) automáticamente el qt en la carga útil de la solicitud para garantizar que las marcas de tiempo de Google Analytics reflejen la hora de la interacción original del usuario.

Habilitando Workbox de Google Analytics

Para habilitar Workbox de Google Analytics, llama al método initialize():

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

googleAnalytics.initialize();

Este es el único código necesario para poner en cola y reintentar las solicitudes fallidas a Google Analytics, y es la forma más sencilla de hacer que Google Analytics funcione sin conexión.

Sin embargo, si solo usas el código anterior, las solicitudes que se reintentaron no podrán distinguirse de las que se realizaron de forma correcta en el primer intento. Esto significa que recibirás todos los datos de interacción de los usuarios sin conexión, pero no podrás saber qué interacciones ocurrieron mientras el usuario estaba sin conexión.

Para abordar este problema, puedes usar una de las opciones de configuración que se describen a continuación a fin de modificar o anotar los datos que se envían en la solicitud que se reintentó.

Modifica qué datos se envían

Si deseas diferenciar las solicitudes que se reintentaron de aquellas que no lo hicieron, puedes especificar las opciones de configuración parameterOverrides o hitFilter.

Estas opciones te permiten modificar los parámetros del Protocolo de medición que se envían en la solicitud que se reintenta. La opción parameterOverrides debe usarse cuando deseas establecer el mismo valor para un parámetro en particular en cada solicitud reintentada. La opción hitFilter debe usarse en casos en los que el valor de un parámetro en particular debe calcularse en el tiempo de ejecución o derivar del valor de otro parámetro.

En los siguientes ejemplos, se muestra cómo usarías ambas opciones.

Ejemplos

Usar una dimensión personalizada para hacer un seguimiento de las interacciones en línea y sin conexión

Google Analytics no tiene una dimensión integrada para las interacciones en línea y sin conexión. Sin embargo, puedes crear tu propia dimensión para exactamente este propósito mediante una función llamada dimensiones personalizadas.

Para hacer un seguimiento de las solicitudes que volvió a reproducir el service worker mediante una dimensión personalizada con Workbox de Google Analytics, sigue estos pasos:

  1. Crea una nueva dimensión personalizada en Google Analytics. Asígnale un nombre como “Estado de la red” y establece su alcance en “hit” (ya que cualquier interacción puede ser sin conexión).

  2. Toma nota del índice asignado para la dimensión recién creada y pásalo como el nombre del parámetro a la opción de configuración parameterOverrides en el código de Workbox de Google Analytics.

    Por ejemplo, si esta es tu primera dimensión personalizada, su índice sería 1 y el nombre del parámetro sería cd1 (si el índice fuera 8, sería cd8):

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

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

  3. (Opcional) Debido a que los valores en parameterOverrides solo se aplican a las solicitudes que se reintentaron (“sin conexión”), te recomendamos establecer un valor predeterminado “en línea” para todas las demás solicitudes. Si bien esto no es estrictamente necesario, hará que tus informes sean más fáciles de leer.

    Por ejemplo, si utilizaste el fragmento de seguimiento analytics.js predeterminado para instalar Google Analytics, puedes agregar la línea ga('set', 'dimension1', 'online') para usar un valor predeterminado de 'online' en la dimensión personalizada "Estado de la red" para todas las solicitudes que el service worker no haya vuelto a reproducir.

    <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 una métrica personalizada para hacer un seguimiento del tiempo de las solicitudes que pasan en la cola

Si quisieras saber cuánto tiempo había transcurrido desde que se produjo una interacción sin conexión hasta que se restableció la conectividad y se reintentó la solicitud, puedes realizar un seguimiento con una métrica personalizada y la opción de configuración hitFilter:

  1. Crea una métrica personalizada nueva en Google Analytics. Asígnale un nombre como "Sin conexión", establece su alcance en "hit" y establece su tipo de formato en "Time" (en segundos).

  2. Usa la opción hitFilter para obtener el valor del parámetro qt y dividirlo por 1,000 (para convertirlo en segundos). Luego, configura ese valor como un parámetro con el índice de la métrica recién creada. Si esta es tu primera métrica personalizada, el nombre del parámetro sería 'cm1': 

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

googleAnalytics.initialize({
  hitFilter: (params) => {
    const queueTimeInSeconds = Math.round(params.get('qt') / 1000);
    params.set('cm1', queueTimeInSeconds);
  },
});

Prueba Workbox de Google Analytics

Debido a que Workbox de Google Analytics usa la sincronización en segundo plano para volver a reproducir eventos, las pruebas pueden resultar poco intuitivas. Obtén más información en Prueba la sincronización en segundo plano de la caja de trabajo.

Tipos

GoogleAnalyticsInitializeOptions

Propiedades

  • cacheName

    cadena opcional

  • parameterOverrides

    objeto opcional

  • hitFilter

    void opcional

    La función hitFilter se ve de la siguiente manera: 

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

    • params

      URLSearchParams

Métodos

initialize()

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

Parámetros