במדריך הזה מוסבר איך לשלוח אירועים של מקורות נתונים של אתרים ואפליקציות ב-Measurement Protocol של Google Analytics לשרת של Google Analytics, כדי שתוכלו לראות את האירועים של Measurement Protocol בדוחות של Google Analytics.
בוחרים את הפלטפורמה שרוצים לראות במדריך הזה:
פורמט הבקשה
Google Analytics Measurement Protocol תומך רק בבקשות HTTP POST
.
כדי לשלוח אירוע, צריך להשתמש בפורמט הבא:
POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
<payload_data >
בכתובת ה-URL של הבקשה צריך לציין את הפרטים הבאים:
api_secret
: סוד ה-API שנוצר בממשק המשתמש של Google Analytics.כדי ליצור סוד חדש, עוברים לקטע ניהול > מקורות נתונים > בחירת מקור הנתונים > Measurement Protocol > יצירה.
firebase_app_id
: מזהה האפליקציה ב-Firebase. המזהה מופיע במסוף Firebase בקטע Project Settings (הגדרות הפרויקט) > General (כללי) > Your Apps (האפליקציות שלך) > App ID (מזהה האפליקציה).הערך של
firebase_app_id
שונה מהערך שלapp_instance_id
. הערךfirebase_app_id
מזהה את האפליקציה, ואילו הערךapp_instance_id
מזהה התקנה יחידה של האפליקציה.
המסמך פרמטרים של שאילתות מכיל את המידע המלא.
צריך לספק את הפרטים הבאים בגוף הבקשה:
app_instance_id
: מזהה ייחודי למכונה של אפליקציית Firebase. זה שונה מ-client_id
באינטרנט:
user_id
: אופציונלי. מזהה ייחודי של משתמש. השם יכול להכיל רק תווים מסוג UTF-8. מידע נוסף על המזהה הזה זמין במאמר User-ID לניתוח נתונים מפלטפורמות שונות.
consent
: אופציונלי. כך מגדירים את הגדרות ההסכמה
timestamp_micros
: אופציונלי. הזמן של ראשית זמן יוניקס (Unix epoch), במיקרו-שניות, של האירועים ומאפייני המשתמש בבקשה. אם לא צוין, הערך שמוגדר כברירת מחדל הוא השעה של הבקשה.events
: מערך של פריטים של אירועים. אפשר לכלול כמה אירועים בבקשה אחת.כדי שפעילות המשתמשים תוצג בדוחות כמו פעילות בזמן אמת, צריך לספק את הערכים
engagement_time_msec
ו-session_id
כחלק מה-params
שלevent
. הפרמטרengagement_time_msec
צריך לשקף את זמן ההתעניינות באירוע באלפיות השנייה.לדוגמה:
{
"app_instance_id": "12345678901234567890123456789012",
"events": [
{
"name": "campaign_details",
"params": {
"campaign_id": "google_1234",
"campaign": "Summer_fun",
"source": "google",
"medium": "cpc",
"term": "summer+travel",
"content": "logolink",
"session_id": "123",
"engagement_time_msec": 100
}
}
]
}
הערך session_start
הוא שם אירוע ששמור, אבל יצירת session_id
חדש יוצרת סשן חדש בלי צורך לשלוח את הערך session_start
. איך המערכת סופרת סשנים
רוצה לנסות?
הנה דוגמה שאפשר להשתמש בה כדי לשלוח כמה אירועים בבת אחת. בדוגמה הזו, המערכת שולחת אירוע tutorial_begin
ואירוע join_group
לשרת של Google Analytics.
const firebase_app_id = `1:1234567890:android:321abc456def7890`;
const api_secret = `<secret_value>`;
fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebase_app_id}&api_secret=${api_secret}`, {
method: "POST",
body: JSON.stringify({
app_instance_id: 'app_instance_id',
events: [
{
name: "tutorial_begin",
params: {
"session_id": "123",
"engagement_time_msec": 100
}
},
{
name: "join_group",
params: {
"group_id": "G_12345",
"session_id": "123",
"engagement_time_msec": 150
}
}
]
})
});
הפורמט של firebase_app_id
ספציפי לפלטפורמה. מידע נוסף זמין בקטע מזהה אפליקציה בקטע קבצים ואובייקטים של תצורה ב-Firebase.
שינוי חותמת הזמן
פרוטוקול Measurement משתמש בחותמת הזמן הראשונה שהוא מוצא ברשימה הבאה לכל אירוע בבקשה:
- ה-
timestamp_micros
של האירוע. - ה-
timestamp_micros
של הבקשה. - המועד שבו הבקשה מתקבלת ב-Measurement Protocol.
בדוגמה הבאה נשלחת חותמת זמן ברמת הבקשה שחלה על כל האירועים בבקשה. כתוצאה מכך, חותמת הזמן requestUnixEpochTimeInMicros
מוקצית גם לאירוע tutorial_begin
וגם לאירוע join_group
.
{
"timestamp_micros": requestUnixEpochTimeInMicros,
"events": [
{
"name": "tutorial_begin"
},
{
"name": "join_group",
"params": {
"group_id": "G_12345",
}
}
]
}
בדוגמה הבאה נשלחות גם חותמת זמן ברמת הבקשה וגם חותמת זמן ברמת האירוע. כתוצאה מכך, מערכת Measurement Protocol מקצה לאירוע tutorial_begin
חותמת זמן של tutorialBeginUnixEpochTimeInMicros
ולאירוע join_group
חותמת זמן של requestUnixEpochTimeInMicros
.
{
"timestamp_micros": requestUnixEpochTimeInMicros,
"events": [
{
"name": "tutorial_begin",
"timestamp_micros": tutorialBeginUnixEpochTimeInMicros
},
{
"name": "join_group",
"params": {
"group_id": "G_12345",
}
}
]
}
מגבלות
המגבלות הבאות חלות על שליחת אירועי Measurement Protocol אל Google Analytics:
- בקשות יכולות לכלול עד 25 אירועים.
- מותר לכלול באירועים עד 25 פרמטרים.
- מותר לכלול באירועים עד 25 מאפייני משתמשים.
- שמות של מאפייני משתמשים צריכים להיות באורך של עד 24 תווים.
- ערכים של מאפייני משתמשים צריכים להיות באורך של עד 36 תווים.
- שמות של אירועים צריכים להיות באורך של עד 40 תווים, יכולים לכלול רק תווים אלפאנומריים ותווי קו תחתון, וחייבים להתחיל באות.
- שמות של פרמטרים, כולל פרמטרים של פריטים, צריכים להיות באורך של עד 40 תווים, יכולים לכלול רק אותיות, מספרים ותווי קו תחתון, וחייבים להתחיל באות.
- ערכי הפרמטרים, כולל ערכי הפרמטרים של הפריטים, צריכים להיות באורך של עד 100 תווים בנכס Google Analytics רגיל, ובאורך של עד 500 תווים בנכס Google Analytics 360.
- פרמטרים של פריטים יכולים לכלול עד 10 פרמטרים מותאמים אישית.
- גוף הפוסט חייב להיות קטן מ-130KB.
- אירועים של Measurement Protocol לאפליקציות שנשלחים אל Google Analytics לא מאכלסים קהלים לרשת החיפוש ב-Google Ads של משתמשי האפליקציה.
דרישות נוספות לכל תרחיש לדוגמה מפורטות במאמר תרחישים נפוצים לדוגמה.