שימוש ב-Google Analytics

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

דרישות

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

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

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

מאז Manifest V3, לתוספים ל-Chrome אין הרשאה להפעיל קוד באירוח מרוחק. כלומר, צריך להשתמש ב-Google Analytics Measurement Protocol כדי לעקוב אחרי אירועים של תוספים. ‫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 ב-browser.storage.local כדי לוודא שהוא יישאר זהה כל עוד התוסף מותקן.

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

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

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

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

‫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 אפשר לעקוב אחרי אירועים של Analytics ב-service workers של תוספים. לדוגמה, אם תקשיבו ל-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, שבו יוצגו האירועים כשהם יתקבלו.