שליחת אירועי 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 ובוחרים באפשרות הגדרות הפרויקט.
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.

צריך לספק גוף בקשה בפורמט גוף POST של JSON עבור 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. איך מתבצעת הספירה של סשנים

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

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

שינוי חותמת הזמן

‫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, האירוע או מאפיין המשתמש יתקבלו ב-Measurement Protocol, אבל חותמת הזמן שלהם תוחלף ל-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 .

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