使用 Google Analytics

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

需求條件

本教學課程假設您已熟悉如何編寫 Chrome 擴充功能，如需瞭解如何編寫擴充功能，請參閱入門教學課程。

您也必須設定 Google Analytics 帳戶，才能追蹤擴充功能。 請注意，設定帳戶時，您可以在網站網址欄位中使用任何值，因為擴充功能不會有自己的網址。

使用 Google Analytics Measurement Protocol

自 Manifest V3 起，Chrome 擴充功能不得執行遠端代管的程式碼。也就是說，您必須使用 Google Analytics Measurement Protocol 追蹤擴充功能事件。您可以透過 Measurement Protocol，使用 HTTP 要求將事件直接傳送至 Google Analytics 伺服器。這種做法的好處是，您可以在擴充功能的任何位置 (包括 Service Worker) 傳送 Analytics 事件。

設定 API 憑證

如要將事件傳送至 Google Analytics，您需要 api_secret 和 measurement_id。請參閱 Measurement Protocol 說明文件，進一步瞭解一般 Measurement Protocol 規格。

步驟 1：建立網站資料串流

由於 Chrome 擴充功能會以網站環境的形式追蹤，因此您必須在 Google Analytics 資源中設定網站資料串流：

  1. 前往 Google Analytics 管理頁面。
  2. 在「資源」欄中，按一下「資料收集和修改」，然後選取「資料串流」。
  3. 按一下「新增串流」，然後點選「網站」。
  4. 在「網站網址」欄位中輸入任何預留位置網址 (例如 https://extension 或擴充功能的 Chrome 線上應用程式商店網址)。
  5. 輸入「串流名稱」 (例如 My Chrome Extension)。
  6. 按一下 [建立串流]。

建立完成後，系統會在「串流詳細資料」頁面頂端顯示評估 ID (格式為 G-XXXXXXXXXX)。

步驟 2：產生 Measurement Protocol API 密鑰

如要產生 Measurement Protocol api_secret，請前往您剛建立的網站資料串流設定：

  1. 依序前往「管理」 >「資料收集和修改」 >「資料串流」，然後選取您的網站資料串流。

  2. 在「事件」部分，按一下「Measurement Protocol API 密鑰」。

  3. 如果系統顯示提示，請詳閱並接受 Measurement Protocol 條款。

  4. 按一下「建立」。

  5. 輸入密鑰的暱稱 (例如 Chrome Extension Secret)，然後按一下「建立」產生密鑰。

  6. 複製產生的密鑰值。

生成client_id

第二個步驟是為特定裝置/使用者產生專屬 ID，即 client_id。只要擴充功能安裝在使用者瀏覽器上，ID 就應維持不變。可以是任意字串，但應是用戶端專屬的字串。將 client_id 儲存在 chrome.storage.local 中，確保擴充功能安裝後，這個值不會變更。

使用 chrome.storage.local 時，需要在資訊清單檔案中加入 storage 權限：

manifest.json:

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

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

function getRandomId() {
  const digits = '123456789'.split('');
  let result = '';

  for (let i = 0; i < 10; i++) {
    result += digits[Math.floor(Math.random() * 9)];
  }

  return result;
}

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. We use
    // the <number>.<number> format since this is typical for GA client IDs.
    const unixTimestampSeconds = Math.floor(new Date().getTime() / 1000);
    clientId = `${getRandomId()}.${unixTimestampSeconds}`;
    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_id 和 engagement_time_msec。

使用建議的參數 session_id 和 engagement_time_msec

使用 Google Analytics Measurement Protocol 時，session_id 和 engagement_time_msec 都是建議使用的參數，因為使用者活動必須有這些參數，才能顯示在「即時」等標準報表中。

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_id 和 engagement_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 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_title 和 page_location 參數。以下範例會在擴充功能選單的 document 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
          },
        },
      ],
    }),
  });
});

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

<!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 即時資訊主頁中顯示的網頁瀏覽事件。

在 Service Worker 中追蹤 Analytics 事件

使用 Google Analytics Measurement Protocol，即可在擴充功能服務工作人員中追蹤 Analytics 事件。舉例來說，您可以監聽 Service Worker 中的 unhandledrejection event，將 Service Worker 中任何未處理的例外狀況記錄到 Google Analytics，這有助於偵錯使用者回報的問題。

service-worker.js：

addEventListener("unhandledrejection", async (event) => {
  fetch(`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await 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 getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            message: event.reason.message,
            stack: event.reason.stack,
          },
        },
      ],
    }),
  });
});

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

錯誤事件，如 Google Analytics 事件資訊主頁所示。

偵錯

Google Analytics 提供兩項實用功能，可偵錯擴充功能中的 Analytics 事件：

  1. 專用偵錯端點 https://www.google-analytics.com**/debug**/mp/collect，可回報事件定義中的任何錯誤。
  2. Google Analytics 即時報表會顯示傳入的事件。