Sử dụng Google Analytics 4

Hướng dẫn này minh hoạ cách theo dõi mức sử dụng tiện ích bằng Google Analytics. Bạn có thể tìm thấy mẫu Google Analytics 4 đ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 của Chrome. Nếu bạn cần thông tin về cách viết một tiện ích, vui lòng đọc Hướng dẫn bắt đầu sử dụng.

Bạn cũng phải thiết lập tài khoản Google Analytics 4 để theo dõi phần mở rộng của mình. 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, 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 Google Analytics Measurement Protocol để theo dõi các sự kiện của phần mở rộng. Measurement Protocol cho phép bạn gửi sự kiện trực tiếp đến máy chủ Google Analytics thông qua 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, bao gồm cả trình chạy dịch vụ của bạn.

Chú ý: Khi sử dụng Measurement Protocol, hệ thống sẽ không bao gồm một số thông tin, chẳng hạn như vị trí địa lý.

Thiết lập thông tin đăng nhập API

Bước đầu tiên là lấy api_secret và measurement_id. Hãy tham khảo tài liệu về Measurement Protocol để biết cách nhận các thành phần này cho Tài khoản Analytics của bạn.

Tạo một client_id

Bước thứ hai là tạo giá trị nhận dạng duy nhất cho một thiết bị/người dùng cụ thể, đó là client_id. Mã nhận dạng phải giữ nguyên, miễn là tiện ích này được cài đặt trên trình duyệt của người dùng. Giá trị này có thể là một chuỗi tuỳ ý, nhưng phải là duy nhất cho máy khách. Bạn có thể tạo bản ghi bằng cách gọi self.crypto.randomUUID(). Lưu trữ client_id trong chrome.storage.local để đảm bảo tiện ích này vẫn giữ nguyên trong thời gian bạn cài đặt tiện ích này.

Để 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ể sử dụng chrome.storage.local để lưu trữ 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;
}

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 thông qua 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 sẽ xuất hiện trong báo cáo sự kiện 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ố đề xuất session_id và engagement_time_msec

Cả session_id và engagement_time_msec đều là thông số được đề xuất khi sử dụng Measurement Protocol của Google Analytics, vì các thông số này là bắt buộc để hoạt động của người dùng hiển thị 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à một người dùng liên tục tương tác với tiện ích của bạn. Theo mặc định, một phiên sẽ kết thúc nếu người dùng không hoạt động trong vòng 30 phút. Không có giới hạn về thời lượng của một phiên.

Trong các tiện ích của Chrome, không giống như 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 phiên người dùng trong tiện ích. Ví dụ: mỗi tương tác của người dùng mới có thể là một phiên mới. Trong trường hợp đó, bạn chỉ cần tạo mã phiên mới cho mỗi sự kiện (tức là sử dụng dấu thời gian).

Ví dụ sau minh hoạ một phương pháp sẽ hết thời gian chờ 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 trên tiện ích của mình). Ví dụ này sử dụng chrome.storage.session để lưu trữ phiên đang hoạt động khi trình duyệt đang chạy. Cùng với phiên, chúng ta lưu trữ lần gần đây nhất 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 đang 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 vào nút trước đó. Đối với engagement_time_msec, 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 this.getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            id: "my-button",
          },
        },
      ],
    }),
  }
);

Sự kiện này sẽ hiển thị như sau trong báo cáo Theo thời gian thực của Google Analytics.

Theo dõi số 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

Google Analytics Measurement Protocol hỗ trợ một sự kiện page_view đặc biệt để theo dõi số lượt xem trang. Dùng tính năng này để theo dõi những người dùng truy cập vào các trang bật lên, bảng điều khiển bên hoặc trang tiện ích trong thẻ mới của bạn. 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 sẽ kích hoạt sự kiện xem trang tại sự kiện load của tài liệu cho cửa sổ bật lên của 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
          },
        },
      ],
    }),
  });
});

Tập lệnh popup.js cần được nhập vào tệp html của cửa sổ bật lên và 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 bật lên sẽ hiển thị như mọi chế độ 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 trình chạy 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 trình chạy dịch vụ 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 nhật ký mọi ngoại lệ chưa được phát hiện trong trình chạy dịch vụ vào Google Analytics. Việc này có thể giúp gỡ lỗi đáng kể các sự cố mà người dùng của bạn có thể báo cáo.

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,
          },
        },
      ],
    }),
  }
});

Thận trọng: Các trường hợp ngoại lệ ghi nhật ký có thể vô tình làm rò rỉ thông tin cá nhân. Tuỳ thuộc vào tiện ích của mình, có thể bạn phải xoá mọi thông tin không nên gửi đến Google Analytics khỏi dấu vết ngăn xếp.

Giờ đây, bạn có thể xem sự kiện lỗi trong báo cáo Google Analytics:

Gỡ lỗi

Google Analytics cung cấp hai tính năng hữu ích để gỡ lỗi sự kiện phân tích vào tiện ích của bạn:

1. Điểm cuối gỡ lỗi đặc biệt https://www.google-analytics.com**/debug**/mp/collect sẽ báo cáo mọi lỗi trong định nghĩa sự kiện của bạn.
2. 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.