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

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

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

Firebase gtag.js

פורמט הבקשה

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 שנוצר בממשק המשתמש של Google Analytics.

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

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

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

המסמך פרמטרים של שאילתות מכיל את המידע המלא.

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

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

• ‫user_id: אופציונלי. מזהה ייחודי של משתמש. השם יכול להכיל רק תווים מסוג UTF-8. מידע נוסף על המזהה הזה זמין במאמר User-ID לניתוח נתונים מפלטפורמות שונות.

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

• ‫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.

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

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

פרוטוקול 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:

הערה: מידע על המגבלות של התכונות ב-360 זמין במאמר Google Analytics 360.

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

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