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

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

    ...

  ],

...

}