workbox-google-analytics

Se stai creando un'applicazione che funziona offline, capire in che modo gli utenti interagiscono con l'app quando non sono connessi è fondamentale per ottimizzare l'esperienza.

I provider di analisi come Google Analytics richiedono una connessione di rete per inviare dati ai propri server, il che significa che se la connettività non è disponibile, queste richieste non andranno a buon fine e le interazioni non saranno presenti nei report di analisi. Sarà come se non fossero mai capitati.

Google Analytics Workbox risolve questo problema per gli utenti di Google Analytics sfruttando la capacità del service worker di rilevare le richieste non riuscite.

Google Analytics riceve tutti i dati tramite richieste HTTP a Measurement Protocol, il che significa che uno script di Service Worker può aggiungere un gestore di recupero per rilevare le richieste non riuscite inviate a Measurement Protocol. Può archiviare queste richieste in IndexedDB e poi riprovare in un secondo momento una volta ripristinata la connettività.

Workbox Google Analytics fa esattamente questo. Inoltre, aggiunge gestori di recupero per memorizzare nella cache gli script analytics.js e gtag.js, in modo che possano essere eseguiti anche offline. Infine, quando le richieste non riuscite vengono tentate di nuovo, Google Analytics Workbox imposta (o aggiorna) automaticamente qt nel payload della richiesta per garantire che i timestamp in Google Analytics riflettano il momento dell'interazione originale dell'utente.

Attivazione di Google Analytics in Workbox

Per abilitare Workbox Google Analytics, chiama il metodo initialize():

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

googleAnalytics.initialize();

Questo è l'unico codice necessario per mettere in coda e riprovare le richieste non riuscite a Google Analytics ed è il modo più semplice per far funzionare Google Analytics offline.

Tuttavia, se utilizzi solo il codice riportato sopra, le richieste ripetute non sono distinguibili da quelle che hanno esito positivo al primo tentativo. Ciò significa che riceverai tutti i dati sulle interazioni dagli utenti offline, ma non potrai sapere quali interazioni si sono verificate mentre l'utente era offline.

Per risolvere questo problema, puoi utilizzare una delle opzioni di configurazione descritte di seguito per modificare o annotare i dati inviati nella richiesta ripetuta.

Modificare i dati inviati

Se vuoi essere in grado di distinguere le richieste tentate nuovamente da quelle non tentate, puoi specificare le opzioni di configurazione parameterOverrides o hitFilter.

Queste opzioni consentono di modificare i parametri di Measurement Protocol inviati nella richiesta ripetuta. L'opzione parameterOverrides deve essere utilizzata quando vuoi impostare lo stesso valore per un determinato parametro per ogni richiesta riprovata. L'opzione hitFilter deve essere utilizzata nei casi in cui il valore di un determinato parametro deve essere calcolato in tempo di esecuzione o derivato dal valore di un altro parametro.

I seguenti esempi mostrano come utilizzare entrambe le opzioni.

Esempi

Utilizzare una dimensione personalizzata per monitorare le interazioni online e offline

Google Analytics non dispone di una dimensione integrata per le interazioni online e offline. Tuttavia, puoi creare una dimensione personalizzata proprio per questo scopo utilizzando una funzionalità chiamata dimensioni personalizzate.

Per monitorare le richieste che sono state riprodotte dal service worker utilizzando una dimensione personalizzata con Workbox Google Analytics, procedi nel seguente modo:

  1. Crea una nuova dimensione personalizzata in Google Analytics. Assegnale un nome come "Stato rete" e imposta l'ambito su "hit" (dal momento che qualsiasi interazione può essere offline).

  2. Prendi nota dell'indice assegnato alla dimensione appena creata e trasferiscilo come nome parametro all'opzione di configurazione parameterOverrides nel codice Google Analytics della casella di lavoro.

    Ad esempio, se questa è la tua prima dimensione personalizzata, il suo indice sarà 1 e il nome del parametro sarebbe cd1 (se l'indice fosse 8, sarebbe cd8):

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

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

  3. (Facoltativo) Poiché i valori in parameterOverrides vengono applicati solo alle richieste tentate nuovamente ("offline"), ti consigliamo di impostare anche un valore predefinito "online" per tutte le altre richieste. Anche se non è strettamente necessario, semplifica la lettura dei report.

    Ad esempio, se hai utilizzato lo snippet di monitoraggio analytics.js predefinito per installare Google Analytics, potresti aggiungere la riga ga('set', 'dimension1', 'online') in modo da utilizzare il valore predefinito 'online' per la dimensione personalizzata "Stato rete" per tutte le richieste non riprodotte dal 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>

Utilizzo di una metrica personalizzata per monitorare le richieste di tempo passate in coda.

Se vuoi sapere quanto tempo è trascorso tra quando si è verificata un'interazione offline e quando è stata ripristinata la connettività e quando la richiesta è stata ritentata, puoi monitorare questo comportamento utilizzando una metrica personalizzata e l'opzione di configurazione hitFilter:

  1. Crea una nuova metrica personalizzata in Google Analytics. Assegna un nome come "Tempo coda offline", imposta l'ambito su "hit" e imposta il tipo di formattazione su "Tempo" (in secondi).

  2. Utilizza l'opzione hitFilter per ottenere il valore del parametro qt e dividerlo per 1000 (per convertirlo in secondi). Poi impostalo come parametro con l'indice della metrica appena creata. Se questa è la tua prima metrica personalizzata, il nome del parametro sarà '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 di Google Analytics di Workbox

Poiché Google Analytics in Workbox utilizza la sincronizzazione in background per riprodurre gli eventi, eseguire dei test può non essere intuitivo. Per saperne di più, consulta la pagina Test della sincronizzazione in background della casella di lavoro.

Tipi

GoogleAnalyticsInitializeOptions

Proprietà

  • cacheName

    stringa facoltativo

  • parameterOverrides

    oggetto facoltativo

  • hitFilter

    void facoltativo

    La funzione hitFilter ha il seguente aspetto: 

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

    • params

      URLSearchParams

Metodi

initialize()

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

Parametri