מסמך עזר בנושא Measurement Protocol

בדף הזה מתואר מנגנון ההעברה ופרמטרים של נתונים ב-Measurement Protocol.

תחבורה ציבורית

כל הנתונים צריכים להישלח בצורה מאובטחת באמצעות בקשות HTTPS POST.

שליחת בקשות לנקודת הקצה הבאה:

https://www.google-analytics.com/mp/collect

אם רוצים שהנתונים ייאספו באיחוד האירופי, צריך להשתמש בנקודת הקצה הבאה במקום זאת:

https://region1.google-analytics.com/mp/collect

הנה דוגמה לבקשת POST:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA

מחליפים את PAYLOAD_DATA ב-Payload של הבקשה.

אם הHTTP בקשה מתקבלת, Measurement Protocol מחזיר קוד סטטוס 2xx. ‫Measurement Protocol לא מחזיר קוד שגיאה אם מטען הייעודי (payload) מוגדר בצורה שגויה, או אם הנתונים שגויים או לא מעובדים על ידי Google Analytics.

מטען ייעודי

המטען הייעודי מחולק לשני חלקים:

  1. פרמטרים של שאילתה.
  2. גוף POST JSON.

פרמטרים של שאילתה

שם פרמטר תיאור

api_secret

 נדרש. ‫API Secret מממשק המשתמש של Google Analytics.

אפשר למצוא אותו בקטע ניהול > מקורות נתונים > בחירת מקור הנתונים > Measurement Protocol > יצירה.

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

firebase_app_id

 נדרש. מזהה האפליקציה ב-Firebase. המזהה של אפליקציה ב-Firebase.

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

תוכן בקשת POST בפורמט JSON

גודל גוף ה-POST של ה-JSON צריך להיות קטן מ-130KB.

מפתח סוג תיאור

app_instance_id

 string נדרש. מזהה ייחודי של התקנה ספציפית של אפליקציית Firebase.

הוא לא זהה ל-client_id.

חובה לאחזר את המזהה באמצעות Firebase SDK:

user_id

 string

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

timestamp_micros

 number

אופציונלי. חותמת זמן של מערכת Unix במיקרו-שניות, ולא באלפיות השנייה. מייצג את השעה של האירוע. צריך להגדיר את הערך הזה רק כדי לתעד אירועים שהתרחשו בעבר. אפשר לשנות את הגדרות ברירת המחדל באמצעות user_property או חותמות זמן של אירועים. אפשר להוסיף אירועים רטרואקטיבית עד 72 שעות אחורה.

user_properties

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

user_data

 object אופציונלי. פרטים שהמשתמשים סיפקו.
object אופציונלי. הגדרות ההסכמה של הבקשה. מידע נוסף זמין בקטע בנושא הסכמה.

non_personalized_ads

 boolean אופציונלי. הערך true מציין שאסור להשתמש בנתונים של המשתמש לצורך הצגת מודעות בהתאמה אישית.

user_location

 object אופציונלי. מגדיר את המידע הגיאוגרפי של הבקשה בפורמט מובנה.

ip_override

 string אופציונלי. כתובת ה-IP שמשמשת את Google Analytics כדי להפיק מידע גיאוגרפי לגבי הבקשה.

device

 object אופציונלי. מגדיר את פרטי המכשיר של הבקשה בפורמט מובנה.

validation_behavior

 string

אופציונלי. הגדרת התנהגות האימות של הבקשה.

‫RELAXED או ENFORCE_RECOMMENDATIONS. אם לא מציינים ערך, ברירת המחדל היא RELAXED.

events[]

 array נדרש. מערך של event פריטים. אפשר לשלוח עד 25 אירועים לכל בקשה. במאמר בנושא אירועים יש מידע על אירועים מומלצים.

events[].name

 string נדרש. שם האירוע. שמות של אירועים יכולים לכלול עד 40 תווים. במאמר אירועים מפורטים אירועים מומלצים.

events[].params

 object אופציונלי. פרמטרים של האירוע. אפשר לשלוח עד 25 פרמטרים לכל אירוע. במאמר אירועים מפורטים הפרמטרים המומלצים לכל אירוע, ובמאמר פרמטרים משותפים של אירועים מפורטים הפרמטרים המשותפים.

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

פרמטרים נפוצים של אירועים

ל-Measurement Protocol יש את הפרמטרים הנפוצים הבאים של אירועים:

מפתח סוג תיאור

session_id

 number מספר חיובי שמזהה את הסשן של המשתמש. נדרש לכמה תרחישים נפוצים לדוגמה. חייב להתאים לביטוי הרגולרי ^\d+$.

חובה לאחזר את המזהה באמצעות Firebase SDK:

engagement_time_msec

 number משך התעניינות המשתמשים באירוע, באלפיות השנייה. משתמשים בערך שמשקף את משך ההתעניינות של המשתמש מאז האירוע הקודם.

timestamp_micros

 number ראשית זמן יוניקס (Unix epoch), במיקרו-שניות, של האירוע. משתמשים בפרמטר הזה כדי לשנות את חותמת הזמן של האירוע.

המאפיין consent מגדיר את סוגי ההסכמה ואת הסטטוסים שלה. אם לא מציינים את consent, מערכת Google Analytics משתמשת בהגדרות ההסכמה מאינטראקציות מקוונות תואמות עבור הלקוח או מופע האפליקציה.

מפתח סוג תיאור

ad_user_data

 string

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

‫GRANTED או DENIED.

ad_personalization

 string

אופציונלי. הסכמה לפרסום מותאם אישית עבור המשתמש.

‫GRANTED או DENIED.

מידע גיאוגרפי

המאפיינים user_location ו-ip_override מספקים מידע גיאוגרפי. המדיניות user_location מקבלת עדיפות על פני ip_override.

זה המבנה של השדה user_location. מומלץ לספק כמה שיותר מאפיינים. מומלץ להוסיף לפחות country_id וגם region_id.

מפתח סוג תיאור

city

 string אופציונלי. שם העיר. אם העיר נמצאת בארה"ב, צריך להגדיר גם את country_id ואת region_id כדי שמערכת Google Analytics תוכל למפות את שם העיר למזהה עיר בצורה נכונה.

region_id

 string אופציונלי. המדינה וחלוקת המשנה לפי ISO 3166. לדוגמה, US-CA, US-AR, CA-BC, GB-LND, CN-HK.

country_id

 string אופציונלי. המדינה בפורמט ISO 3166-1 alpha-2. לדוגמה, US, AU, ES, FR.

subcontinent_id

 string אופציונלי. תת-היבשת בפורמט UN M49. לדוגמה, 011, 021, 030, 039.

continent_id

 string אופציונלי. היבשת בפורמט UN M49. לדוגמה, 002, 019, 142, 150.

דוגמה ל-user_location:

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

‫ip_override היא חלופה ל-user_location. אם שולחים במקום זאת את ip_override, מערכת Google Analytics מסיקה מידע גיאוגרפי מכתובת ה-IP. אם שולחים את user_location, מערכת Google Analytics מתעלמת מ-ip_override.

אם לא תשלחו את user_location או ip_override, מערכת Google Analytics תפיק מידע גיאוגרפי מתיוג אירועים באמצעות app_instance_id.

מערכת Google Analytics מחילה על הבקשה את ההגדרות של נתוני מיקום ברמת דיוק גבוהה של הנכס, בלי קשר למידע הגיאוגרפי שנשלח.

פרטי המכשיר

כדי לשלוח את פרטי המכשיר, משתמשים בשדה device. זהו המבנה של השדה device. כדאי לספק כמה שיותר מאפיינים. מומלץ להשתמש ב-category לפחות.

מפתח סוג תיאור

category

 string אופציונלי. הקטגוריה של המכשיר. לדוגמה, desktop, tablet, mobile, smart TV.

language

 string אופציונלי. השפה בפורמט ISO 639-1. לדוגמה, en, en-US.

screen_resolution

 string אופציונלי. הרזולוציה של המכשיר, בפורמט WIDTHxHEIGHT. לדוגמה, 1280x2856, 1080x2340.

operating_system

 string אופציונלי. מערכת ההפעלה או הפלטפורמה. לדוגמה, MacOS.

operating_system_version

 string אופציונלי. הגרסה של מערכת ההפעלה או הפלטפורמה. לדוגמה, 13.5.

model

 string אופציונלי. הדגם של המכשיר. לדוגמה, Pixel 9 Pro, Samsung Galaxy S24.

brand

 string אופציונלי. המותג של המכשיר. לדוגמה, Google, Samsung.

browser

 string אופציונלי. המותג או סוג הדפדפן. לדוגמה, Chrome, Firefox.

browser_version

 string אופציונלי. גרסת הדפדפן. לדוגמה, 136.0.7103.60, 5.0.

בקטע הקוד הבא מוצגות הגדרות לדוגמה של device:

"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"
}
אם בקשה לא מציינת את device, מערכת Google Analytics מסיקה את פרטי המכשיר מאירועי תיוג באמצעות app_instance_id.

לא משנה אם מציינים את device, מערכת Google Analytics מחילה על הבקשה את ההגדרות של נתוני המכשיר הגרנולריים של הנכס.

התנהגות האימות

המאפיין validation_behavior קובע איך Measurement Protocol מאמת את התוכן של הבקשה.

  • במהלך האימות של RELAXED נדחות רק בקשות לא תקינות. יכול להיות שהמערכת עדיין תקבל אירועים ופרמטרים עם שמות שדות לא תקינים או עם נתונים שלא תואמים לסוג הנכון, אבל היא תתעלם מפרמטרים שחורגים ממגבלות. כברירת מחדל, ב-Measurement Protocol נעשה שימוש באימות RELAXED.
  • ENFORCE_RECOMMENDATIONS תהליך האימות דוחה פרמטרים של אירועים ופריטים שהסוג שלהם לא נכון או שמכילים פרמטרים שחורגים מהמגבלות. בנוסף, מערכת ENFORCE_RECOMMENDATIONS דוחה כל אירוע או מאפיין משתמש עם חותמת זמן שלא חלה ב-72 השעות האחרונות.

אנחנו ממליצים על הגישה הבאה:

  • מומלץ להשתמש ב-ENFORCE_RECOMMENDATIONS כשמאמתים אירועים כדי לקבל כמה שיותר משוב על בעיות פוטנציאליות בבקשות.

    אפשר גם לאמת בקשות באמצעות הכלי ליצירת אירועים, כי הוא מציין את ENFORCE_RECOMMENDATIONS כשמאמתים בקשות.

  • כדי למזער את כמות הנתונים שנדחים על ידי Measurement Protocol, אל תציינו את validation_behavior כששולחים אירועים.

    אם אתם רוצים לתת עדיפות לאימות קפדני על פני איסוף נתונים כשאתם שולחים בקשה מסוימת, אתם יכולים להוסיף את השדה validation_behavior ולהגדיר אותו לערך ENFORCE_RECOMMENDATIONS.

פרמטרים מותאמים אישית

אתם יכולים לכלול במטען ייעודי (payload) של Measurement Protocol פרמטרים מותאמים אישית ברמת המשתמש, ברמת האירוע וברמת הפריט.

  • אפשר לכלול פרמטרים מותאמים אישית ברמת המשתמש ב-user_properties.
  • אפשר לכלול פרמטרים מותאמים אישית ברמת האירוע ב-events[].params.
  • אפשר לכלול פרמטרים מותאמים אישית ברמת הפריט ב-items.

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

שמות שמורים

חלק מהשמות של אירועים, פרמטרים ומאפייני משתמשים שמורים ואי אפשר להשתמש בהם:

שמות שמורים של אירועים

שמות האירועים הבאים שמורים ואי אפשר להשתמש בהם:

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

בנוסף, האירועים ad_impression, in_app_purchase ו-screen_view מותרים רק בסטרימינג של אפליקציה.

שמות פרמטרים שמורים

שמות הפרמטרים הבאים שמורים ואי אפשר להשתמש בהם:

  • firebase_conversion

שמות הפרמטרים לא יכולים להתחיל ב:

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

שמות שמורים של מאפייני משתמשים

השמות של מאפייני המשתמשים הבאים הם שמורים ואי אפשר להשתמש בהם:

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

בנוסף, שמות של מאפייני משתמשים לא יכולים להתחיל ב:

  • _ (underscore)
  • firebase_
  • ga_
  • google_