התיעוד הזה רלוונטי ל-Universal Analytics. אם אתם משתמשים ב-Google Analytics 4, לחצו על Measurement Protocol (Google Analytics 4).

הפניה ל-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 של בקשת הפרסום. הגוף צריך לכלול בדיוק מטען ייעודי אחד (URI) שמקודד ולא יכול לחרוג מ-8,192 בייטים.
  • כתובת IP – נשלחת באופן מפורש בבקשת ה-HTTP ומשמשת לחישוב כל המאפיינים הגיאוגרפיים/הרשתות ב-Google Analytics.

הורדה

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

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

המיקום שבו נתוני המטען הייעודי נשלחים כפרמטרים של שאילתה המסומנים ב-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 לא בוצעו שגיאות, אם ה-payload לא היה נכון, אם הנתונים במטען הייעודי (payload) היו שגויים או שלא עובדו.

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

נתוני המטען הייעודי

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

key1=val1&key2=val2

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

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

ערכי חובה לכל ההיטים

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

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 תומך בסוגי הנתונים הבאים:

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

טקסט

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

   Hello      World

יהפוך ל:

Hello World

מטבע

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

1000.000001

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

$-55.00

יהפוך ל:

-55.00

בוליאני

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

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

מספר שלם

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

מספר

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