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

במדריך הזה מוסבר איך לשלוח אירועים ממקורות של נתוני אתרים ואפליקציות באמצעות Google Analytics Measurement Protocol לשרת של 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.

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

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

  המספר measurement_id הוא לא מזהה מקור הנתונים.

צריך לספק את תוכן הבקשה בפורמט JSON POST body עבור פרוטוקול המדידה. לדוגמה:

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

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

רוצה לנסות?

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

const measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "CLIENT_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"
    }
  })
});

חותמת זמן של ביטול

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

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

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

{
  "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 עבור משתמשי אפליקציות.

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