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 cho 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.

Bạn cũng phải thiết lập một tài khoản Google Analytics 4 để 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 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 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, kể 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 tham khảo tài liệu về Measurement Protocol để biết cách lấy các thông tin này cho Tài khoản Analytics của bạn.

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à duy nhất đối với khách hà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 = `${this.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 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ự kiện này sẽ 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à những 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 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 chỉ cần tạo một 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 đâ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 của bạn). 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 liệu phiên hoạt động có hết hạn hay không:

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ẽ xuất hiện 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 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

Nền tảng 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 các trang bật lên, bảng điều khiển bên hoặc trang tiện ích 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 xem trang tại sự kiện load của tài liệu cho một 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
          },
        },
      ],
    }),
  });
});

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à 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:

Sự kiện lượt xem trang xuất hiện 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 service worker

Việc sử dụng Measurement Protocol của Google Analytics giúp bạn 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 worker 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 worker dịch vụ vào Google Analytics. Điều này có thể giúp ích rất nhiều cho việc gỡ lỗi mà người dùng 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ể thấy sự kiện lỗi trong báo cáo Google Analytics:

Sự kiện lỗi xuất hiện trên trang tổng quan sự kiện của 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/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 chúng xuất hiện.