שליחת אירועי 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.

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

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

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

לעיון המלא, ראו פרמטרים של שאילתה.

עליכם לכלול את הפרטים הבאים בגוף הבקשה:

  • client_id: מזהה ייחודי של לקוח. כתובת האימייל הזו שונה מ Firebase app_instance_id. משתמשים ב-gtag.js('get').
  • user_id: אופציונלי. מזהה ייחודי של המשתמש. יכול להכיל רק UTF-8 תווים. מידע נוסף זמין במאמר User-ID לניתוח נתונים בפלטפורמות שונות על המזהה הזה.

  • consent: אופציונלי. איך להגדיר הסכמה הגדרות.

  • timestamp_micros: אופציונלי. זמן Epoch של Unix, במיקרו-שניות, אירועים ומאפייני משתמש בבקשה. אם לא צוין, ברירת המחדל היא מועד הבקשה.

  • 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 אל Google שרת Analytics:

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: {},
    }]
  })
});

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

ה-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 ניתוח נתונים:

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

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