workbox-google-analytics

Se stai creando un'applicazione che funziona offline, devi comprendere Il modo in cui gli utenti interagiscono con la tua app in assenza di connettività è fondamentale per ottimizzare l'esperienza.

Fornitori di servizi di analisi come Google Analytics richiede una rete connessione per inviare dati ai loro server, il che significa che se la connettività non disponibile, le richieste non andranno a buon fine e le interazioni non presenti nei report di Analytics. Sarà come se non fossero mai avvenuti.

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

Google Analytics riceve tutti i dati tramite richieste HTTP al Measurement Protocol, il che significa che uno script dei service worker può aggiungere un gestore di recupero per rilevare richieste non riuscite inviate a Measurement Protocol. Può archiviare questi dati in IndexedDB e riprova più tardi una volta che la connettività è ripristinato.

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

Attivazione di Google Analytics di Workbox

Per attivare Google Analytics per Workbox, 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 sopra, le richieste ritentate vengono indistinguibile dalle richieste che hanno esito positivo al primo tentativo. Ciò significa che riceverai tutti i dati sulle interazioni degli utenti offline, ma non potrai sapere quali interazioni si sono verificate quando l'utente era offline.

Per risolvere il problema, puoi utilizzare una delle opzioni di configurazione descritti di seguito per modificare o annotare i dati che vengono inviati nuovo tentativo.

Modificare i dati inviati

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

Queste opzioni ti consentono di modificare i parametri di Measurement Protocol inviati nella richiesta di nuovo tentativo. Opzione parameterOverrides deve essere utilizzata quando vuoi impostare lo stesso valore per un particolare per ogni richiesta ripetuta. Deve essere utilizzata l'opzione hitFilter nei casi in cui occorre calcolare il valore di un particolare parametro tempo di esecuzione o ricavato dal valore di un altro parametro.

Gli esempi riportati di seguito mostrano come utilizzare entrambe le opzioni.

Esempi:

Utilizzo di una dimensione personalizzata per monitorare le interazioni online e offline

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

Per tenere traccia delle richieste riprodotte dal service worker utilizzando un modello con Workbox Google Analytics, segui questi passaggi:

  1. Creare una nuova dimensione personalizzata in Google Analytics. Assegna un nome come "Stato rete" e imposta il suo ambito su "hit" (poiché qualsiasi interazione può essere offline).

  2. Prendi nota dell'indice assegnato alla dimensione appena creata e passa come nome del 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 sarà 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 di cui è stato eseguito il nuovo tentativo ("offline"), ti consigliamo di impostare anche un valore predefinito di "online" per tutte le altre richieste. Anche se non è strettamente necessario, renderà i report più facili da leggere.

    Ad esempio, se hai utilizzato lo snippet di monitoraggio analytics.js predefinito per installare Google Analytics, potresti aggiungere la riga ga('set', 'dimension1', 'online') per utilizzare il valore predefinito 'online' per lo "Stato della rete" dimensione personalizzata 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>
di Gemini Advanced.

Utilizzo di una metrica personalizzata per monitorare il tempo di attesa delle richieste in coda

Se vuoi sapere quanto tempo è trascorso tra il momento in cui si è verificata un'interazione offline e quello in cui la connettività è stata ripristinata e la richiesta è stata ripetuta correttamente, puoi monitorare questo dato 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 il suo 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). Imposta poi questo valore come parametro con l'indice della metrica appena creata. Se si tratta della 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);
  },
});

Workbox di test di Google Analytics

Poiché Workbox Google Analytics utilizza la sincronizzazione in background per riprodurre gli eventi, può essere difficile da testare. Scopri di più su Testare la sincronizzazione in background di Workbox.

Tipi

GoogleAnalyticsInitializeOptions

Proprietà

  • cacheName

    stringa facoltativo

  • parameterOverrides

    Oggetto facoltativo

  • hitFilter

    void optional

    La funzione hitFilter ha questo aspetto: 

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

    • params

      URLSearchParams

Metodi

initialize()

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

Parametri