מסמך עזר בנושא 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 או חותמות זמן של אירועים. אפשר להזין תאריך מאוחר יותר לאירועים עד 72 שעות אחרי שהם קרו.

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

בנוסף, האירועים ad_impression ו-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_