חומר עזר בנושא Measurement Protocol

סקירה

יש שני חלקים לשליחת נתונים אל Google Analytics באמצעות פרוטוקול המדידה:

  1. ההעברה – המקומות והאופן שבהם שולחים נתונים
  2. המטען הייעודי (payload) – הנתונים שנשלחים.

המסמך הזה מתאר את הפורמט של ההעברה והמטען הייעודי (payload).

תחבורה

נקודת הקצה של כתובת ה-URL

כדי לשלוח נתונים באמצעות Measurement Protocol, שולחים בקשות HTTP POST לנקודת הקצה הבאה:

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

כדי לשלוח אירוע, צריך לשלוח את בקשת POST הבאה:

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

קודי תגובה

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

מטען ייעודי (payload)

הנתונים נשלחים אל Google Analytics באמצעות נתוני Measurement Protocol בשני חלקים:

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

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

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

api_secret

חובה. API Secret שנוצר באמצעות ממשק המשתמש של Google Analytics.

כדי ליצור סוד חדש, עוברים בממשק המשתמש של Google Analytics אל:
אדמין > מקורות נתונים > בחירת מקור הנתונים > Measurement Protocol > יצירה

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

firebase_app_id

 חובה. מזהה האפליקציה ב-Firebase המזהה של אפליקציית Firebase. נמצא במסוף Firebase, בקטע:
הגדרות הפרויקט > כללי > האפליקציות שלך > מזהה האפליקציה

measurement_id

 מזהה מדידה. המזהה של מקור נתונים. נמצאים בממשק המשתמש של Google Analytics בקטע:
אדמין > מקורות נתונים > בחירת מקור הנתונים > מזהה מדידה

גוף פוסט ב-JSON

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

app_instance_id

 string

חובה. מזהה באופן ייחודי התקנה ספציפית של אפליקציית Firebase. יש לאחזר את הערך הזה דרך Firebase SDK.

client_id

 string

חובה. מזהה באופן ייחודי מופע משתמש של לקוח אינטרנט. למידע נוסף, ראו שליחת אירוע אל Measurement Protocol.

user_id

 string

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

timestamp_micros

 number

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

user_properties

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

non_personalized_ads

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

events[]

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

events[].name

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

events[].params

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

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

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

ad_user_data

 string

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

חייב להיות GRANTED או DENIED.

ad_personalization

 string

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

חייב להיות GRANTED או DENIED.

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

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

  • אפשר לכלול פרמטרים מותאמים אישית ברמת המשתמש באובייקט user_properties של המטען הייעודי (payload).
  • אפשר לכלול פרמטרים מותאמים אישית ברמת האירוע באובייקט events[].params של המטען הייעודי (payload).
  • אפשר לכלול פרמטרים מותאמים אישית ברמת הפריט במערך 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_