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

• ‫firebase_app_id: מזהה האפליקציה ב-Firebase, שמופיע במסוף Firebase בקטע Project Settings (הגדרות הפרויקט) > General (כללי) > Your Apps (האפליקציות שלך) > App ID (מזהה האפליקציה).

  הערך של firebase_app_id לא זהה לערך של app_instance_id. ‫firebase_app_id מזהה את האפליקציה, ואילו app_instance_id מזהה התקנה יחידה של האפליקציה.

צריך לספק גוף בקשה בפורמט JSON POST body עבור Measurement Protocol. לדוגמה:

  {
   "app_instance_id": "APP_INSTANCE_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 firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_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"
    }
  })
});

הפורמט של firebase_app_id הוא ספציפי לפלטפורמה. אפשר לעיין בקטע מזהה האפליקציה במאמר בנושא קובצי תצורה ואובייקטים של Firebase.

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

ב-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"
    }
  }
}

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

• 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, Measurement Protocol מקבל את האירוע או את מאפיין המשתמש, אבל מחליף את חותמת הזמן שלו לזמן של לפני 72 שעות.
• אם הערך של validation_behavior מוגדר כ-ENFORCE_RECOMMENDATIONS, ‏ Measurement Protocol דוחה את האירוע או את מאפיין המשתמש.

אירועים שנשלחים באמצעות Measurement Protocol ומיועדים לצירוף או לעיבוד בשילוב עם אירועים שנאספים על ידי Google Analytics for Firebase SDK או gtag.js, צריכים להתקבל על ידי Google Analytics תוך 48 שעות מהחותמת המקורית של האירוע בצד הלקוח. יכול להיות שאירועים שיתקבלו אחרי התקופה הזו לא יעברו עיבוד כמו שצריך, במיוחד למטרות כמו שיוך המרות.

מגבלות

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

• בכל בקשה יכולים להיות עד 25 אירועים.
• מותר לכלול באירועים עד 25 פרמטרים.
• מותר לכלול באירועים עד 25 מאפייני משתמשים.
• שמות של מאפייני משתמשים צריכים להיות באורך של עד 24 תווים.
• ערכים של מאפייני משתמשים צריכים להיות באורך של עד 36 תווים.
• שמות של אירועים צריכים להיות באורך של עד 40 תווים, יכולים לכלול רק תווים אלפאנומריים וקווים תחתונים, וחייבים להתחיל באות.
• שמות של פרמטרים, כולל פרמטרים של פריטים, צריכים להיות באורך של עד 40 תווים, יכולים לכלול רק אותיות, מספרים ותווי קו תחתון, וחייבים להתחיל באות.

• ערכים של פרמטרים, כולל ערכים של פרמטרים של פריטים, צריכים להיות באורך של עד 100 תווים בנכס ב-Google Analytics, ובאורך של עד 500 תווים בנכס Google Analytics 360.

  המגבלה הזו לא חלה על הפרמטרים session_id ו-session_number כשהערכים שלהם מסופקים על ידי המשתנים המובנים התואמים מזהה הסשן ב-Analytics ומספר הסשן ב-Analytics ב-Google Tag Manager.

• אפשר להוסיף עד 10 פרמטרים מותאמים אישית לפרמטרים של פריטים.

• גודל הטקסט של הפוסט חייב להיות קטן מ-130KB.

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

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