המדריך הזה מדגים איך לעקוב אחרי השימוש בתוסף באמצעות Google Analytics. אתם יכולים למצוא דוגמה פעילה ל-Google Analytics 4 ב-GitHub, שבה google-analytics.js כולל את כל הקוד שקשור ל-Google Analytics.
דרישות
במדריך הזה אנחנו מניחים שאתם מכירים את כתיבת תוספים ל-Chrome. אם אתם זקוקים להסבר על כתיבת תוסף, קראו את המדריך לתחילת העבודה.
צריך גם להגדיר חשבון Google Analytics 4 כדי לעקוב אחר התוסף. לתשומת ליבכם: כשמגדירים את החשבון, אפשר להשתמש בכל ערך שמופיע בשדה 'כתובת ה-URL של האתר', כי לתוסף לא תהיה כתובת URL משלו.
שימוש ב-Measurement Protocol של Google Analytics
מאז מניפסט V3, לתוספים ל-Chrome אין הרשאה להפעיל קוד באירוח מרוחק. כלומר, צריך להשתמש ב-Google Analytics Measurement Protocol כדי לעקוב אחר אירועים של תוספים. באמצעות Measurement Protocol אפשר לשלוח אירועים ישירות לשרתים של Google Analytics באמצעות בקשות HTTP. אחד היתרונות של גישה זו הוא שהיא מאפשרת לשלוח אירועי ניתוח מכל מקום בתוסף, כולל קובץ השירות (service worker).
הגדרת פרטי הכניסה ל-API
השלב הראשון הוא לקבל api_secret ו-measurement_id. במסמכי התיעוד בנושא Measurement Protocol מוסבר איך לקבל את הדוחות האלה לחשבון Analytics.
יצירת client_id
השלב השני הוא ליצור מזהה ייחודי למכשיר או למשתמש ספציפי, client_id. המזהה לא משתנה, כל עוד התוסף מותקן בדפדפן של המשתמש. היא יכולה להיות מחרוזת שרירותית, אבל צריכה להיות ייחודית ללקוח. אפשר ליצור חשבון על ידי התקשרות אל self.crypto.randomUUID(). אפשר לאחסן את client_id ב-chrome.storage.local כדי לוודא שהוא יישאר ללא שינוי כל עוד התוסף מותקן.
כדי להשתמש ב-chrome.storage.local נדרשת ההרשאה storage בקובץ המניפסט:
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;
}
שליחת אירוע 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 הם פרמטרים מומלצים כשמשתמשים ב-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.
מעקב אחר צפיות בדף בחלון קופץ, בחלונית צדדית ובדפי תוספים
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
השימוש ב-Measurement Protocol ב-Google Analytics מאפשר לעקוב אחר אירועים של ניתוח נתונים ב-Service Workers. לדוגמה, אם תאזינו ל-unhandledrejection event ב-Service Worker, תוכלו לתעד ב-Google Analytics חריגות לא נתפסו ב-Service Worker, מה שיכול לעזור לכם מאוד לנפות באגים בבעיות שהמשתמשים שלכם עשויים לדווח עליהן.
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 יש שתי תכונות שימושיות לניפוי באגים של אירועי ניתוח נתונים בתוסף:
- נקודת קצה מיוחדת לניפוי באגים
https://www.google-analytics.com**/debug**/mp/collectשתדווח על שגיאות בהגדרות האירועים. - הדוח 'זמן אמת ב-Google Analytics' שהאירועים יוצגו בו ברגע שהם מתקבלים.