ใช้ Google Analytics

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

ข้อกำหนด

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

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

ใช้ Measurement Protocol ของ Google Analytics

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

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

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

ขั้นตอนที่ 1: สร้างสตรีมข้อมูลเว็บ

เนื่องจากระบบจะติดตามส่วนขยาย Chrome เป็นสภาพแวดล้อมเว็บ คุณจึงต้องตั้งค่าสตรีมข้อมูลเว็บ ในพร็อพเพอร์ตี้ Google Analytics โดยทำดังนี้

1. ไปที่หน้าผู้ดูแลระบบของ Google Analytics
2. ในคอลัมน์พร็อพเพอร์ตี้ ให้คลิกการเก็บรวบรวมข้อมูลและการแก้ไข แล้วเลือกสตรีมข้อมูล
3. คลิกเพิ่มสตรีม แล้วคลิกเว็บ
4. ป้อน URL ตัวยึดตำแหน่งในช่องURL ของเว็บไซต์ (เช่น https://extension หรือ URL Chrome เว็บสโตร์ของส่วนขยาย)
5. ป้อนชื่อสตรีม (เช่น My Chrome Extension)
6. คลิกสร้างสตรีม

เมื่อสร้างแล้ว รหัสการวัด (ลักษณะคล้าย G-XXXXXXXXXX) จะปรากฏที่ด้านบนของหน้ารายละเอียดสตรีม

ขั้นตอนที่ 2: สร้าง API Secret สำหรับ Measurement Protocol

หากต้องการสร้าง api_secret ที่จำเป็นสำหรับ Measurement Protocol ให้ไปที่การตั้งค่าสำหรับสตรีมข้อมูลเว็บที่คุณเพิ่งสร้าง โดยทำดังนี้

1. ไปที่ผู้ดูแลระบบ > การเก็บรวบรวมข้อมูลและการแก้ไข > สตรีมข้อมูล แล้วเลือกสตรีมข้อมูลเว็บ

2. ในส่วนเหตุการณ์ ให้คลิก API Secret สำหรับ Measurement Protocol

3. อ่านและยอมรับข้อกำหนดของ Measurement Protocol หากระบบแจ้ง

4. คลิกสร้าง

5. ป้อนชื่อเล่นสำหรับข้อมูลลับ (เช่น Chrome Extension Secret) แล้วคลิกสร้าง เพื่อสร้างข้อมูลลับ

6. คัดลอกค่าข้อมูลลับ ที่สร้างขึ้น

สร้าง client_id

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

การใช้ chrome.storage.local ต้องได้รับสิทธิ์ storage ในไฟล์ Manifest

manifest.json:

{
  …
  "permissions": ["storage"],
  …
}

จากนั้นคุณจะใช้ chrome.storage.local เพื่อจัดเก็บ 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 = `${getRandomId()}.${unixTimestampSeconds}`;
    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 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 ช่วยให้ติดตามเหตุการณ์ Analytics ใน Service Worker ของส่วนขยายได้ ตัวอย่างเช่น การรับฟัง unhandledrejection event ใน Service Worker จะช่วยให้คุณบันทึก ข้อยกเว้นที่ไม่ได้จัดการใน Service Worker ลงใน Google Analytics ได้ ซึ่งจะ เป็นประโยชน์อย่างมากในการแก้ไขข้อบกพร่องของปัญหาที่ผู้ใช้อาจรายงาน

service-worker.js:

addEventListener("unhandledrejection", async (event) => {
  fetch(`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await 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 getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            message: event.reason.message,
            stack: event.reason.stack,
          },
        },
      ],
    }),
  });
});

ตอนนี้คุณจะเห็นเหตุการณ์ข้อผิดพลาดในรายงาน Google Analytics แล้ว

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

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

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