שליחת אירועי 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	חובה	חובה
שדה גוף 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, 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.

• בכל בקשה יכולים להיות עד 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 במקום זאת.

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