ใช้ 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 ประโยชน์ของวิธีนี้คือช่วยให้คุณส่งเหตุการณ์การวิเคราะห์ได้จากทุกที่ในส่วนขยาย รวมถึงโปรแกรมทำงานของบริการด้วย

ข้อควรระวัง: การใช้ Measurement Protocol จะทำให้ระบบไม่รวมข้อมูลบางอย่าง เช่น ตำแหน่งทางภูมิศาสตร์

ตั้งค่าข้อมูลเข้าสู่ระบบ 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;
}

ส่งเหตุการณ์การวิเคราะห์

ด้วยข้อมูลเข้าสู่ระบบ 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 เป็นพารามิเตอร์ที่แนะนำเมื่อใช้ Google Analytics Measurement Protocol เนื่องจากกิจกรรมของผู้ใช้จะต้องแสดงในรายงานมาตรฐาน เช่น เรียลไทม์

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

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

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

การแก้ไขข้อบกพร่อง

Google Analytics มีฟีเจอร์ที่เป็นประโยชน์ 2 อย่างในการแก้ไขข้อบกพร่องของเหตุการณ์ในการวิเคราะห์ส่วนขยาย

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