本教學課程示範如何使用 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 (分析) 伺服器。這種做法的好處是,它能讓您從擴充功能中的任何位置 (包括服務工作人員) 傳送數據分析事件。
設定 API 憑證
第一步是取得 api_secret
和 measurement_id
。請參閱 Measurement Protocol 說明文件,瞭解如何在 Analytics (分析) 帳戶中取得這些資料。
產生 client_id
第二步是為特定裝置/使用者產生專屬 ID,也就是 client_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_id
和 engagement_time_msec
。
使用建議的參數 session_id
和 engagement_time_msec
session_id
和 engagement_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_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 this.getOrCreateSessionId(),
engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
id: "my-button",
},
},
],
}),
}
);
事件在 Google Analytics (分析) 即時報表中如下所示。
在彈出式視窗、側邊面板和擴充功能頁面中追蹤網頁瀏覽
Google Analytics (分析) Measurement Protocol 支援追蹤網頁瀏覽的特殊 page_view
事件。您可以使用這項功能,在新分頁中追蹤造訪彈出式網頁、側邊面板或擴充功能網頁的使用者。page_view
事件也需要 page_title
和 page_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 (分析) Measurement Protocol 追蹤擴充功能服務工作站中的分析事件。舉例來說,透過在服務工作處理程序中監聽 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 (分析) 提供兩項實用功能,協助您對擴充功能中的分析事件進行偵錯:
- 特殊偵錯端點
https://www.google-analytics.com**/debug**/mp/collect
,可回報事件定義中的任何錯誤。 - 畫面上將顯示事件發生的 Google Analytics (分析) 即時報表。