#workbox-google-analytics

オフラインで動作するアプリを構築している場合、ユーザーが接続していないときにアプリをどのように操作しているかを把握することは、そのエクスペリエンスを最適化するために不可欠です。

Google アナリティクスなどの分析プロバイダでは、サーバーにデータを送信するためにネットワーク接続が必要です。つまり、接続が利用できない場合、リクエストは失敗し、分析レポートからそれらのインタラクションは失われます。そんなことないよ。

Workbox Google アナリティクスは、Service Worker の失敗したリクエストを検出する機能を利用して、Google アナリティクス ユーザーがこの問題を解決します。

Google アナリティクスでは、Measurement Protocol への HTTP リクエストを介してすべてのデータを受信します。つまり、Service Worker スクリプトでフェッチ ハンドラを追加して、Measurement Protocol に送信された失敗したリクエストを検出できます。これらのリクエストを IndexedDB に保存し、接続が回復してから再試行できます。

Workbox Google アナリティクスはまさにそのためです。また、analytics.js スクリプトと gtag.js スクリプトをキャッシュに保存する取得ハンドラも追加されるため、オフラインで実行することもできます。最後に、失敗したリクエストが再試行されると、Workbox Google アナリティクスはリクエスト ペイロードの qt を自動的に設定（または更新）し、Google アナリティクスのタイムスタンプに元のユーザー操作の時刻が反映されるようにします。

Workbox Google アナリティクスの有効化

Workbox Google アナリティクスを有効にするには、initialize() メソッドを呼び出します。

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

googleAnalytics.initialize();

これは、Google アナリティクスへの失敗したリクエストをキューに入れて再試行するために必要な唯一のコードであり、Google アナリティクスをオフラインで動作させる最も簡単な方法です。

ただし、上記のコードのみを使用した場合、再試行されたリクエストは、最初の試行で成功するリクエストと区別がつきません。つまり、オフライン ユーザーからすべてのインタラクション データを受け取りますが、ユーザーがオフラインの間に発生したインタラクションは識別できません。

この問題に対処するには、以下で説明する構成オプションのいずれかを使用して、再試行されたリクエストで送信されるデータを変更するか、アノテーションを付けます。

送信されるデータの変更

再試行されたリクエストと再試行されないリクエストを区別できるようにするには、parameterOverrides または hitFilter の構成オプションを指定します。

このオプションを使用すると、再試行されたリクエストで送信される Measurement Protocol パラメータを変更できます。parameterOverrides オプションは、再試行されるすべてのリクエストの特定のパラメータに同じ値を設定する場合に使用します。hitFilter オプションは、特定のパラメータの値を実行時に計算する場合や、別のパラメータの値から派生させる必要がある場合に使用します。

以下の例は、両方のオプションの使用方法を示しています。

例

カスタム ディメンションを使ってオンラインとオフラインのインタラクションをトラッキングする

Google アナリティクスには、オンラインとオフラインのインタラクションを示す組み込みディメンションはありません。ただし、カスタム ディメンションと呼ばれる機能を使用して、まさにこの目的のために独自のディメンションを作成できます。

Workbox Google アナリティクスでカスタム ディメンションを使用して Service Worker がリプレイしたリクエストを追跡するには、次の手順を行います。

1. Google アナリティクスで新しいカスタム ディメンションを作成します。「Network Status」などの名前を付け、スコープを「ヒット」に設定します（どのインタラクションもオフラインになる可能性があるため）。

2. 新しく作成したディメンションに割り当てられたインデックスをメモし、それをパラメータ名として Workbox の Google アナリティクス コードの parameterOverrides 設定オプションに渡します。

   たとえば、これが最初のカスタム ディメンションの場合、インデックスは 1、パラメータ名は cd1 になります（インデックスが 8 の場合は cd8 になります）。

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

3. （省略可）parameterOverrides の値は再試行された（「オフライン」）リクエストにのみ適用されるため、他のすべてのリクエストにはデフォルト値の「online」を設定することもできます。必須ではありませんが、これでレポートが見やすくなります。
   
   たとえば、デフォルトの analytics.js トラッキング スニペットを使用して Google アナリティクスをインストールした場合は、ga('set', 'dimension1', 'online') という行を追加して、Service Worker でリプレイされないすべてのリクエストについて、「ネットワーク ステータス」カスタム ディメンションにデフォルト値の 'online' を使用できます。

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

カスタム指標を使用してリクエストがキューで費やされた時間を追跡する

オフライン インタラクションが発生してから、接続が回復してリクエストが正常に再試行されるまでの経過時間を確認したい場合は、カスタム指標と hitFilter 構成オプションを使用してこれを追跡できます。

1. Google アナリティクスで新しいカスタム指標を作成します。「Offline Queue Time」などの名前を付け、スコープを「hit」に設定し、書式タイプを「Time」（秒単位）に設定します。

2. hitFilter オプションを使用して qt パラメータの値を取得し、1,000 で割ります（秒に変換します）。次に、その値を、新しく作成された指標のインデックスを含むパラメータとして設定します。これが最初のカスタム指標である場合、パラメータ名は '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 アナリティクスのテスト

Workbox の Google アナリティクスはバックグラウンド同期を使用してイベントをリプレイするため、テストが直感に欠ける場合があります。詳しくは、ワークボックスのバックグラウンド同期のテストをご覧ください。

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