Workbox-google-analytics

如果您建構的應用程式可在離線狀態下運作，那麼瞭解使用者沒有網路連線時，如何與應用程式互動，才能提供最佳體驗。

Google Analytics (分析) 等分析服務供應商需要網路連線，才能將資料傳送至他們的伺服器，這表示如果沒有可用的連線，這些要求就會失敗，且分析報表中也不會顯示這些互動。就好像他們從來沒發生過。

Workbox Google Analytics (分析) 透過服務工作處理程序偵測失敗要求的能力，為 Google Analytics (分析) 使用者解決這個問題。

Google Analytics (分析) 會透過 HTTP 要求向 Measurement Protocol 接收所有資料，這表示 Service Worker 指令碼可加入擷取處理常式，偵測傳送至 Measurement Protocol 的失敗要求。並將這些要求儲存在 IndexedDB 中，然後在連線恢復後重試。

Workbox Google Analytics (分析) 本身就是如此。此外，它還會新增擷取處理常式來快取 analytics.js 和 gtag.js 指令碼，因此也可以離線執行。最後，如果重試失敗的要求，Workbox Google Analytics (分析) 也會自動設定 (或更新) 要求酬載中的 qt，確保 Google Analytics (分析) 中的時間戳記能反映出原始使用者互動的時間。

啟用 Workbox Google Analytics (分析)

如要啟用 Workbox Google Analytics (分析)，請呼叫 initialize() 方法：

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

googleAnalytics.initialize();

想要將 Google Analytics (分析) 的失敗要求排入佇列並重試，這是唯一需要排入佇列的程式碼。這是讓 Google Analytics (分析) 離線運作最簡單的方法。

不過，如果只使用上述程式碼，就無法與第一次嘗試時成功的要求區分重試要求。這表示您將會收到離線使用者的所有互動資料，但您無法判斷使用者離線時發生了哪些互動。

如要解決這個問題，您可以使用以下所述的設定選項，修改或加上註解在重試要求中傳送的資料。

修改要傳送的資料

如果您想區分重試的要求與非重試要求，您可以指定 parameterOverrides 或 hitFilter 設定選項。

這些選項可讓您修改在重試要求中傳送的 Measurement Protocol 參數。當您想為每個重試要求的特定參數設定相同的值時，應使用 parameterOverrides 選項。如果需要在執行階段計算特定參數值或衍生自其他參數的值，則應使用 hitFilter 選項。

以下舉例說明如何使用這兩個選項。

示例

使用自訂維度追蹤線上與離線互動

Google Analytics (分析) 並未內建線上與離線互動維度。不過，您可以使用「自訂維度」功能，自行建立維度。

如要針對 Workbox Google Analytics (分析) 使用自訂維度追蹤服務工作站重播的要求，請按照下列步驟操作：

1. 在 Google Analytics (分析) 中建立新的自訂維度。輸入「Network Status」這類名稱，並將其範圍設為「hit」(因為任何互動皆可離線)。

2. 記下為新建立維度指派的索引，並將該參數做為參數名稱傳送至 Workbox Google Analytics (分析) 程式碼中的 parameterOverrides 設定選項。

   舉例來說，如果這是您的第一個自訂維度，索引是 1，參數名稱則是 cd1 (如果索引是 8，則參數為 cd8)：

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

3. (選用) 由於 parameterOverrides 中的值只會套用至重試 (「離線」) 要求，因此建議您將所有其他要求設為「online」。雖然這並非必要，但可以讓報表更容易閱讀。
   
   舉例來說，如果您使用預設的 analytics.js 追蹤程式碼片段安裝 Google Analytics (分析)，可以加入 ga('set', 'dimension1', 'online') 這一行程式碼，將「Network Status」自訂維度加入 '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 Analytics (分析) 中建立新的自訂指標。為檔案取個名稱，例如「離線佇列時間」，將其範圍設為「hit」，然後將格式類型設為「Time」(以秒為單位)。

2. 使用 hitFilter 選項取得 qt 參數的值，並將其除以 1000 (轉換為秒)。然後將該值設為使用新建立指標索引的參數。如果這是您的第一個自訂指標，參數名稱將會是 '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 (分析)

由於 Workbox Google Analytics (分析) 會使用 Background Sync 重播事件，因此測試過程可能並不直覺。詳情請參閱測試 Workbox 背景同步處理。

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