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

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

    ...

  ],

...

}