מסמך עזר בנושא 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 של הבקשה.

‫Measurement Protocol מחזיר קוד סטטוס 2xx אם הבקשה HTTPמתקבלת. ‫Measurement Protocol לא מחזיר קוד שגיאה אם מטען הייעודי (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 אופציונלי. מגדיר את פרטי המכשיר של הבקשה בפורמט מובנה.

validation_behavior

 string

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

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

events[]

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

events[].name

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

events[].params

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

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

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

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

session_id

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

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 תפיק מידע גיאוגרפי מתיוג אירועים באמצעות 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 מחילה על הבקשה את ההגדרות של נתוני המכשירים הגרנולריים של הנכס.

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

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

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

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

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

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

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

    אם אתם רוצים לתת עדיפות לאימות קפדני על פני איסוף נתונים כשאתם שולחים בקשה מסוימת, אתם יכולים להוסיף את השדה 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
  • 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_