workbox-google-analytics

Wenn Sie eine Anwendung entwickeln, die offline funktioniert, ist es wichtig zu verstehen, wie Nutzer mit Ihrer App interagieren, wenn sie keine Internetverbindung haben.

Analytics-Anbieter 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 entsprechenden Interaktionen fehlen in Ihren Analyseberichten. Es ist, als wären sie nie passiert.

Mit Workbox Google Analytics wird dieses Problem für Google Analytics-Nutzer gelöst, da Service Worker fehlgeschlagene Anfragen erkennen können.

Google Analytics empfängt alle Daten über HTTP-Anfragen an das Measurement Protocol. Das bedeutet, dass ein Service Worker-Script einen Abruf-Handler hinzufügen kann, um fehlgeschlagene Anfragen an das Measurement Protocol zu erkennen. Diese Anfragen können in IndexedDB gespeichert und später noch einmal ausgeführt werden, sobald die Verbindung wiederhergestellt ist.

Genau das macht Workbox Google Analytics. Außerdem werden Abruf-Handler hinzugefügt, um die Scripts analytics.js und gtag.js im Cache zu speichern, damit sie auch offline ausgeführt werden können. Wenn fehlgeschlagene Anfragen noch einmal versucht werden, wird in Workbox Google Analytics außerdem automatisch das qt in der Anfragen-Nutzlast festgelegt (oder aktualisiert), damit die Zeitstempel in Google Analytics der Zeit der ursprünglichen Nutzerinteraktion entsprechen.

Google Analytics für Workbox aktivieren

Rufen Sie die Methode initialize() auf, um Google Analytics für Workbox zu aktivieren:

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

googleAnalytics.initialize();

Das ist der einzige Code, der erforderlich ist, um fehlgeschlagene Anfragen an Google Analytics in die Warteschlange zu stellen und noch einmal zu versuchen. Es ist die einfachste Möglichkeit, Google Analytics offline zu verwenden.

Wenn Sie jedoch nur den Code oben verwenden, sind die wiederholten Anfragen nicht von Anfragen zu unterscheiden, die beim ersten Versuch erfolgreich waren. Das bedeutet, dass Sie alle Interaktionsdaten von Offlinenutzern erhalten, aber nicht feststellen können, welche Interaktionen stattgefunden haben, während 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.

Festlegen, welche Daten gesendet werden

Wenn Sie zwischen Anfragen unterscheiden möchten, die wiederholt wurden, und solchen, die nicht wiederholt wurden, können Sie entweder die KonfigurationsoptionenparameterOverrides oder hitFilter angeben.

Mit diesen Optionen können Sie die Measurement Protocol-Parameter ändern, die in der wiederholten Anfrage gesendet werden. Die Option parameterOverrides sollte verwendet werden, wenn Sie für einen bestimmten Parameter bei jeder wiederholten Anfrage denselben Wert 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

Online- und Offlineinteraktionen mithilfe einer benutzerdefinierten Dimension erfassen

In Google Analytics gibt es keine integrierte Dimension für Online- und Offlineinteraktionen. Sie können jedoch mithilfe der Funktion benutzerdefinierte Dimensionen eine eigene Dimension für genau diesen Zweck erstellen.

So erfassen Sie mit einer benutzerdefinierten Dimension in Google Analytics mit Workbox-Unterstützung Anfragen, die vom Service Worker noch einmal abgespielt wurden:

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

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

    Wenn dies beispielsweise Ihre erste benutzerdefinierte Dimension ist, lautet ihr Index 1 und der Parametername cd1. Bei einem Index von 8 wäre der Parametername 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, können Sie für alle anderen Anfragen auch den Standardwert „online“ festlegen. Dies ist zwar nicht unbedingt erforderlich, aber es erleichtert die Lesbarkeit Ihrer Berichte.

    Wenn Sie beispielsweise das standardmäßige analytics.js-Tracking-Snippet verwendet haben, um Google Analytics zu installieren, können Sie die Zeile ga('set', 'dimension1', 'online') hinzufügen, um für alle Anfragen, die nicht vom Service Worker noch einmal abgespielt 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 Zeit erfassen, die Anfragen in der Warteschlange verbringen

Wenn Sie wissen möchten, wie viel Zeit zwischen einer Offlineinteraktion und der Wiederherstellung der Verbindung vergangen ist und die Anfrage erfolgreich wiederholt wurde, können Sie dies mit einem benutzerdefinierten Messwert und der Konfigurationsoption hitFilter erfassen:

  1. Erstellen Sie in Google Analytics einen neuen benutzerdefinierten Messwert. Geben Sie einen Namen wie „Offline-Warteschlangenzeit“ ein, legen Sie den Umfang auf „Treffer“ fest und wählen Sie als Formatierungstyp „Zeit“ (in Sekunden) aus.

  2. Verwenden Sie die Option hitFilter, um den Wert des Parameters qt abzurufen und durch 1.000 zu teilen, um ihn in Sekunden umzuwandeln. Legen Sie diesen Wert dann 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-Tests

Da in Workbox Google Analytics Ereignisse mithilfe der Hintergrundsynchronisierung wiedergegeben werden, ist das Testen nicht immer intuitiv. Weitere Informationen finden Sie unter Workbox-Hintergrundsynchronisierung testen.

Typen

GoogleAnalyticsInitializeOptions

Attribute

  • cacheName

    String optional

  • parameterOverrides

    object optional

  • hitFilter

    void optional

    Die hitFilter-Funktion sieht so aus: 

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

    • params

      URLSearchParams

Methoden

initialize()

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

Parameter