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

סקירה כללית

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

  1. התחבורה – איפה ואיך אתם שולחים נתונים
  2. עומס העבודה – הנתונים שאתם שולחים

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

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

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

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

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

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

api_secret

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

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

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

גוף הפוסט של JSON

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

user_id

 string

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

timestamp_micros

 number

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

user_properties

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

user_data

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

non_personalized_ads

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

events[]

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

events[].name

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

events[].params

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

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

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

ad_user_data

 string

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

הערך חייב להיות GRANTED או DENIED.

ad_personalization

 string

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

הערך חייב להיות GRANTED או DENIED.

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

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