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

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

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

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

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

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

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
<payload_data>

בכתובת ה-URL של הבקשה צריך לציין את הפרטים הבאים:

  • api_secret: ה-API Secret שנוצר בממשק המשתמש של Google Analytics.

    כדי ליצור סוד חדש, עוברים לקטע ניהול > מקורות נתונים > בחירת מקור הנתונים > Measurement Protocol > יצירה.

  • measurement_id: מזהה המדידה שמשויך למקור נתונים. הוא מופיע בממשק המשתמש של Google Analytics בקטע ניהול > מקורות נתונים > בחירת מקור הנתונים > מזהה מדידה.

    הערך של measurement_id הוא לא מזהה מקור הנתונים.

במאמר פרמטרים של שאילתות מפורט מידע מלא.

צריך לציין את הפרטים הבאים בגוף הבקשה:

  • client_id: מזהה ייחודי של לקוח. זה שונה מ-app_instance_id ב-Firebase. משתמשים ב-gtag.js('get').

  • ‫timestamp_micros: אופציונלי. ראשית זמן יוניקס (Unix epoch), במיקרו-שניות, של האירועים ומאפייני המשתמשים שכלולים בבקשה. אם הפרמטר הזה לא יצוין, המערכת תשתמש כברירת מחדל בחותמת הזמן של הבקשה.

  • events: מערך של פריטי אירועים. אתם יכולים לכלול כמה אירועים בבקשה אחת.

    כדי שפעילות המשתמשים תופיע בדוחות כמו פעילות בזמן אמת, צריך לספק את הפרמטרים engagement_time_msec ו-session_id כחלק מה-params של event. הפרמטר engagement_time_msec צריך לשקף את משך ההתעניינות של האירוע באלפיות השנייה.

    לדוגמה:

  {
   "client_id": "123456.7654321",
   "events": [
     {
        "name": "campaign_details",
        "params": {
          "campaign_id": "google_1234",
          "campaign": "Summer_fun",
          "source": "google",
          "medium": "cpc",
          "term": "summer+travel",
          "content": "logolink",
          "session_id": "123",
          "engagement_time_msec": 100
        }
     }
   ]
  }

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

רוצה לנסות?

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

const measurement_id = `G-XXXXXXXXXX`;
const api_secret = `<secret_value>`;

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "XXXXXXXXXX.YYYYYYYYYY",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "123",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "123",
          "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"
    }
  })
});

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

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

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

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

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

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

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

מגבלות

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

  • בקשות יכולות לכלול עד 25 אירועים.
  • מותר לכלול באירועים עד 25 פרמטרים.
  • מותר לכלול באירועים עד 25 מאפייני משתמשים.
  • שמות של מאפייני משתמשים צריכים להיות באורך של עד 24 תווים.
  • ערכים של מאפייני משתמשים צריכים להיות באורך של עד 36 תווים.
  • שמות של אירועים צריכים להיות באורך של עד 40 תווים, יכולים לכלול רק תווים אלפאנומריים ותווי קו תחתון, וחייבים להתחיל באות.
  • שמות של פרמטרים, כולל פרמטרים של פריטים, צריכים להיות באורך של עד 40 תווים, יכולים לכלול רק אותיות, מספרים ותווי קו תחתון, וחייבים להתחיל באות.
  • ערכי הפרמטרים, כולל ערכי הפרמטרים של הפריטים, צריכים להיות באורך של עד 100 תווים בנכס Google Analytics רגיל, ובאורך של עד 500 תווים בנכס Google Analytics 360.
  • פרמטרים של פריטים יכולים לכלול עד 10 פרמטרים מותאמים אישית.
  • גוף הפוסט חייב להיות קטן מ-130KB.
  • אירועים של Measurement Protocol לאפליקציות שנשלחים אל Google Analytics לא מאכלסים קהלים לרשת החיפוש ב-Google Ads של משתמשי האפליקציה.

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