workbox-google-analytics

Wenn Sie eine Anwendung erstellen, die offline funktioniert, ist es wichtig zu wissen, wie Nutzer mit Ihrer Anwendung interagieren, wenn sie keine Verbindung haben, um diese Erfahrung zu optimieren.

Analyseanbieter wie Google Analytics benötigen eine Netzwerkverbindung, um Daten an ihre Server zu senden. Wenn keine Verbindung verfügbar ist, schlagen diese Anfragen fehl und die Interaktionen sind nicht in Ihren Analyseberichten enthalten. Sie werden so sein, als hätten sie nie stattgefunden.

Workbox Google Analytics löst dieses Problem für Google Analytics-Nutzer, indem es die Fähigkeit des Service Workers nutzt, fehlgeschlagene Anfragen zu erkennen.

Google Analytics empfängt alle Daten über HTTP-Anfragen an das Measurement Protocol. Ein Service Worker-Skript kann also einen Abruf-Handler hinzufügen, um fehlgeschlagene Anfragen zu erkennen, die an das Measurement Protocol gesendet werden. Sie kann diese Anfragen in IndexedDB speichern und später wiederholen, sobald die Verbindung wiederhergestellt ist.

Workbox Google Analytics macht genau das. Außerdem werden Abruf-Handler hinzugefügt, um die Skripts analytics.js und gtag.js im Cache zu speichern, damit sie auch offline ausgeführt werden können. Wenn fehlgeschlagene Anfragen wiederholt werden, legt Workbox Google Analytics automatisch den qt in der Anfragenutzlast fest (oder aktualisiert ihn), damit die Zeitstempel in Google Analytics den Zeitpunkt der ursprünglichen Nutzerinteraktion widerspiegeln.

Workbox Google Analytics wird aktiviert

Um Workbox Google Analytics zu aktivieren, rufen Sie die Methode initialize() auf:

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

googleAnalytics.initialize();

Er ist der einzige Code, der für das Senden und Wiederholen fehlgeschlagener Anfragen an Google Analytics in die Warteschlange gestellt und wiederholt werden muss. Außerdem ist er die einfachste Methode, um Google Analytics offline auszuführen.

Wenn Sie jedoch nur den obigen Code verwenden, sind die wiederholten Anfragen nicht von Anfragen zu unterscheiden, die beim ersten Versuch erfolgreich waren. Sie erhalten also alle Interaktionsdaten von Offlinenutzern, können aber nicht erkennen, welche Interaktionen stattgefunden haben, als der Nutzer offline war.

Sie können eine der unten beschriebenen Konfigurationsoptionen verwenden, um die Daten zu ändern oder zu annotieren, die in der wiederholten Anfrage gesendet werden.

Ändern, welche Daten gesendet werden

Wenn Sie zwischen wiederholten Anfragen und nicht wiederholten Anfragen unterscheiden möchten, können Sie die Konfigurationsoptionen parameterOverrides oder hitFilter angeben.

Mit diesen Optionen können Sie die Measurement Protocol-Parameter ändern, die bei der wiederholten Anfrage gesendet werden. Die Option parameterOverrides sollte verwendet werden, wenn Sie bei jeder wiederholten Anfrage denselben Wert für einen bestimmten Parameter festlegen möchten. Die Option hitFilter sollte verwendet werden, wenn der Wert eines bestimmten Parameters zur Laufzeit berechnet oder aus dem Wert eines anderen Parameters abgeleitet werden muss.

Die folgenden Beispiele zeigen, wie Sie beide Optionen verwenden.

Beispiele

Mit einer benutzerdefinierten Dimension Online- und Offlineinteraktionen erfassen

Google Analytics hat keine integrierte Dimension für Online- und Offlineinteraktionen. Mit der Funktion Benutzerdefinierte Dimensionen können Sie jedoch auch eine eigene Dimension für genau diesen Zweck erstellen.

So verfolgen Sie Anfragen, die vom Service Worker mithilfe einer benutzerdefinierten Dimension mit Workbox Google Analytics wiederholt wurden:

  1. Erstellen Sie eine neue benutzerdefinierte Dimension in Google Analytics. Geben Sie ihm einen Namen wie „Netzwerkstatus“ und legen Sie als Umfang auf „hit“ fest, da jede Interaktion offline sein kann.

  2. Notieren Sie sich den Index, der der neu erstellten Dimension zugewiesen ist, und übergeben Sie ihn als Parameternamen an die Konfigurationsoption parameterOverrides in Ihrem Google Analytics-Code für die Workbox.

    Wenn dies beispielsweise Ihre erste benutzerdefinierte Dimension ist, wäre der Index 1 und der Parametername cd1 (wenn der Index 8 wäre, wäre er cd8):

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

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

  3. Optional: Da Werte in parameterOverrides nur auf wiederholte ("Offline")-Anfragen angewendet werden, sollten Sie auch für alle anderen Anfragen den Standardwert "online" festlegen. Dies ist zwar nicht unbedingt notwendig, verbessert jedoch die Lesbarkeit Ihrer Berichte.

    Wenn Sie Google Analytics beispielsweise mit dem standardmäßigen analytics.js-Tracking-Snippet installiert haben, können Sie die Zeile ga('set', 'dimension1', 'online') hinzufügen, um für alle Anfragen, die vom Service Worker nicht wiedergegeben werden, den Standardwert 'online' für die benutzerdefinierte Dimension „Netzwerkstatus“ zu verwenden.

    <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>

Mit einem benutzerdefinierten Messwert die in der Warteschlange verbrachte Zeit erfassen

Wenn Sie wissen möchten, wie viel Zeit zwischen dem Zeitpunkt einer Offlineinteraktion, der Wiederherstellung der Verbindung und der erfolgreichen Wiederholung der Anfrage vergangen ist, können Sie dies mit einem benutzerdefinierten Messwert und der Konfigurationsoption hitFilter verfolgen:

  1. Erstellen Sie einen neuen benutzerdefinierten Messwert in Google Analytics. Geben Sie ihm einen Namen wie „Offline Queue Time“, legen Sie den Bereich auf „hit“ und den Formatierungstyp „Time“ (in Sekunden) fest.

  2. Verwenden Sie die Option hitFilter, um den Wert des Parameters qt abzurufen und durch 1.000 zu teilen, um ihn in Sekunden umzurechnen. Legen Sie dann diesen Wert als Parameter mit dem Index des neu erstellten Messwerts fest. Wenn dies Ihr erster benutzerdefinierter Messwert ist, lautet der Parametername '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 Google Analytics testen

Da Workbox Google Analytics die Hintergrundsynchronisierung zur Wiederholung von Ereignissen verwendet, ist der Test möglicherweise nicht intuitiv. Weitere Informationen finden Sie unter Workbox-Hintergrundsynchronisierung testen.

Typen

GoogleAnalyticsInitializeOptions

Attribute

  • cacheName

    String optional

  • parameterOverrides

    Objekt optional

  • hitFilter

    void optional

    Die Funktion hitFilter sieht so aus: 

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

    • params

      URLSearchParams

Methoden

initialize()

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

Parameters