使用 Google Analytics (分析) 4

本教學課程說明如何使用 Google Analytics 追蹤擴充功能的使用情形。您可以在 GitHub 上查看實用的 Google Analytics 4 範例,其中「google-analytics.js包含所有 Google Analytics 相關程式碼。

需求條件

本教學課程假設您已熟悉如何編寫 Chrome 擴充功能,如需如何編寫擴充功能的相關資訊,請參閱入門教學課程

此外,您還必須設定 Google Analytics 4 帳戶來追蹤額外資訊。請注意,設定帳戶時,您可以使用 [網站網址] 欄位中的任何值,因為您的擴充功能沒有本身的網址。

使用 Google Analytics Measurement Protocol

自 Manifest V3 起,Chrome 擴充功能都無法執行遠端代管的程式碼。也就是說,您必須使用 Google Analytics Measurement Protocol 追蹤額外資訊事件。Measurement Protocol 可讓您透過 HTTP 要求將事件直接傳送至 Google Analytics 伺服器。這種做法的好處是,您可以從擴充功能中所有位置 (包括 Service Worker) 傳送數據分析事件,

設定 API 憑證

第一步是取得 api_secretmeasurement_id。請參閱 Measurement Protocol 說明文件,瞭解如何為 Analytics 帳戶取得這些設定。

產生 client_id

第二個步驟是為特定裝置/使用者 (client_id) 產生專屬 ID。只要使用者的瀏覽器中安裝了擴充功能,ID 應維持不變。它可以是任意字串,但對用戶端而言應該是唯一的。您可以呼叫 self.crypto.randomUUID() 來產生。將 client_id 儲存在 chrome.storage.local 中,確保在安裝擴充功能期間維持不變。

如要使用 chrome.storage.local,您必須具備資訊清單檔案中的 storage 權限:

manifest.json:

{
  
  "permissions": ["storage"],
  
}

接著,您可以使用 chrome.storage.local 儲存 client_id

async function getOrCreateClientId() {
  const result = await chrome.storage.local.get('clientId');
  let clientId = result.clientId;
  if (!clientId) {
    // Generate a unique client ID, the actual value is not relevant
    clientId = self.crypto.randomUUID();
    await chrome.storage.local.set({clientId});
  }
  return clientId;
}

傳送數據分析事件

使用 API 憑證和 client_id,您就可以透過 fetch 要求將事件傳送至 Google Analytics:

const GA_ENDPOINT = 'https://www.google-analytics.com/mp/collect';
const MEASUREMENT_ID = `G-...`;
const API_SECRET = `...`;

fetch(
  `${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: 'POST',
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: 'button_clicked',
          params: {
            id: 'my-button',
          },
        },
      ],
    }),
  }
);

這樣做會傳送 button_clicked 事件,會顯示在 Google Analytics 事件報表中。如果想在 Google Analytics 即時報表中查看事件,您必須提供額外兩個參數:session_idengagement_time_msec

使用建議的參數 session_idengagement_time_msec

session_idengagement_time_msec 都是使用 Google Analytics Measurement Protocol 時的建議參數,因為這是要在即時報表等標準報表中顯示使用者活動的必要參數。

session_id 是指使用者持續與擴充功能互動的一段時間。根據預設,工作階段會在使用者閒置 30 分鐘後結束,工作階段沒有持續時間長度限制。

Chrome 擴充功能與一般網站不同,使用者工作階段沒有明顯的概念。因此,您必須在擴充功能中定義使用者工作階段代表的意義。舉例來說,每個新的使用者互動都可能是新的工作階段。在這種情況下,您可以直接為每個事件產生新的工作階段 ID (即使用時間戳記)。

以下範例說明如何在未回報任何事件的 30 分鐘後逾時新的工作階段 (您可以自訂這個時間,以便更符合擴充功能的使用者行為)。這個範例會使用 chrome.storage.session,在瀏覽器執行期間儲存運作中的工作階段。我們儲存上次觸發事件時儲存的工作階段。如此一來,我們便能判斷目前工作階段是否已過期:

const SESSION_EXPIRATION_IN_MIN = 30;

async function getOrCreateSessionId() {
  // Store session in memory storage
  let {sessionData} = await chrome.storage.session.get('sessionData');
  // Check if session exists and is still valid
  const currentTimeInMs = Date.now();
  if (sessionData && sessionData.timestamp) {
    // Calculate how long ago the session was last updated
    const durationInMin = (currentTimeInMs - sessionData.timestamp) / 60000;
    // Check if last update lays past the session expiration threshold
    if (durationInMin > SESSION_EXPIRATION_IN_MIN) {
      // Delete old session id to start a new session
      sessionData = null;
    } else {
      // Update timestamp to keep session alive
      sessionData.timestamp = currentTimeInMs;
      await chrome.storage.session.set({sessionData});
    }
  }
  if (!sessionData) {
    // Create and store a new session
    sessionData = {
      session_id: currentTimeInMs.toString(),
      timestamp: currentTimeInMs.toString(),
    };
    await chrome.storage.session.set({sessionData});
  }
  return sessionData.session_id;
}

下例會將 session_idengagement_time_msec 新增至先前的按鈕點擊事件要求。如果是 engagement_time_msec,您可以提供預設值 100 ms

const GA_ENDPOINT = "https://www.google-analytics.com/mp/collect";
const MEASUREMENT_ID = `G-...`;
const API_SECRET = `...`;
const DEFAULT_ENGAGEMENT_TIME_IN_MSEC = 100;

fetch(
`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: "button_clicked",
          params: {
            session_id: await this.getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            id: "my-button",
          },
        },
      ],
    }),
  }
);

這個事件在 Google Analytics「即時」報表中會如下所示。

Google Analytics 中的即時事件。

追蹤彈出式視窗、側邊面板和擴充功能頁面中的網頁瀏覽次數

Google Analytics Measurement Protocol 支援追蹤網頁瀏覽的特殊 page_view 事件。可用來在新分頁、側邊面板或擴充功能頁面追蹤使用者。page_view 事件也需要 page_titlepage_location 參數。以下範例會在擴充功能彈出式視窗中,於文件 load 事件觸發網頁瀏覽事件。

popup.js:

window.addEventListener("load", async () => {
  fetch(`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: "page_view",
          params: {
            session_id: await getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            page_title: document.title,
            page_location: document.location.href
          },
        },
      ],
    }),
  });
});

popup.js 指令碼必須匯入彈出式視窗的 HTML 檔案,且應該在執行任何其他指令碼前執行:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Analytics Demo Popup</title>
    <script src="./popup.js" type="module"></script>
  </head>
  <body>
    <h1>Analytics Demo</h1>
  </body>
</html>

彈出式檢視畫面的顯示方式與 Google Analytics 即時報表中的任何其他網頁瀏覽相同:

網頁瀏覽事件顯示在 Google Analytics 即時資訊主頁中的畫面。

追蹤服務工作處理程序中的數據分析事件

只要使用 Google Analytics Measurement Protocol,就能追蹤擴充功能服務工作人員的數據分析事件。舉例來說,透過在 Service Worker 中監聽 unhandledrejection event,您可以將服務工作處理程序中所有未偵測到的例外狀況記錄到 Google Analytics,有助於解決使用者可能回報的問題。

service-worker.js:

addEventListener("unhandledrejection", async (event) => {
  `${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: getOrCreateClientId(),
      events: [
        {
          // Note: 'error' is a reserved event name and cannot be used
          // see https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference?client_type=gtag#reserved_names
          name: "extension_error",
          params: {
            session_id: await this.getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            message: error.message,
            stack: error.stack,
          },
        },
      ],
    }),
  }
});
敬上

您現在可以在 Google Analytics 報表中查看錯誤事件:

Google Analytics 事件資訊主頁中顯示的錯誤事件。

偵錯

Google Analytics 提供兩項實用功能,方便您對擴充功能偵錯數據分析事件:

  1. 特殊的偵錯端點 https://www.google-analytics.com**/debug**/mp/collect,會回報事件定義中的任何錯誤。
  2. Google Analytics 即時報表會顯示發生事件。