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

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

סקירה

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

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

במסמך הזה נסביר איך לעצב את שניהם.

תחבורה

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

שליחת הנתונים באמצעות 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) אחד בדיוק עם קידוד URI אחד, ובגודל של עד 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

כאשר נתוני המטען הייעודיים נשלחים כפרמטרים של שאילתה ב-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

קודי תגובה

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

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

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

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

key1=val1&key2=val2

לכל מטען ייעודי (payload) יש כללים שחלים: ערכים נדרשים, קידוד 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 מטענים ייעודיים (payloads) הבאים:

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

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

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

טקסט

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

   Hello      World

יהפוך ל:

Hello World

מטבע

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

1000.000001

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

$-55.00

יהפוך ל:

-55.00

ערך בוליאני

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

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

מספר שלם

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

מספרים

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