שימוש ב-Google Analytics

במדריך הזה מוסבר איך לעקוב אחרי השימוש בתוסף באמצעות Google Analytics. דוגמה פעילה של Google Analytics זמינה ב-GitHub, שבה google-analytics.js כולל את כל הקוד שקשור ל-Google Analytics.

דרישות

ההדרכה הזו מיועדת למי שכבר יודע לכתוב תוספים ל-Chrome. אם אתם צריכים מידע על כתיבת תוסף, כדאי לקרוא את המדריך לתחילת העבודה.

כדי לעקוב אחרי התוסף, צריך גם להגדיר חשבון Google Analytics. שימו לב: כשמגדירים את החשבון, אפשר להשתמש בכל ערך בשדה'כתובת האתר', כי לתוסף אין כתובת URL משלו.

שימוש ב-Measurement Protocol של Google Analytics

מאז Manifest V3, לתוספים ל-Chrome אין הרשאה להפעיל קוד באירוח מרוחק. כלומר, אתם צריכים להשתמש ב-Measurement Protocol של Google Analytics כדי לעקוב אחרי אירועים של תוספים. ‫Measurement Protocol מאפשר לשלוח אירועים ישירות לשרתים של Google Analytics באמצעות בקשות HTTP. היתרון בגישה הזו הוא שאפשר לשלוח אירועים של ניתוח נתונים מכל מקום בתוסף, כולל מ-service worker.

הגדרת פרטי כניסה ל-API

כדי לשלוח אירועים ל-Google Analytics, צריך api_secret וmeasurement_id. כדי לקבל מידע נוסף על מפרטים כלליים של Measurement Protocol, אפשר לעיין בתיעוד של Measurement Protocol.

שלב 1: יצירת מקור לנתוני האתר

תוספי Chrome נחשבים לסביבות אינטרנט, ולכן צריך להגדיר מקור לנתוני האתר בנכס ב-Google Analytics:

1. עוברים אל דף הניהול של Google Analytics.
2. בעמודה נכס, לוחצים על איסוף נתונים ושינוי שלהם ואז בוחרים באפשרות מקורות נתונים.
3. לוחצים על הוספת מקור נתונים ואז על אתר.
4. מזינים כתובת URL של placeholder בשדה כתובת אתר (לדוגמה, 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. מזינים כינוי ל-Secret (למשל, Chrome Extension Secret) ולוחצים על יצירה כדי ליצור את ה-Secret.

6. מעתיקים את ערך הסוד שנוצר.

יצירת client_id

השלב השני הוא ליצור מזהה ייחודי למכשיר או למשתמש ספציפיים, client_id. המזהה צריך להישאר זהה כל עוד התוסף מותקן בדפדפן של המשתמש. המזהה יכול להיות מחרוזת שרירותית, אבל הוא צריך להיות ייחודי ללקוח. מאחסנים את client_id ב-chrome.storage.local כדי לוודא שהוא יישאר זהה כל עוד התוסף מותקן.

כדי להשתמש ב-chrome.storage.local, צריך להוסיף את ההרשאה storage לקובץ המניפסט:

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

שליחת אירוע ניתוח נתונים

בעזרת פרטי הכניסה ל-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, צריך לספק שני פרמטרים נוספים: 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 באופן הבא.

מעקב אחרי צפיות בדפים בחלונות קופצים, בחלונית הצדדית ובדפי תוספים

‫Google Analytics Measurement Protocol תומך באירוע מיוחד 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 workers

באמצעות Google Analytics Measurement Protocol אפשר לעקוב אחרי אירועים של ניתוח נתונים בסקריפטים של שירותים לתוספים. לדוגמה, אם מאזינים ל-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 מספקת שתי תכונות שימושיות לניפוי באגים של אירועים של Analytics בתוסף:

1. נקודת קצה מיוחדת לניפוי באגים https://www.google-analytics.com**/debug**/mp/collect שתדווח על שגיאות בהגדרות האירועים.
2. הדוח 'פעילות בזמן אמת' ב-Google Analytics שבו יוצגו האירועים כשהם יתקבלו.