Hướng dẫn này minh hoạ cách theo dõi mức sử dụng tiện ích của bạn bằng Google Analytics. Bạn có thể tìm thấy mẫu Google Analytics đang hoạt động trên GitHub, trong đó google-analytics.js bao gồm tất cả mã liên quan đến Google Analytics.
Yêu cầu
Hướng dẫn này giả định rằng bạn đã quen với việc viết tiện ích cho Chrome. Nếu bạn cần thông tin về cách viết một tiện ích, hãy đọc hướng dẫn Bắt đầu.
Bạn cũng phải thiết lập một tài khoản Google Analytics để theo dõi tiện ích. Xin lưu ý rằng khi thiết lập tài khoản, bạn có thể sử dụng bất kỳ giá trị nào trong trường URL của trang web, vì tiện ích của bạn sẽ không có URL riêng.
Sử dụng Measurement Protocol của Google Analytics
Kể từ Manifest V3, các tiện ích của Chrome không được phép thực thi mã được lưu trữ từ xa. Điều này có nghĩa là bạn phải sử dụng Measurement Protocol của Google Analytics để theo dõi các sự kiện của tiện ích. Measurement Protocol cho phép bạn gửi sự kiện trực tiếp đến máy chủ Google Analytics bằng các yêu cầu HTTP. Lợi ích của phương pháp này là cho phép bạn gửi các sự kiện phân tích từ mọi nơi trong tiện ích, kể cả trình chạy dịch vụ.
Thiết lập thông tin đăng nhập API
Để gửi sự kiện đến Google Analytics, bạn cần có một api_secret và một measurement_id. Hãy tham khảo tài liệu về Measurement Protocol để tìm hiểu thêm về các quy cách chung của Measurement Protocol.
Bước 1: Tạo luồng dữ liệu web
Vì Tiện ích Chrome được theo dõi dưới dạng môi trường web, nên bạn phải thiết lập một Luồng dữ liệu web trong tài sản Google Analytics:
- Chuyển đến trang Quản trị của Google Analytics.
- Trong cột Tài sản, hãy nhấp vào Thu thập và sửa đổi dữ liệu, sau đó chọn Luồng dữ liệu.
- Nhấp vào Thêm luồng, rồi nhấp vào Web.
- Nhập một URL giữ chỗ bất kỳ vào trường URL trang web (ví dụ:
https://extensionhoặc URL của tiện ích trên Cửa hàng Chrome trực tuyến). - Nhập Tên luồng (ví dụ:
My Chrome Extension). - Nhấp vào Tạo luồng.
Sau khi tạo, Mã đo lường (có dạng G-XXXXXXXXXX) sẽ xuất hiện ở đầu trang Thông tin chi tiết về luồng dữ liệu.
Bước 2: Tạo mã thông báo bí mật cho API Measurement Protocol
Để tạo api_secret bắt buộc cho Measurement Protocol, hãy chuyển đến phần cài đặt cho Luồng dữ liệu web mà bạn vừa tạo:
- Chuyển đến mục Quản trị > Thu thập và sửa đổi dữ liệu > Luồng dữ liệu rồi chọn luồng dữ liệu web của bạn.
Trong mục Sự kiện, hãy nhấp vào Mã thông báo bí mật cho API Measurement Protocol.
Nếu được nhắc, hãy đọc và chấp nhận các điều khoản của Measurement Protocol.
Nhấp vào Tạo.
Nhập biệt hiệu cho mã thông báo bí mật (ví dụ:
Chrome Extension Secret) rồi nhấp vào Tạo để tạo mã thông báo bí mật.Sao chép Giá trị khoá bí mật đã tạo.
Tạo client_id
Bước thứ hai là tạo một giá trị nhận dạng riêng biệt cho một thiết bị/người dùng cụ thể, client_id. Mã nhận dạng này sẽ không thay đổi, miễn là tiện ích được cài đặt trên trình duyệt của người dùng. Đây có thể là một chuỗi bất kỳ, nhưng phải là chuỗi duy nhất đối với ứng dụng. Lưu trữ client_id trong chrome.storage.local để đảm bảo giá trị này không thay đổi miễn là tiện ích được cài đặt.
Để sử dụng chrome.storage.local, bạn cần có quyền storage trong tệp kê khai:
manifest.json:
{
…
"permissions": ["storage"],
…
}
Sau đó, bạn có thể dùng chrome.storage.local để lưu trữ 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;
}
Gửi sự kiện phân tích
Với thông tin đăng nhập API và client_id, bạn có thể gửi một sự kiện đến Google Analytics bằng cách sử dụng yêu cầu fetch:
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',
},
},
],
}),
}
);
Thao tác này sẽ gửi một sự kiện button_clicked xuất hiện trong báo cáo sự kiện của Google Analytics. Nếu muốn xem các sự kiện trong Báo cáo theo thời gian thực của Google Analytics, bạn cần cung cấp thêm 2 thông số: session_id và engagement_time_msec.
Sử dụng các tham số được đề xuất session_id và engagement_time_msec
Cả session_id và engagement_time_msec đều là các thông số được đề xuất khi sử dụng Measurement Protocol của Google Analytics vì chúng là các thông số bắt buộc để hoạt động của người dùng xuất hiện trong các báo cáo chuẩn như báo cáo Theo thời gian thực.
session_id mô tả một khoảng thời gian mà người dùng tương tác liên tục với tiện ích của bạn. Theo mặc định, một phiên sẽ kết thúc sau 30 phút người dùng không hoạt động. Không có giới hạn về thời lượng của một phiên.
Trong tiện ích của Chrome, không giống như trong các trang web thông thường, không có khái niệm rõ ràng về phiên người dùng. Do đó, bạn phải xác định ý nghĩa của một phiên người dùng trong tiện ích của mình. Ví dụ: mỗi lượt tương tác mới của người dùng có thể là một phiên mới. Trong trường hợp đó, bạn có thể tạo mã phiên mới cho mỗi sự kiện, chẳng hạn như sử dụng dấu thời gian.
Ví dụ sau đây minh hoạ một phương pháp sẽ hết thời gian chờ của một phiên mới sau 30 phút không có sự kiện nào được báo cáo (bạn có thể tuỳ chỉnh thời gian này cho phù hợp hơn với hành vi của người dùng đối với tiện ích). Ví dụ này sử dụng chrome.storage.session để lưu trữ phiên hoạt động trong khi trình duyệt đang chạy. Cùng với phiên, chúng tôi lưu trữ thời gian gần đây nhất mà một sự kiện được kích hoạt.
Bằng cách này, chúng ta có thể biết phiên hoạt động đã hết hạn hay chưa:
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;
}
Ví dụ sau đây sẽ thêm session_id và engagement_time_msec vào yêu cầu sự kiện nhấp chuột vào nút trước đó. Đối với engagement_time_msec, tốt nhất là bạn nên cung cấp thời gian đã trôi qua kể từ sự kiện gần đây nhất. Tuy nhiên, nếu không thể thực hiện được, bạn có thể cung cấp giá trị mặc định là 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",
},
},
],
}),
}
);
Sự kiện này sẽ xuất hiện như sau trong báo cáo Theo thời gian thực của Google Analytics.
Theo dõi lượt xem trang trong cửa sổ bật lên, bảng điều khiển bên và trang tiện ích
Measurement Protocol của Google Analytics hỗ trợ một sự kiện page_view đặc biệt để theo dõi lượt xem trang. Sử dụng sự kiện này để theo dõi những người dùng truy cập vào hộp thoại, trang trình đơn, bảng điều khiển bên và trang tiện ích của bạn trong một thẻ mới. Sự kiện page_view cũng yêu cầu các thông số page_title và page_location. Ví dụ sau đây kích hoạt một sự kiện lượt xem trang tại sự kiện load của tài liệu cho một trình đơn tiện ích:
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
},
},
],
}),
});
});
Bạn phải nhập tập lệnh popup.js vào tệp html của cửa sổ bật lên và tập lệnh này phải chạy trước khi bất kỳ tập lệnh nào khác được thực thi:
<!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>
Chế độ xem cửa sổ bật lên sẽ xuất hiện như mọi lượt xem trang khác trong Báo cáo theo thời gian thực của Google Analytics:
Theo dõi các sự kiện phân tích trong worker dịch vụ
Việc sử dụng Measurement Protocol của Google Analytics giúp bạn có thể theo dõi các sự kiện phân tích trong các worker dịch vụ của tiện ích. Ví dụ: bằng cách theo dõi unhandledrejection event trong trình chạy dịch vụ, bạn có thể ghi lại mọi trường hợp ngoại lệ chưa được phát hiện trong trình chạy dịch vụ vào Google Analytics. Điều này có thể giúp bạn gỡ lỗi các vấn đề mà người dùng có thể báo cáo.
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,
},
},
],
}),
});
});
Giờ đây, bạn có thể thấy sự kiện lỗi trong báo cáo Google Analytics:
Gỡ lỗi
Google Analytics cung cấp 2 tính năng hữu ích để gỡ lỗi các sự kiện phân tích trong tiện ích của bạn:
- Một điểm cuối gỡ lỗi đặc biệt
https://www.google-analytics.com**/debug**/mp/collectsẽ báo cáo mọi lỗi trong định nghĩa sự kiện của bạn. - Báo cáo theo thời gian thực của Google Analytics sẽ hiển thị các sự kiện khi chúng xuất hiện.