ใช้ Google Analytics 4

บทแนะนำนี้อธิบายวิธีติดตามการใช้ส่วนขยายของคุณโดยใช้ Google Analytics ดูตัวอย่าง Google Analytics 4 ที่ใช้งานได้ใน GitHub ซึ่ง google-analytics.js จะมีโค้ดที่เกี่ยวข้องกับ Google Analytics ทั้งหมด

ข้อกำหนด

บทแนะนำนี้จะถือว่าคุณคุ้นเคยกับการเขียนส่วนขยาย Chrome หากคุณต้องการข้อมูลเกี่ยวกับวิธีเขียนส่วนขยาย โปรดอ่านบทแนะนำการเริ่มต้นใช้งาน

คุณยังต้องตั้งค่าบัญชี Google Analytics 4 เพื่อติดตามส่วนขยายด้วย โปรดทราบว่าขณะตั้งค่าบัญชี คุณสามารถใช้ค่าใดก็ได้ในช่อง URL ของเว็บไซต์ เนื่องจากส่วนขยายของคุณจะไม่มี URL ของตัวเอง

การใช้ Measurement Protocol ของ Google Analytics

เนื่องจากไฟล์ Manifest V3 ส่วนขยาย Chrome จะไม่ได้รับอนุญาตให้เรียกใช้โค้ดที่โฮสต์จากระยะไกล ซึ่งหมายความว่าคุณต้องใช้ Google Analytics Measurement Protocol เพื่อติดตามเหตุการณ์ของส่วนขยาย Measurement Protocol ช่วยให้คุณส่งเหตุการณ์ไปยังเซิร์ฟเวอร์ Google Analytics ได้โดยตรงผ่านคำขอ HTTP ประโยชน์ของวิธีนี้คือช่วยให้คุณส่งเหตุการณ์ Analytics จากทุกที่ในส่วนขยายได้ รวมถึง Service Worker ด้วย

ตั้งค่าข้อมูลเข้าสู่ระบบ API

ขั้นตอนแรกคือการได้รับ api_secret และ measurement_id ทำตามเอกสาร Measurement Protocol เพื่อดูวิธีรับข้อมูลเหล่านี้สําหรับบัญชี Analytics ของคุณ

สร้าง client_id

ขั้นตอนที่ 2 คือการสร้างตัวระบุที่ไม่ซ้ำกันสำหรับอุปกรณ์/ผู้ใช้ที่เฉพาะเจาะจง ซึ่งก็คือ client_id รหัสจะยังคงเหมือนเดิมตราบใดที่ติดตั้งส่วนขยายในเบราว์เซอร์ของผู้ใช้ โดยสามารถเป็นสตริงที่กำหนดเองได้ แต่ต้องไม่ซ้ำกับไคลเอ็นต์ คุณจะสร้างบัญชีได้โดยโทรไปที่ self.crypto.randomUUID() จัดเก็บ client_id ใน chrome.storage.local เพื่อให้แน่ใจว่าจะยังคงเหมือนเดิมตราบเท่าที่ติดตั้งส่วนขยายนั้นไว้

การใช้ chrome.storage.local จะต้องใช้สิทธิ์ storage ในไฟล์ Manifest ของคุณ

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;
}

ส่งเหตุการณ์ Analytics

ด้วยข้อมูลเข้าสู่ระบบ API และ client_id คุณจะส่งเหตุการณ์ไปยัง Google Analytics ผ่านคําขอ 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',
          },
        },
      ],
    }),
  }
);

การดำเนินการนี้จะส่งเหตุการณ์ button_clicked ซึ่งจะปรากฏในรายงานเหตุการณ์ Google Analytics หากต้องการดูเหตุการณ์ในรายงานแบบเรียลไทม์ของ Google Analytics คุณจะต้องระบุพารามิเตอร์เพิ่มเติม 2 รายการ ได้แก่ session_id และ engagement_time_msec

ใช้พารามิเตอร์ที่แนะนำ session_id และ engagement_time_msec

ทั้ง session_id และ engagement_time_msec เป็นพารามิเตอร์ที่แนะนําเมื่อใช้ Measurement Protocol ของ Google Analytics เนื่องจากจําเป็นต้องใช้เพื่อให้กิจกรรมของผู้ใช้แสดงในรายงานมาตรฐาน เช่น เรียลไทม์

session_id อธิบายช่วงเวลาที่ผู้ใช้มีการโต้ตอบกับส่วนขยายอย่างต่อเนื่อง โดยค่าเริ่มต้น เซสชันหนึ่งจะสิ้นสุดลงหลังจากไม่มีกิจกรรมจากผู้ใช้เป็นเวลา 30 นาที และไม่มีการจํากัดระยะเวลาของเซสชัน

ในส่วนขยาย Chrome จะไม่มีข้อมูลที่ชัดเจนเกี่ยวกับเซสชันของผู้ใช้ ซึ่งต่างจากเว็บไซต์ทั่วไป ดังนั้น คุณต้องนิยามความหมายของเซสชันของผู้ใช้ในส่วนขยาย เช่น การโต้ตอบของผู้ใช้ใหม่ทุกครั้งอาจเป็นเซสชันใหม่ ในกรณีดังกล่าว คุณก็เพียงสร้างรหัสเซสชันใหม่ที่มีทุกเหตุการณ์ (โดยใช้การประทับเวลา)

ตัวอย่างต่อไปนี้แสดงวิธีที่จะทำให้เซสชันใหม่หมดเวลาหลังจากไม่มีการรายงานเหตุการณ์นาน 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

การติดตามการดูหน้าเว็บในหน้าป๊อปอัป แผงด้านข้าง และหน้าส่วนขยาย

Measurement Protocol ของ Google Analytics รองรับเหตุการณ์ 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

การติดตามเหตุการณ์ Analytics ใน Service Worker

การใช้ Measurement Protocol ของ Google Analytics จะช่วยให้สามารถติดตามเหตุการณ์การวิเคราะห์ใน Service Worker ส่วนขยายได้ ตัวอย่างเช่น การฟัง unhandledrejection event ใน Service Worker จะช่วยให้คุณบันทึกข้อยกเว้นที่ไม่พบใน Service Worker ไปยัง 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 มีฟีเจอร์ที่เป็นประโยชน์ 2 อย่างในการแก้ไขข้อบกพร่องของเหตุการณ์ Analytics ในส่วนขยาย ดังนี้

1. ปลายทางการแก้ไขข้อบกพร่องพิเศษ https://www.google-analytics.com**/debug**/mp/collect ที่จะรายงานข้อผิดพลาดในคำจำกัดความเหตุการณ์
2. รายงานแบบเรียลไทม์ของ Google Analytics ที่แสดงเหตุการณ์เมื่อเข้ามา