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 ne disposent pas de connectivité pour optimiser cette expérience.

Les fournisseurs de solutions d'analyse tels que Google Analytics ont besoin d'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. C'est comme si ce n'était jamais le cas.

Workbox Google Analytics résout ce problème pour les utilisateurs de Google Analytics en exploitant la capacité de 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, ce qui signifie qu'un script de service de calcul peut ajouter un gestionnaire de récupération pour détecter les requêtes ayant échoué envoyées au protocole de mesure. Il peut stocker ces requêtes dans IndexedDB, puis les relancer ultérieurement une fois la connectivité restaurée.

C'est exactement ce que fait Google Analytics pour Workbox. 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 des requêtes ayant échoué font l'objet de nouvelles tentatives, Workbox Google Analytics définit (ou met à jour) automatiquement le qt dans la charge utile de la requête pour que les horodatages dans Google Analytics reflètent l'heure de l'interaction utilisateur d'origine.

Activation de Workbox Google Analytics

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

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

googleAnalytics.initialize();

Il s'agit du seul code nécessaire pour mettre en file d'attente et relancer les requêtes ayant échoué dans Google Analytics, et c'est le moyen le plus simple de faire fonctionner Google Analytics hors connexion.

Toutefois, si vous n'utilisez que le code ci-dessus, les nouvelles requêtes peuvent être différenciées des requêtes qui aboutissent au premier essai. Cela signifie que vous recevrez toutes les données d'interaction des utilisateurs hors connexion, mais vous ne pourrez pas savoir quelles interactions se sont produites 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 nouvelle requête.

Modifier les données envoyées

Si vous souhaitez pouvoir différencier les requêtes ayant fait l'objet d'une nouvelle tentative des requêtes qui n'ont pas été relancé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 faisant l'objet d'une nouvelle tentative. Utilisez l'option parameterOverrides si vous souhaitez définir la même valeur pour un paramètre particulier lors de chaque nouvelle tentative. 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 illustrent comment vous pouvez utiliser ces deux options.

Exemples

Effectuer le suivi des interactions en ligne et hors connexion à l'aide d'une dimension personnalisée

Google Analytics ne propose pas de dimension intégrée pour les interactions en ligne et hors connexion. Cependant, vous pouvez créer votre propre dimension à cette fin à l'aide de la fonctionnalité appelée dimensions personnalisées.

Pour suivre les requêtes répété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. Attribuez-lui un nom tel que "État du réseau" et définissez son champ d'application sur "hit" (puisque toute interaction peut être hors connexion).

2. Prenez note de l'index attribué à la nouvelle dimension et transmettez-le en tant que nom de paramètre à l'option de configuration parameterOverrides dans le code Google Analytics de votre boîte de travail.

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

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

3. (Facultatif) Étant donné que les valeurs dans parameterOverrides ne sont appliquées qu'aux requêtes relancées ("hors connexion"), vous pouvez également définir la valeur par défaut "online" pour toutes les autres requêtes. Bien que ce 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') afin d'utiliser la valeur par défaut '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 que les requêtes passent 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é restaurée et la requête a été relancée, vous pouvez suivre cela à 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. Donnez-lui un nom tel que "Temps d'attente hors connexion", définissez son champ d'application sur "hit", puis définissez son type de format 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). Ensuite, définissez cette valeur en tant que paramètre avec l'index de la métrique que vous venez de créer. 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);
     },
   });
   

Test de Workbox Google Analytics

Étant donné que Workbox Google Analytics utilise la synchronisation en arrière-plan pour relire des événements, les tests peuvent ne pas être intuitifs. Pour en savoir plus, consultez la page Tester la synchronisation en arrière-plan de Workbox.

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