שליחת אירועי 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 מקצה חותמת זמן של 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"
    }
  }
}

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

  • 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:

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

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