Trang này được dịch bởi Cloud Translation API.

Sử dụng Google Analytics 4

Hướng dẫn này trình bày cách theo dõi việ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 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 viết tiện ích của Chrome. Nếu bạn cần thông tin về cách viế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. 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 Measurement Protocol của Google Analytics để 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 đến thẳng máy chủ Google Analytics thông qua các yêu cầu HTTP. Phương pháp này cho phép bạn gửi các sự kiện Analytics từ mọi nơi trong tiện ích của mình, bao gồm cả trình chạy dịch vụ.

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 làm theo tài liệu về Measurement Protocol để biết cách tải các phương diệ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ể, client_id. Mã 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 tuỳ ý nhưng phải dành riêng cho ứng dụng khách. Bạn có thể tạo một mã bằng cách gọi self.crypto.randomUUID(). Lưu trữ client_id trong chrome.storage.local để đảm bảo phần này không thay đổi trong suốt thời gian cài đặt tiện ích này.

Để sử dụng chrome.storage.local, bạn phải 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 một 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 của mình 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à các thông số được đề xuất khi sử dụng Measurement Protocol của Google Analytics vì các thông số này cần thiết cho 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, trong đó một người dùng liên tục tương tác với phần mở rộng 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 của 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 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 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 nếu 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 người dùng của tiện ích). 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 hoạt động, chúng tôi 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.

Sự kiện theo thời gian thực trong 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

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 tính năng này để theo dõi những người dùng truy cập vào trang bật lên, bảng điều khiển bên hoặc trang tiện ích của bạn trong thẻ mới. Sự kiện page_view cũng yêu cầu tham số page_title và page_location. Ví dụ sau đây kích hoạt một sự kiện xem trang tại sự kiện tài liệu load cho một cửa sổ bật lên của phần mở rộng.:

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 cần nhập tập lệnh popup.js 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ẽ được hiển thị giống như mọi lượt xem trang khác trong báo cáo Theo thời gian thực của Google Analytics:

Sự kiện lượt xem trang khi sự kiện đó hiển thị trong trang tổng quan 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ụ

Khi sử dụng Measurement Protocol của Google Analytics, 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 lắng nghe unhandledrejection event trong trình chạy dịch vụ, bạn có thể ghi mọi 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 ích rất nhiều trong việc gỡ lỗi 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,
          },
        },
      ],
    }),
  }
});

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

Sự kiện lỗi hiển thị trong trang tổng quan về sự kiện Google Analytics.

Gỡ lỗi

Google Analytics cung cấp 2 tính năng hữu ích để gỡ lỗi sự kiện Analytics 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/collect sẽ 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 có sự kiện đó.