zone-de-travail-google-analytics

Si vous créez une application qui fonctionne hors connexion, il est essentiel de comprendre comment les utilisateurs interagissent avec votre application lorsqu'ils n'ont pas de connexion pour optimiser cette expérience.

Les fournisseurs d'analyse tels que Google Analytics nécessitent une connexion réseau pour envoyer des données à leurs serveurs. Par conséquent, si la connectivité n'est pas disponible, ces requêtes échoueront et ces interactions ne figureront pas dans vos rapports d'analyse. Comme si elles n'avaient jamais eu lieu.

Workbox Google Analytics résout ce problème pour les utilisateurs de Google Analytics en exploitant la capacité du service worker à détecter les requêtes ayant échoué.

Google Analytics reçoit toutes les données via des requêtes HTTP envoyées au protocole de mesure. Par conséquent, un script de service worker peut ajouter un gestionnaire de récupération pour détecter les requêtes envoyées au protocole de mesure qui échouent. Il peut stocker ces requêtes dans IndexedDB, puis les réessayer plus tard une fois la connectivité rétablie.

Workbox Google Analytics permet exactement cela. Il ajoute également des gestionnaires de récupération pour mettre en cache les scripts analytics.js et gtag.js afin qu'ils puissent également être exécutés hors connexion. Enfin, lorsque les requêtes échouées sont réessayées, Workbox Google Analytics définit (ou met à jour) automatiquement le qt dans la charge utile de la requête pour s'assurer que les codes temporels dans Google Analytics reflètent l'heure de l'interaction utilisateur d'origine.

Activer Google Analytics pour Workbox

Pour activer Google Analytics Workbox, appelez la méthode initialize():

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

googleAnalytics.initialize();

Il s'agit du seul code requis pour mettre en file d'attente et réessayer les requêtes Google Analytics qui ont échoué. Il s'agit du moyen le plus simple de faire fonctionner Google Analytics hors connexion.

Toutefois, si vous n'utilisez que le code ci-dessus, les requêtes réessayées sont indiscernables des requêtes qui réussissent au premier essai. Cela signifie que vous recevrez toutes les données d'interaction des utilisateurs hors connexion, mais vous ne pourrez pas déterminer quelles interactions ont eu lieu lorsque l'utilisateur était hors connexion.

Pour résoudre ce problème, vous pouvez utiliser l'une des options de configuration décrites ci-dessous pour modifier ou annoter les données envoyées dans la requête réessayée.

Modifier les données envoyées

Si vous souhaitez pouvoir différencier les requêtes réessayées des requêtes non réessayées, vous pouvez spécifier les options de configuration parameterOverrides ou hitFilter.

Ces options vous permettent de modifier les paramètres du protocole de mesure envoyés dans la requête réessayée. L'option parameterOverrides doit être utilisée lorsque vous souhaitez définir la même valeur pour un paramètre particulier pour chaque requête réessayée. L'option hitFilter doit être utilisée lorsque la valeur d'un paramètre particulier doit être calculée au moment de l'exécution ou dérivée de la valeur d'un autre paramètre.

Les exemples ci-dessous montrent comment utiliser ces deux options.

Exemples

Utiliser une dimension personnalisée pour suivre les interactions en ligne et hors connexion

Google Analytics ne propose pas de dimension intégrée pour les interactions en ligne et hors ligne. Toutefois, vous pouvez créer votre propre dimension à cet effet à l'aide d'une fonctionnalité appelée dimensions personnalisées.

Pour suivre les requêtes qui ont été rejouées par le service worker à l'aide d'une dimension personnalisée avec Workbox Google Analytics, procédez comme suit:

  1. Créez une dimension personnalisée dans Google Analytics. Nommez-la "État du réseau" et définissez sa portée sur "hit" (puisque toute interaction peut être hors connexion).

  2. Notez l'index attribué à la dimension nouvellement créée et transmettez-le en tant que nom de paramètre à l'option de configuration parameterOverrides dans votre code Google Analytics Workbox.

    Par exemple, s'il s'agit de votre première dimension personnalisée, son indice sera 1 et le nom du paramètre sera cd1 (si l'indice était 8, il serait cd8):

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

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

  3. (Facultatif) Étant donné que les valeurs de parameterOverrides ne sont appliquées qu'aux requêtes réessayées ("hors connexion"), vous pouvez également définir la valeur par défaut sur "en ligne" pour toutes les autres requêtes. Bien que cela ne soit pas strictement nécessaire, cela facilitera la lecture de vos rapports.

    Par exemple, si vous avez utilisé l'extrait de suivi analytics.js par défaut pour installer Google Analytics, vous pouvez ajouter la ligne ga('set', 'dimension1', 'online') pour utiliser une valeur par défaut de 'online' pour votre dimension personnalisée "État du réseau" pour toutes les requêtes non répétées par le 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>

Utiliser une métrique personnalisée pour suivre le temps passé par les requêtes dans la file d'attente

Si vous souhaitez savoir combien de temps s'est écoulé entre le moment où une interaction hors connexion a eu lieu et le moment où la connectivité a été rétablie et que la requête a été réessayée avec succès, vous pouvez le suivre à l'aide d'une métrique personnalisée et de l'option de configuration hitFilter:

  1. Créez une métrique personnalisée dans Google Analytics. Nommez-la "Temps d'attente dans la file d'attente hors connexion", définissez sa portée sur "hit" et son type de mise en forme sur "Temps" (en secondes).

  2. Utilisez l'option hitFilter pour obtenir la valeur du paramètre qt et la diviser par 1 000 (pour la convertir en secondes). Définissez ensuite cette valeur en tant que paramètre avec l'indice de la métrique créée. S'il s'agit de votre première métrique personnalisée, le nom du paramètre sera 'cm1': 

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

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

Tester Workbox Google Analytics

Comme Workbox Google Analytics utilise la synchronisation en arrière-plan pour rejouer les événements, les tests peuvent être peu intuitifs. Pour en savoir plus, consultez Tester la synchronisation en arrière-plan de Workbox.

Types

GoogleAnalyticsInitializeOptions

Propriétés

  • cacheName

    chaîne facultatif

  • parameterOverrides

    objet facultatif

  • hitFilter

    void facultatif

    La fonction hitFilter se présente comme suit : 

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

    • params

      URLSearchParams

Méthodes

initialize()

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

Paramètres