הפניית Measurement Protocol

במסמך הזה נסביר איך לשלוח נתונים אל Google Analytics באמצעות Measurement Protocol.

סקירה כללית

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

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

במסמך הזה נסביר איך להזין את שני הפורמטים.

תחבורה

נקודת קצה של כתובת אתר

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

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

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

אפשר לשלוח נתונים באמצעות בקשות POST או GET.

שימוש ב-POST

מומלץ לשלוח נתונים דרך POST כי זה מאפשר מטען ייעודי (payload) גדול יותר. כשמשתמשים ב-POST, צריך לשלוח את בקשת ה-HTTP הבאה:

User-Agent: user_agent_string
POST https://www.google-analytics.com/collect
payload_data

כאשר:

  • user_agent_string – היא מחרוזת בפורמט של סוכן משתמש שמשמשת לחישוב המאפיינים הבאים: הדפדפן, הפלטפורמה והיכולות בנייד.

    אם הערך הזה לא מוגדר, הנתונים שצוינו לא יחושבו.

  • payload_data – ה-BODY של הבקשה לאחר ההעלאה. הגוף חייב לכלול מטען ייעודי (payload) מקודד אחד בדיוק, באורך של 8,192 בייטים.
  • כתובת IP – נשלחת במרומז בבקשת ה-HTTP ומשמשת לחישוב כל מאפייני הרשת / המיקום הגיאוגרפי ב-Google Analytics.

GET

בסביבות שבהן אי אפשר לשלוח נתוני POST, אפשר גם לשלוח בקשות HTTP GET לאותה נקודת קצה:

GET /collect?payload_data HTTP/1.1
Host: https://www.google-analytics.com
User-Agent: user_agent_string

כאשר נתוני המטען הייעודי (payload) נשלחים כפרמטרים של שאילתה עם קוד URI שמסומן בתו בריחה (escape). האורך של כל כתובת ה-URL המקודדת לא יכול להיות יותר מ-8,000 בייטים.

מעקף קובצי מטמון

בסביבות מסוימות, כמו דפדפנים, בקשות HTTP GET עשויות להישמר במטמון. כשבקשה נשמרת במטמון, יכול להיות שבקשות עתידיות יאוחזרו מהמטמון ולא יישלחו ל-Google Analytics. כדי לפרוץ את המטמון, ה-Measurement Protocol מספק פרמטר מיוחד (z) שאפשר להגדיר באמצעות מספר אקראי. כך ניתן לוודא שכל בקשות ה-Measurement Protocol הן ייחודיות, ושהבקשות הבאות לא אוחזרות מהמטמון.

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

https://www.google-analytics.com/collect?payload_data&z=123456

קודי תגובה

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

אם לא קיבלת קוד סטטוס 2xx, לא כדאי לנסות לשלוח שוב את הבקשה. במקום זאת, צריך להפסיק ולתקן את השגיאות בבקשת ה-HTTP.

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

כל הנתונים שנאספים על ידי Google Analytics באמצעות Measurement Protocol נשלחים כמטען ייעודי (payload). המטען הייעודי דומה למחרוזת שאילתה של כתובת URL, שבה לכל פרמטר יש מפתח וערך, שמופרדים בתו = וכל צמד מופרד בתו &. לדוגמה:

key1=val1&key2=val2

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

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

ערכים נדרשים לכל ההתאמות

הפרמטרים הבאים חייבים להיות בכל מטען ייעודי (payload):

שם פרמטר דוגמה התיאור
גרסת פרוטוקול v v=1 גרסת הפרוטוקול. הערך צריך להיות 1.
מזהה לצורכי מעקב tid tid=UA-123456-1 המזהה שמבדיל בין נכס Google Analytics שאליו יש לשלוח נתונים.
Client ID cid cid=xxxxx מזהה ייחודי למשתמש מסוים.
סוג התאמה t t=pageview סוג האינטראקציה שנאספת עבור משתמש מסוים.

הנתונים של Client ID ושל Hit Type הם ערכים שממופים ישירות למודל הנתונים של Google Analytics. כדי לעקוב אחרי המשתמש 5555 שנכנס אל /pageA, /pageB ו-/pageC, צריך לשלוח את 3 מטענים הנתונים הבאים:

v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC

לתשומת ליבך, / קודד ל-%2F.

ערכי קידוד של כתובות URL

כל הערכים שנשלחים ל-Google Analytics צריכים להיות גם UTF-8 וגם כתובת URL מקודדת. כדי לשלוח את המפתח dp עם הערך /my page €, עליכם קודם לוודא שהקידוד הוא UTF-8, ולאחר מכן עם קידוד כתובת ה-URL, וכתוצאה מכך תתקבל המחרוזת הסופית:

dp=%2Fmy%20page%20%E2%82%AC

אם תווים כלשהם מקודדים באופן שגוי, הם יוחלפו בתו החלופי של ה-Unicode xFFFD.

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

פרמטרים מסוימים יכולים להישלח רק עם סוגי היטים ספציפיים. לדוגמה, סוג ההתאמה pageview מחייב הגדרה גם של הפרמטר 'נתיב הדף' (dp). בהפניה לפרמטרים מתוארים הפרמטרים הנדרשים לכל סוגי ההיטים.

אורך מקסימלי

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

סוגי נתונים נתמכים

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

ב-Measurement Protocol יש תמיכה בסוגי הנתונים הבאים:

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

טקסט

משמש לייצוג מחרוזות. מתבצע עיבוד נוסף בשדות הטקסט. המערכת מסירה את כל תווי הרווחים בהתחלה והסוף. אם יש שני תווים או יותר של רווח לבן (כולל רווח, Tab, שורות חדשות וכו') מוקטנים תו רווח אחד בכל פעם שהרצות פנימיות של שני תווים או יותר. הטרנספורמציה הזו מיושמת על הטקסט הגולמי לפני הקיצוץ. לדוגמה:

   Hello      World

יהפוך ל:

Hello World

מטבע

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

1000.000001

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

$-55.00

יהפוך ל:

-55.00

בוליאני

משמש כדי לקבוע אם ערך הוא 'נכון' או 'לא נכון'. הערכים החוקיים כוללים:

  • 1 – נכון
  • 0 – לא נכון

מספר שלם

משמש לייצוג מספר שלם. הערך יאוחסן כ-int64 חתום

מספרים

משמש לייצוג מספר שלם או מספר נקודה צפה (floating-point).