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

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

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

תצוגה חזותית של קבוצות בעלות מאפיינים משותפים (cohort) של משתמשים לאורך זמן

קבוצות בעלות מאפיינים משותפים מרובות וחלק מהמשתמשים שנשארים

צירוף משתמשים ושמירה עליהם הם דרכים להגדלת היקף השימוש באתר או באפליקציה. דוחות על קבוצות בעלות מאפיינים משותפים מתמקדים בשמירה על משתמשים. בדוגמה הזו, הדוח מראה שהנכס הזה שיפר את שיעור שימור המשתמשים אחרי 4 ימים ב-10% במהלך שבועיים.

כדי ליצור את הדוח הזה, אנחנו מציינים שלוש קבוצות בעלות מאפיינים משותפים: הראשונה עם הערך firstSessionDate2020-11-02, השנייה עם הערך firstSessionDate2020-11-09 והשלישית עם הערך firstSessionDate2020-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"
        }
      ]
    },

    ...

  ],

...

}