במסמך הזה מתוארות כמה תכונות מתקדמות של Google Analytics Data API v1. הפנייה מפורטת ל-API מופיעה במאמר הפניית API.
הצגת רשימה של הגדרות בהתאמה אישית ויצירת דוחות
באמצעות Data API אפשר ליצור דוחות על מאפיינים מותאמים אישית ומדדים מותאמים אישית רשומים. אפשר להשתמש בשיטת ה-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: כוללים את המדד 'שיעור האירועים המרכזיים' בבקשה לדוח. זוהי דוגמה לבקשה ל-method 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"
}
]
},
...
],
...
}