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

במסמך הזה מתוארות כמה תכונות מתקדמות של Google Analytics Data API v1. למידע מפורט על ה-API, קראו את מאמרי העזרה של ה-API.

הצגת רשימה של הגדרות מותאמות אישית ויצירת דוחות

באמצעות Data API אפשר ליצור דוחות על מאפיינים מותאמים אישית ומדדים מותאמים אישית רשומים. אפשר להשתמש בשיטה Metadata API כדי להציג את שמות ה-API של ההגדרות המותאמות אישית שרשומות בנכס. אפשר להשתמש בשמות ה-API האלה בבקשות דוחות ל-method ‏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: כוללים את המאפיין המותאם אישית בבקשה לדוח. הדוגמה הבאה היא בקשה לדוגמה ל-method‏ 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: כוללים את המאפיין המותאם אישית בבקשה לדוח. הדוגמה הבאה היא בקשה לדוגמה ל-method‏ 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: כוללים את המדד המותאם אישית בבקשת דוח. הדוגמה הבאה היא בקשה לדוגמה ל-method‏ 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 Method עם מזהה הנכס.

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: כוללים את הממוצע של המדד המותאם אישית בבקשת הדוח. הדוגמה הבאה היא בקשה לדוגמה ל-method‏ 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"
        }
      ]
    },

    ...

  ],

...

}