תרחישים מתקדמים לדוגמה

במסמך הזה מתוארים כמה תכונות מתקדמות של 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.

משתמשים שהתקינו בשבוע מסוים ושימוש בקבוצות בעלות מאפיינים משותפים (cohort) עם תכונות אחרות של 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"
        }
      ]
    },

    ...

  ],

...

}