במסמך הזה מפורטות כמה תכונות מתקדמות של Google Analytics Data API v1. למידע מפורט על ה-API, אפשר לעיין בהפניית ה-API.
הצגת הגדרות בהתאמה אישית ויצירת דוחות
בעזרת Data API אפשר ליצור דוחות על מאפיינים מותאמים אישית ועל מדדים מותאמים אישית שנרשמו. אפשר להשתמש בשיטת Metadata API כדי להציג את שמות ה-API של ההגדרות המותאמות אישית שרשומות בנכס. אפשר להשתמש בשמות האלה של ה-API בבקשות לדוחות, למשל בשיטה runReport.
בקטעים הבאים מופיעות דוגמאות לכל סוג של הגדרה מותאמת אישית. בדוגמאות האלה, מחליפים את GA_PROPERTY_ID במזהה הנכס.
מאפיינים מותאמים אישית ברמת האירוע
שלב 1: שולחים שאילתה לשיטה של Metadata API עם מזהה הנכס.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
שלב 2: מחפשים בתגובה את המאפיין המותאם אישית ברמת האירוע שרוצים ליצור לגביו דוחות. אם המאפיין לא מופיע, צריך לרשום את המאפיין.
"dimensions": [
...
{
"apiName": "customEvent:achievement_id",
"uiName": "Achievement ID",
"description": "An event scoped custom dimension for your Analytics property."
},
...
],
שלב 3: כוללים את המאפיין המותאם אישית בבקשת דוח. הדוגמה הבאה היא בקשה לשיטה runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [{ "name": "customEvent:achievement_id" }],
"metrics": [{ "name": "eventCount" }]
}
מאפיינים מותאמים אישית ברמת המשתמש
שלב 1: שולחים שאילתה לשיטה של Metadata API עם מזהה הנכס.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
שלב 2: מחפשים בתגובה את המאפיין המותאם אישית ברמת המשתמש שרוצים ליצור לגביו דוחות. אם המאפיין לא מופיע, צריך לרשום את המאפיין.
"dimensions": [
...
{
"apiName": "customUser:last_level",
"uiName": "Last level",
"description": "A user property for your Analytics property."
},
...
],
שלב 3: כוללים את המאפיין המותאם אישית בבקשת דוח. הדוגמה הבאה היא בקשה לשיטה runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"entity": { "propertyId": "GA_PROPERTY_ID" },
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "customUser:last_level" }],
"metrics": [{ "name": "activeUsers" }]
}
מדדים מותאמים אישית ברמת האירוע
שלב 1: שולחים שאילתה לשיטה של Metadata API עם מזהה הנכס.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
שלב 2: מחפשים בתגובה את המדד המותאם אישית ברמת האירוע שרוצים ליצור לגביו דוחות. אם המדד לא מופיע, צריך לרשום אותו.
"metrics": [
...
{
"apiName": "customEvent:credits_spent",
"uiName": "Credits Spent",
"description": "An event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
שלב 3: כוללים את המדד המותאם אישית בבקשת דוח. הדוגמה הבאה היא בקשה לשיטה runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "customEvent:credits_spent" }]
}
מדדים שמתייחסים לשיעור המשתמשים שהפעילו אירוע מרכזי לגבי אירוע מרכזי אחד
שלב 1: שולחים שאילתה לשיטת Metadata API עם מזהה הנכס.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
שלב 2: מחפשים בתגובה את מדד שיעור המשתמשים שהפעילו אירוע מרכזי של אירוע מרכזי אחד שרוצים ליצור לגביו דוחות. אם האירוע המרכזי לא מופיע, צריך להגדיר את האירוע המרכזי.
"metrics": [
...
{
"apiName": "sessionKeyEventRate:add_to_cart",
"uiName": "Session key event rate for add_to_cart",
"description": "The percentage of sessions in which a specific key event was triggered",
},
...
],
שלב 3: כוללים את מדד שיעור המשתמשים שהפעילו אירוע מרכזי בבקשת דוח. הדוגמה הבאה היא בקשה לשיטה runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}
ממוצעים של מדדים מותאמים אישית ברמת האירוע
שלב 1: שולחים שאילתה לשיטה של Metadata API עם מזהה הנכס.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
שלב 2: מאתרים בתגובה את המדד המותאם אישית הממוצע ברמת האירוע שרוצים ליצור לגביו דוחות. אם המדד לא מופיע, צריך לרשום אותו.
"metrics": [
...
{
"apiName": "averageCustomEvent:credits_spent",
"uiName": "Average Credits Spent",
"description": "The average of an event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
שלב 3: כוללים את המדד המותאם אישית הממוצע בבקשת דוח. הדוגמה הבאה היא בקשה לשיטה runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}
דוגמאות לדוח על קבוצה בעלת מאפיינים משותפים
בדוחות על קבוצות בעלות מאפיינים משותפים נוצרת סדרת נתונים כרונולוגית של שימור משתמשים בקבוצה. לעיון במסמכים מפורטים על כל שדה API, אפשר לעיין בהפניה ל-REST בנושא CohortSpec.
יצירת דוח על קבוצה בעלת מאפיינים משותפים
לפניכם דוגמה לדוח על קבוצה בעלת מאפיינים משותפים:
- הקבוצה בעלת המאפיינים המשותפים היא משתמשים עם
firstSessionDateשל2020-12-01; ההגדרה הזו מתבצעת על ידי אובייקטcohorts. המאפיינים והמדדים בתגובת הדוח יתבססו רק על המשתמשים בקבוצה בעלת המאפיינים המשותפים. - בדוח על קבוצה בעלת מאפיינים משותפים יוצגו שלוש עמודות. ההגדרה הזו מתבצעת באמצעות אובייקטים של מאפיינים ומדדים.
- המאפיין
cohortהוא שם הקוהורטה. - המאפיין
cohortNthDayהוא מספר הימים שחלפו מאז2020-12-01. - המדד
cohortActiveUsersהוא מספר המשתמשים שעדיין פעילים.
- המאפיין
- האובייקט
cohortsRangeמציין שהדוח צריך להכיל נתוני אירועים מתאריך2020-12-01עד תאריך2020-12-06עבור הקוהורט הזה.- כשמשתמשים בגרנולריות של
DAILY, מומלץ להשתמש במאפייןcohortNthDayכדי לשמור על עקביות.
- כשמשתמשים בגרנולריות של
בקשת הדוח לגבי הקבוצה בעלת המאפיינים המשותפים היא:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
"metrics": [{ "name": "cohortActiveUsers" }],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "DAILY"
}
},
}
זו דוגמה לתגובה של דוח לבקשה הזו:
{
"dimensionHeaders": [
{ "name": "cohort" }, { "name": "cohortNthDay" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "293" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "143" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "123" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "92" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
"metricValues": [{ "value": "86" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "83" }]
}
],
"metadata": {},
"rowCount": 6
}
בהמשך מופיע תרשים עבור דוח על קבוצה בעלת מאפיינים משותפים זה, שנוצר על סמך התשובה של הדוח הזה. תובנה מהדוח הזה היא שהירידה הכי גדולה במספר המשתמשים הפעילים בקבוצה הזו היא בין היום הראשון ליום השני.

כמה קבוצות בעלות מאפיינים משותפים ושבר שימור המשתמשים
צירוף משתמשים ושימור משתמשים הם דרכים להרחבת השימוש באתר או באפליקציה. דוחות של קבוצות בעלות מאפיינים משותפים מתמקדים בשימור משתמשים. בדוגמה הזו, הדוח מראה שהשיעור של שימור המשתמשים למשך 4 ימים בנכס הזה עלה ב-10% במהלך שבועיים.
כדי ליצור את הדוח הזה, אנחנו מציינים שלוש קבוצות: הראשונה עם firstSessionDate של 2020-11-02, השנייה עם firstSessionDate של 2020-11-09 והשלישית עם firstSessionDate של 2020-11-16. מכיוון שמספר המשתמשים בנכס יהיה שונה בשלושת הימים האלה, אנחנו משווים את מדד שיעור שימור המשתמשים של הקבוצה בעלת המאפיינים המשותפים, שהוא cohortActiveUsers/cohortTotalUsers, במקום להשתמש במדד cohortActiveUsers ישירות.
בקשת הדוח לקבוצות האלה היא:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metrics": [
{
"name": "cohortRetentionFraction",
"expression": "cohortActiveUsers/cohortTotalUsers"
}
],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
}
],
"cohortsRange": {
"endOffset": 4,
"granularity": "DAILY"
}
},
}
זו דוגמה לתגובה של דוח לבקשה הזו:
{
"dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metricHeaders": [{
"name": "cohortRetentionFraction",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
"metricValues": [{ "value": "0.308" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
"metricValues": [{ "value": "0.272" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
"metricValues": [{ "value": "0.257" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "0.248" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
"metricValues": [{ "value": "0.235" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
"metricValues": [{ "value": "0.211" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
"metricValues": [{ "value": "0.198" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "0.172" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
"metricValues": [{ "value": "0.167" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
"metricValues": [{ "value": "0.155" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "0.141" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "0.118" }]
}
],
"metadata": {},
"rowCount": 15
}
בהמשך מופיע תרשים עבור דוח על קבוצה בעלת מאפיינים משותפים זה, שנוצר על סמך התשובה של הדוח הזה. תובנה מהדוח הזה היא ששימור משתמשים אחרי 4 ימים עלה ב-10% במהלך שבועיים. הקבוצה המאוחרת יותר עם firstSessionDate מתוך 2020-11-16 חורגת מהשמירה של הקבוצה המוקדמת יותר עם firstSessionDate מתוך 2020-11-02.

משתמשים שהתקינו בשבוע מסוים ושימוש בקבוצות עם תכונות אחרות של API
כדי להסיר את השונות מיום ליום בהתנהגות המשתמשים, כדאי להשתמש בקבוצות בעלות מאפיינים משותפים שמוגדרות לפי שבוע. בדוחות שבועיים של קבוצות בעלות מאפיינים משותפים, כל המשתמשים עם firstSessionDate באותו שבוע יוצרים את הקבוצה. השבוע מתחיל ביום ראשון ומסתיים בשבת. בנוסף, בדוח הזה אנחנו מבצעים פילוח של הקבוצה כדי להשוות בין משתמשים עם פעילות ברוסיה לבין משתמשים עם פעילות במקסיקו. הפילוח הזה משתמש במאפיין country ובמסנן dimensionFilter כדי להתייחס רק לשתי המדינות.
בקשת הדוח לקבוצות האלה היא:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metrics": [{ "name": "cohortActiveUsers" }],
"dimensionFilter": {
"filter": {
"fieldName": "country",
"inListFilter": {
"values": [ "Russia", "Mexico" ]
}
}
},
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": {
"startDate": "2020-10-04",
"endDate": "2020-10-10"
}
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "WEEKLY"
}
},
}
זו דוגמה לתגובה של דוח לבקשה הזו:
{
"dimensionHeaders": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
],
"metricValues": [{ "value": "105" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "98" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "35" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "24" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
],
"metricValues": [{ "value": "23" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "17" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
],
"metricValues": [{ "value": "3" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
}
],
"metadata": {},
"rowCount": 11
}
בהמשך מופיע תרשים של דוח על קבוצה בעלת מאפיינים משותפים זה. על סמך הדוח הזה, הנכס הזה מצליח יותר לשמר משתמשים עם פעילות במקסיקו מאשר משתמשים עם פעילות ברוסיה.

השוואות
השוואות מאפשרות לכם לבחון קבוצות משנה של נתונים זו לצד זו. אפשר להגדיר השוואות על ידי ציון השדה comparisons בהגדרת הדוח. התכונה 'השוואות' ב-Data API דומה להשוואות בממשק הקצה הקדמי של Google Analytics.
לעיון במסמכים מפורטים של כל שדה API, אפשר לעבור אל הפניית REST להשוואה.
יצירת השוואה
אפשר ליצור השוואה נפרדת לכל קבוצת נתונים שרוצים להשוות. לדוגמה, כדי להשוות בין נתוני אפליקציות לנתוני אתרים, אפשר ליצור השוואה אחת לנתוני Android ו-iOS והשוואה נוספת לנתוני אתרים.
זו דוגמה לדוח שמוגדרות בו שתי השוואות ומוחזרים בו נתונים של משתמשים פעילים עם פירוט לפי מדינה.
ההשוואה הראשונה שנקראת 'תנועה באפליקציה' משתמשת ב-inListFilter כדי להתאים את המאפיין platform לערכים 'iOS' ו-'Android'. ההשוואה השנייה, שנקראת 'תנועה לאתר', משתמשת בstringFilter כדי להתאים את המאפיין platform לערך 'אינטרנט'.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"comparisons": [
{
"name": "App traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"inListFilter": {
"values": [
"iOS",
"Android"
]
}
}
}
},
{
"name": "Web traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"stringFilter": {
"matchType": "EXACT",
"value": "web"
}
}
}
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
],
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
]
}
לכל הבקשות שמשתמשות בתכונת ההשוואות, השדה comparison מתווסף אוטומטית לדוח שנוצר. השדה הזה מכיל את שם ההשוואה שצוין בבקשה.
דוגמה לקטע קוד של תגובה שמכילה השוואות:
{
"dimensionHeaders": [
{
"name": "comparison"
},
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "638572"
}
]
},
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "376578"
}
]
},
{
"dimensionValues": [
{
"value": "App traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "79527"
}
]
},
...
],
...
}