Workbox-google-analytics

如果您要建構可離線運作的應用程式，那麼瞭解使用者在沒有連線時如何與應用程式互動，對於改善使用體驗至關重要。

Google Analytics 等數據分析供應商需要網路連線才能將資料傳送至伺服器，也就是說，如果無法連線，這些要求就會失敗，而這些互動也會從數據分析報表中消失。就好像沒發生過

Workbox Google Analytics 為 Google Analytics 使用者 利用 Service Worker 偵測失敗的要求。

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 不提供線上與離線維度 互動情形不過，您可以自行建立維度 這項功能的用途是 自訂維度，

追蹤 Service Worker 使用 使用 Workbox Google Analytics 維度，請按照下列步驟進行：

1. 建立新的自訂維度 使用 Google Analytics 進行分析為其命名 (例如「Network Status」)，並將範圍設為「hit」 (因為任何互動都可以離線)。

2. 請記下為新建維度指派的索引，然後傳送 做為 parameterOverrides 設定選項的參數名稱 。

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

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

3. (選用) 由於 parameterOverrides 中的值只會套用至重試 (「離線」) 要求，因此您可能也想為所有其他要求設定「線上」的預設值。雖然這並非強制性規定 讓報表更容易閱讀
   
   舉例來說，如果您使用預設的 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 進行分析為廣告活動命名，例如「離線佇列時間」，設定其名稱 範圍設為「命中」， ，將格式設定類型設為「時間」(以秒為單位)。

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 會使用背景同步功能重播事件，因此測試時可能不夠直覺。詳情請見 測試 Workbox 背景同步處理。

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