ใช้ Google Analytics

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

ข้อกำหนด

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

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

ใช้ Measurement Protocol ของ Google Analytics

ตั้งแต่ Manifest V3 เป็นต้นมา ส่วนขยาย Chrome ไม่อนุญาตให้เรียกใช้โค้ดที่โฮสต์จากระยะไกล ซึ่งหมายความว่าคุณต้องใช้ Measurement Protocol ของ Google Analytics เพื่อติดตามเหตุการณ์ของส่วนขยาย 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 ไว้ใน browser.storage.local เพื่อให้ค่าดังกล่าวคงเดิมตราบใดที่ติดตั้งส่วนขยาย

การใช้ browser.storage.local ต้องมีสิทธิ์ storage ในไฟล์ Manifest

manifest.json:

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

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

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

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

ตัวอย่างต่อไปนี้แสดงแนวทางที่จะหมดเวลาเซสชันใหม่ หลังจากไม่มีการรายงานเหตุการณ์เป็นเวลา 30 นาที (คุณปรับแต่งเวลานี้ได้ เพื่อให้เหมาะกับพฤติกรรมของผู้ใช้ส่วนขยายมากขึ้น) ตัวอย่างนี้ใช้ browser.storage.session เพื่อจัดเก็บเซสชันที่ใช้งานอยู่ขณะที่เบราว์เซอร์ ทำงาน เราจะจัดเก็บเวลาล่าสุดที่เหตุการณ์ทริกเกอร์พร้อมกับเซสชัน วิธีตรวจสอบว่าเซสชันที่ใช้งานอยู่หมดอายุแล้วหรือไม่

const SESSION_EXPIRATION_IN_MIN = 30;

async function getOrCreateSessionId() {
  // Store session in memory storage
  let {sessionData} = await browser.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 browser.storage.session.set({sessionData});
    }
  }
  if (!sessionData) {
    // Create and store a new session
    sessionData = {
      session_id: currentTimeInMs.toString(),
      timestamp: currentTimeInMs.toString(),
    };
    await browser.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 ดังนี้

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

การใช้ Measurement Protocol ของ Google 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 ซึ่งจะแสดงเหตุการณ์เมื่อได้รับ