במדריך הזה מוסבר איך לעקוב אחרי השימוש בתוסף באמצעות Google Analytics. דוגמה פעילה של Google Analytics 4 זמינה ב-GitHub, שבה google-analytics.js כולל את כל הקוד שקשור ל-Google Analytics.
דרישות
ההדרכה הזו מיועדת למי שכבר יודע לכתוב תוספים ל-Chrome. אם אתם צריכים מידע על כתיבת תוסף, כדאי לקרוא את המדריך לתחילת העבודה.
כדי לעקוב אחרי התוסף, צריך גם להגדיר חשבון Google Analytics 4. שימו לב: כשמגדירים את החשבון, אפשר להשתמש בכל ערך בשדה 'כתובת האתר', כי לתוסף לא תהיה כתובת URL משלו.
שימוש ב-Measurement Protocol של Google Analytics
מאז Manifest V3, אסור לתוספים ל-Chrome להריץ קוד באירוח מרוחק. כלומר, אתם צריכים להשתמש ב-Measurement Protocol של Google Analytics כדי לעקוב אחרי אירועים של תוספים. Measurement Protocol מאפשר לשלוח אירועים ישירות לשרתים של Google Analytics באמצעות בקשות HTTP. היתרון בגישה הזו הוא שאפשר לשלוח אירועים של ניתוח נתונים מכל מקום בתוסף, כולל מ-service worker.
הגדרת פרטי כניסה ל-API
השלב הראשון הוא לקבל api_secret וmeasurement_id. במסמכי התיעוד של Measurement Protocol מוסבר איך מקבלים את הפרטים האלה לחשבון Analytics.
יצירת 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 = `${this.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 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:
מעקב אחר אירועים ב-Analytics ב-service workers
באמצעות Google Analytics Measurement Protocol אפשר לעקוב אחרי אירועים של ניתוח נתונים ב-service workers של תוספים. לדוגמה, אם מאזינים ל-unhandledrejection event ב-service worker, אפשר לרשום ביומן כל חריגה שלא נתפסה ב-service worker ב-Google Analytics. כך אפשר לנפות באגים בבעיות שהמשתמשים עשויים לדווח עליהן.
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 מספק שתי תכונות שימושיות לניפוי באגים של אירועים של Analytics בתוסף:
- נקודת קצה מיוחדת לניפוי באגים
https://www.google-analytics.com**/debug**/mp/collectשתדווח על שגיאות בהגדרות האירועים. - הדוח 'פעילות בזמן אמת' ב-Google Analytics שבו יוצגו האירועים כשהם יתקבלו.