שליחת אירועי Measurement Protocol ל-Google Analytics

במדריך הזה מוסבר איך לשלוח אירועים ממקורות של נתוני אתרים ומקורות נתוני אפליקציות ב-Google Analytics Measurement Protocol לשרת של Google Analytics, כדי שתוכלו לראות את האירועים של Measurement Protocol בדוחות של Google Analytics.

המזהים והפרמטרים שנדרשים לבקשות Measurement Protocol תלויים בכך שאתם שולחים אירועים למקור לנתוני האתר או למקור נתוני אפליקציה.

• במקורות לנתוני האתר (בדרך כלל מוגדרים באמצעות gtag.js או Google Tag Manager), משתמשים בפרמטר measurement_id בכתובת ה-URL של הבקשה ובפרמטר client_id בגוף ה-JSON כדי לזהות את מופע המשתמש. הערך של client_id צריך להיות זהה למזהה שנוצר על ידי תג Google Analytics באתר שלכם.
• במקורות נתוני אפליקציות (שמוטמע בהם Firebase SDK), משתמשים בפרמטר firebase_app_id בכתובת ה-URL של הבקשה ובפרמטר app_instance_id בגוף ה-JSON, שמסופקים על ידי Google Analytics for Firebase SDK.

במדריך הזה אנחנו מספקים דוגמאות לשני התרחישים.

רכיבים מרכזיים של בקשות לפי סוג הסטרימינג

רכיב	מקור לנתוני האתר (gtag.js/GTM)	המקור לנתוני האפליקציה (Firebase)
פרמטר של כתובת URL של מקור נתונים	measurement_id	firebase_app_id
פרמטר של כתובת URL של API Secret	חובה	חובה
שדה גוף JSON של מזהה המכשיר	client_id	app_instance_id

בוחרים את הפלטפורמה שרוצים לראות במדריך הזה:

Firebase gtag.js

בכרטיסייה הזו מוצגות הוראות לשליחת אירועים מהשרת שקשורים לפעילות המשתמש בסטרימינג של אפליקציה באמצעות Google Analytics for Firebase SDK. חשוב לזכור שהבקשות האלה משתמשות ב-firebase_app_id וב-app_instance_id.

דרישות מוקדמות

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

API Secret

השדה api_secret משמש לאימות הבקשות שלכם. חשוב מאוד לשמור על הסודיות של הסוד הזה.

כדי ליצור סוד חדש:

1. עוברים אל Google Analytics ועוברים לחשבון ולנכס.
2. לוחצים על ניהול בפינה הימנית התחתונה.
3. בקטע איסוף נתונים ושינוי שלהם, לוחצים על מקורות הנתונים.
4. בוחרים את המקור לנתוני האתר או האפליקציה.
5. לוחצים על ערכי API Secret של Measurement Protocol.
6. לוחצים על יצירה.
7. מזינים כינוי ל-Secret ולוחצים על יצירה.

8. מעתיקים את ערך הסוד.

   חשוב: המרחב api_secret הוא פרטי. אל תחשפו אותו בקוד בצד הלקוח של האתר או האפליקציה.

   • סיכון אבטחה: חשיפת api_secret מאפשרת לצדדים לא מורשים לשלוח נתונים שרירותיים או ספאם לנכס שלכם ב-Google Analytics, מה שעלול לפגוע בדוחות.
   • שימוש נכון: ‏Measurement Protocol מיועד בעיקר לשימוש בסביבות בצד השרת או בסביבות מהימנות (כמו מערכות אופליין או תקשורת בין שרתים).
   • מעקב בצד הלקוח: אם אתם צריכים לשלוח אירועים ישירות מדפדפן אינטרנט, אתם יכולים להשתמש ב-Google Tag ‏ (gtag.js) או ב-Google Tag Manager.
   • תוספים ל-Chrome: בתוספים ל-Chrome מגרסה Manifest V3, אי אפשר לטעון קוד מרוחק כמו gtag.js. במקרה כזה, הגישה המומלצת היא Measurement Protocol. איך משתמשים ב-Google Analytics בתוספים ל-Chrome

מזהה האפליקציה ב-Firebase

הקוד firebase_app_id מזהה את אפליקציית Firebase שלכם. הוא לא זהה לapp_instance_id.

כדי למצוא את מזהה האפליקציה ב-Firebase:

1. פותחים את הפרויקט במסוף Firebase.
2. לוחצים על סמל גלגל השיניים של ההגדרות לצד Project Overview (סקירת הפרויקט) ובוחרים באפשרות Project settings (הגדרות הפרויקט).
3. בכרטיסייה כללי, עוברים לקטע האפליקציות שלך.
4. בוחרים את האפליקציה הספציפית ל-iOS או ל-Android.
5. מעתיקים את הערך של מזהה האפליקציה.

בחירת הפורמט של הבקשה

‫Google Analytics Measurement Protocol תומך רק בבקשות HTTP POST.

כדי לשלוח אירוע, צריך להשתמש בפורמט הבא:

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

הערה: אם רוצים שהנתונים ייאספו באיחוד האירופי, צריך לשנות את HOST בדוגמה ל-region1.google-analytics.com.

בפרמטרים של השאילתה בכתובת ה-URL של הבקשה צריך לציין את הפרטים הבאים (בקטע דרישות מוקדמות מוסבר איך למצוא או ליצור את הערכים האלה):

• ‫api_secret: ה-API Secret לאימות הבקשה.
• ‫firebase_app_id: מזהה האפליקציה ב-Firebase של האפליקציה שלכם.

צריך לספק גוף בקשה בפורמט JSON POST body עבור Measurement Protocol. לדוגמה:

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

כדי לזהות התקנה ייחודית של האפליקציה לנייד, צריך לספק את app_instance_id בגוף הבקשה. חשוב לשים לב שהמזהה הזה שונה מfirebase_app_id, שמזהה את האפליקציה עצמה. מידע נוסף על app_instance_id ועל האופן שבו אפשר לאחזר אותו באמצעות Firebase SDK זמין במסמכי העיון בנושא app_instance_id.

‫session_start הוא שם אירוע שמור, אבל אם תיצרו session_id חדש, המערכת תיצור סשן חדש בלי שתצטרכו לשלוח אירוע session_start. איך מתבצעת הספירה של סשנים

אני רוצה לנסות

הערה: הדוגמאות הבאות מתבססות על fetch API ומיועדות לשימוש בסביבות מהימנות או בצד השרת (לדוגמה, Node.js או שרת בק-אנד). אין להשתמש בהם בקוד בצד הלקוח (בדפדפן), כי זה יחשוף את api_secret.

דוגמה לשליחת כמה אירועים בבת אחת: בדוגמה הזו, אירוע tutorial_begin ואירוע join_group נשלחים לשרת Google Analytics, כולל מידע גיאוגרפי באמצעות השדה user_location, וכולל מידע על המכשיר באמצעות השדה device.

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    device: {
      category: "mobile",
      language: "en",
      screen_resolution: "1280x2856",
      operating_system: "Android",
      operating_system_version: "14",
      model: "Pixel 9 Pro",
      brand: "Google",
      browser: "Chrome",
      browser_version: "136.0.7103.60"
    }
  })
});

הפורמט של firebase_app_id הוא ספציפי לפלטפורמה. ראו מזהה האפליקציה תחת קובצי תצורה ואובייקטים של Firebase.

החלפת חותמת הזמן

ב-Measurement Protocol נעשה שימוש בחותמת הזמן הראשונה שמופיעה ברשימה הבאה לכל אירוע ומאפיין משתמש בבקשה:

1. ה-timestamp_micros של האירוע או מאפיין המשתמש.
2. timestamp_micros של הבקשה.
3. השעה שבה Measurement Protocol מקבל את הבקשה.

בדוגמה הבאה מוצגת שליחה של חותמת זמן ברמת הבקשה, שחלה על כל האירועים ומאפייני המשתמש בבקשה. כתוצאה מכך, Measurement Protocol מקצה חותמת זמן של requestUnixEpochTimeInMicros לאירועים tutorial_begin ו-join_group ולמאפיין המשתמש customer_tier.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

בדוגמה הבאה נשלחת חותמת זמן ברמת הבקשה, חותמת זמן ברמת האירוע וחותמת זמן ברמת מאפיין המשתמש. כתוצאה מכך, Measurement Protocol מקצה את חותמות הזמן הבאות:

• tutorialBeginUnixEpochTimeInMicros לאירוע tutorial_begin
• ‫customerTierUnixEpochTimeInMicros עבור מאפיין המשתמש customer_tier
• ‫requestUnixEpochTimeInMicros עבור האירוע join_group ומאפיין המשתמש newsletter_reader.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

התנהגות האימות לגבי אירועים ומאפייני משתמשים שהתרחשו בעבר

אפשר להגדיר תאריך מאוחר יותר לאירועים ולמאפייני משתמשים עד 72 שעות אחורה. אם הערך של timestamp_micros הוא מוקדם יותר מ-72 שעות לפני עכשיו, Measurement Protocol מקבל או דוחה את האירוע או את מאפיין המשתמש באופן הבא:

• אם הפרמטר validation_behavior לא מוגדר או מוגדר לערך RELAXED, פרוטוקול המדידה מקבל את האירוע או את מאפיין המשתמש, אבל מחליף את חותמת הזמן שלו לזמן שלפני 72 שעות.
• אם הערך של validation_behavior מוגדר כ-ENFORCE_RECOMMENDATIONS, ‏ Measurement Protocol דוחה את האירוע או את מאפיין המשתמש.

אירועים שנשלחים באמצעות Measurement Protocol ומיועדים לצירוף או לעיבוד בשילוב עם אירועים שנאספים על ידי Google Analytics for Firebase SDK או gtag.js, צריכים להתקבל על ידי Google Analytics תוך 48 שעות מהחותמת המקורית של האירוע בצד הלקוח. יכול להיות שאירועים שיתקבלו אחרי התאריך הזה לא יעברו עיבוד כמו שצריך, במיוחד למטרות כמו שיוך המרות.

מגבלות

המגבלות הבאות רלוונטיות לשליחת אירועים של Measurement Protocol אל Google Analytics:

הערה: מידע על המגבלות של תכונות 360 זמין במאמר Google Analytics 360.

• אפשר לשלוח לכל נכס עד 100 מיליון בקשות שאינן המרות בשעה. בקשה היא בקשה שאינה המרה אם אף אחד מהאירועים בבקשה הוא אירוע מרכזי שיש לו המרה ב-Google Ads. אם חורגים מהמגבלה הזו, Measurement Protocol מתעלם בשקט מכל הבקשות שאינן בקשות המרה עבור הנכס למשך שארית השעה.

  נקודה חשובה: המגבלה הזו לא חלה על נכסי Google Analytics 360.

• כל בקשה יכולה לכלול עד 25 אירועים.

• מותר לכלול באירועים עד 25 פרמטרים.

• מותר לכלול באירועים עד 25 מאפייני משתמשים.

• שמות של מאפייני משתמשים צריכים להיות באורך של עד 24 תווים.

• ערכים של מאפייני משתמשים צריכים להיות באורך של עד 36 תווים.

• שמות של אירועים צריכים להיות באורך של עד 40 תווים, יכולים לכלול רק תווים אלפאנומריים וקווים תחתונים, וחייבים להתחיל באות.

• שמות של פרמטרים, כולל פרמטרים של פריטים, צריכים להיות באורך של עד 40 תווים, יכולים לכלול רק תווים אלפאנומריים וקו תחתון, וחייבים להתחיל באות.

• ערכי פרמטרים, כולל ערכי פרמטרים של פריטים, צריכים להיות באורך של עד 100 תווים בנכס ב-Google Analytics רגיל, ובאורך של עד 500 תווים בנכס Google Analytics 360.

  המגבלה הזו לא חלה על הפרמטרים session_id ו-session_number כשהערכים שלהם מסופקים על ידי המשתנים המובנים התואמים מזהה הסשן ב-Analytics ומספר הסשן ב-Analytics ב-Google Tag Manager.

• אפשר להוסיף לפרמטרים של פריטים עד 10 פרמטרים מותאמים אישית.

• גודל הטקסט של הפוסט צריך להיות קטן מ-130KB.

• אירועים של Measurement Protocol באפליקציות שנשלחים אל Google Analytics לא מאכלסים קהלים לרשת החיפוש ב-Google Ads עבור משתמשי אפליקציות.

• יש שמות שמורים של אירועים, פרמטרים ומאפייני משתמשים שאסור להשתמש בהם. פרטים נוספים זמינים במאמר בנושא שמות שמורים.

שמות שמורים

ב-Measurement Protocol יש כמה שמות שמורים שאסור להשתמש בהם לאירועים, לפרמטרים או למאפייני משתמשים.

אלה שמות האירועים שגורמים לרוב לבלבול:

• ‫screen_view: האירוע הזה מותר רק במקורות של נתוני אפליקציות. לשידורים באינטרנט, צריך להשתמש ב-page_view במקום זאת.
• ‫ad_impression: האירוע הזה מותר רק במקורות של נתוני אפליקציות.
• ‫in_app_purchase: האירוע הזה מותר רק במקורות של נתוני אפליקציות. לזרמי נתונים מאתרים, צריך להשתמש באירוע purchase במקום זאת.

במאמר תרחישים נפוצים לדוגמה מפורטות דרישות נוספות לכל תרחיש לדוגמה.