Workbox-google-analytics

Jeśli tworzysz aplikację, która działa w trybie offline, musisz wiedzieć, jak użytkownicy korzystają z aplikacji, gdy nie mają połączenia z internetem. Jest to kluczowe dla optymalizacji działania aplikacji.

Dostawcy usług analitycznych, tacy jak Google Analytics wymaga sieci wysyła dane na ich serwery, co oznacza, że jeśli połączenie jest niedostępne, te żądania zakończą się niepowodzeniem, a interakcje zostaną których brakuje w raportach statystycznych. Zupełnie tak, jakby nigdy nic się nie stało.

Workbox Google Analytics rozwiązuje ten problem dzięki wykorzystanie możliwości wykrywania nieudanych żądań przez mechanizmy Service Worker.

Google Analytics otrzymuje wszystkie dane przez żądania HTTP wysyłane do Measurement Protocol, co oznacza, że skrypt service worker może dodać moduł obsługi pobierania w celu wykrywania wysłanych do Measurement Protocol. Może on przechowywać te żądania w IndexedDB, a potem ponownie wysyłać je, gdy tylko połączenie zostanie przywrócone.

Do tego właśnie służy Google Analytics. Dodaje też funkcję pobierania moduły obsługi buforowania analytics.js oraz gtag.js dzięki czemu można je również uruchamiać offline. Wreszcie, jeśli nieudane żądania są Google Analytics automatycznie ustawia (lub aktualizuje) także qt w ładunku żądania, tak by sygnatury czasowe w Google Analytics odzwierciedlały czas pierwotnej interakcji z użytkownikiem.

Włączanie Google Analytics w Workbox

Aby włączyć Google Analytics w Workbox, wywołaj metodę initialize():

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

googleAnalytics.initialize();

To jedyny kod wymagany do umieszczania w kole i powtarzania nieudanych próśb wysyłanych do Google Analytics. Jest to też najprostszy sposób na uruchomienie Google Analytics w trybie offline.

Jeśli jednak używasz tylko powyższego kodu, ponawiane żądania są nie da się odróżnić od tych, które okażą się skuteczne za pierwszym razem. Oznacza to, że otrzymasz wszystkie dane o interakcjach użytkowników offline, ale nie będziesz mieć możliwości określenia, które interakcje miały miejsce, gdy użytkownik był offline.

Aby rozwiązać ten problem, możesz użyć jednego z opcji konfiguracji opisanych poniżej, aby zmodyfikować lub opatrzyć adnotacjami dane wysyłane w powtórzonej prośbie.

Modyfikowanie danych, które mają być wysyłane

Jeśli chcesz mieć możliwość odróżniania ponownych żądań od tych, które nie zostały ponowione możesz określić parameterOverrides albo hitFilter opcji konfiguracji.

Te opcje umożliwiają modyfikowanie parametrów protokołu Measurement Protocol, które są wysyłane w powtórzonym żądaniu. Opcji parameterOverrides należy używać, gdy chcesz ustawić tę samą wartość danego parametru w przypadku każdego żądania, które zostało wysłane ponownie. Opcji hitFilter należy używać w przypadkach, gdy wartość danego parametru musi być obliczana w czasie wykonywania lub pochodzić z wartości innego parametru.

Poniższe przykłady pokazują, jak możesz korzystać z obu tych opcji.

Przykłady

Używanie wymiaru niestandardowego do śledzenia interakcji online i offline

Google Analytics nie ma wbudowanej wymiany dotyczącej interakcji online i offline. Możesz jednak utworzyć własny wymiar, by za pomocą funkcji wymiarów niestandardowych.

Aby śledzić za pomocą Google Analytics Workbox żądania odtworzone przez service workera za pomocą wymiaru niestandardowego, wykonaj te czynności:

1. Utwórz nowy wymiar niestandardowy w Google Analytics. Nadaj mu nazwę, np. „Stan sieci”, i ustaw zakres na „hit” (ponieważ każda interakcja może odbywać się w trybie offline).

2. Zanotuj indeks przypisany do nowo utworzonego wymiaru i przekaż go jako nazwę parametru do opcji konfiguracji parameterOverrides w kodzie Google Analytics Workbox.

   Jeśli np. jest to pierwszy wymiar niestandardowy, jego indeks będzie wyglądać tak: 1, a nazwa parametru będzie miała postać cd1 (jeśli indeks będzie miał wartość 8, to cd8):

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

3. (Opcjonalnie) Ponieważ wartości w polu parameterOverrides są stosowane tylko do powtórnych („offline”) żądań, warto też ustawić wartość domyślną „online” dla wszystkich innych żądań. Nie jest to konieczne, ale ułatwia czytanie raportów.
   
   Na przykład: jeśli używasz domyślnego fragmentu kodu śledzenia analytics.js do instalacji Google Analytics, możesz dodać wiersz ga('set', 'dimension1', 'online') aby użyć domyślnej wartości 'online' w kolumnie „Stan sieci” wymiar niestandardowy dla wszystkich żądań, które nie zostały ponownie odtworzone przez skrypt 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>
   

Śledzenie czasu oczekiwania żądań w kolejce za pomocą danych niestandardowych

Jeśli chcesz wiedzieć, ile czasu minęło od interakcji offline do przywrócenia połączenia i powtórnego wysłania żądania, możesz to śledzić za pomocą danych niestandardowych i opcji konfiguracji hitFilter:

1. Tworzenie nowych danych niestandardowych w Google Analytics. Nadaj mu nazwę, np. „Offline Queue Time”, ustaw zakres na „hit” i ustaw typ formatowania na „Czas” (w sekundach).

2. Użyj opcji hitFilter, aby uzyskać wartość parametru qt, i podziel ją przez 1000 (aby przeliczyć ją na sekundy). Następnie ustaw tę wartość jako parametr z indeksem nowo utworzonych wskaźników. Jeśli są to pierwsze dane niestandardowe, nazwa parametru będzie wyglądać tak: 'cm1':

   import * as googleAnalytics from 'workbox-google-analytics';
   
   googleAnalytics.initialize({
     hitFilter: (params) => {
       const queueTimeInSeconds = Math.round(params.get('qt') / 1000);
       params.set('cm1', queueTimeInSeconds);
     },
   });
   

Testowanie Workboxa w Google Analytics

Google Analytics używa synchronizacji w tle do odtwarzania zdarzeń Workbox, dzięki czemu może ich testowanie jest nieintuicyjne. Więcej informacji znajdziesz w artykule Testowanie synchronizacji Workboxa w tle.

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