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

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

תחבורה

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

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

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 במטען הייעודי של הבקשה.

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

מטען ייעודי

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

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

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

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

api_secret

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

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

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

גוף ה-POST של JSON

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

user_id

 string

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

timestamp_micros

 number

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

user_properties

 object אופציונלי. מאפייני המשתמש למדידה.

user_data

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

non_personalized_ads

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

user_location

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

ip_override

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

device

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

events[]

 array נדרש. מערך של פריטים מסוג event. אפשר לשלוח עד 25 אירועים בכל בקשה. במסמך העזרה events מפורטים כל האירועים התקפים.

events[].name

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

events[].params

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

המאפיין 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 מסיקה מידע גיאוגרפי מאירועי תיוג באמצעות client_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"
}

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

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

אפשר לכלול פרמטרים מותאמים אישית ברמת המשתמש, ברמת האירוע וברמת הפריט בעומס העבודה של 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
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

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

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

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