Примеры использования расширенных функций

В этом документе описаны некоторые продвинутые функции Google Analytics Data API версии 1. Подробную информацию об 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 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. Добавьте показатель доли ключевых событий в запрос отчета. Ниже приведен пример запроса к методу 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
}

Ниже приведена диаграмма для этого отчета о когорте, созданная на основе данных из этого ответа. Из этого отчета можно сделать вывод, что наибольшее снижение количества активных пользователей в этой когорте происходит между первым и вторым днем.

Визуализация данных о пользователях когорт за определенный период

Несколько когорт и доля удержания пользователей

Привлечение и удержание пользователей – это способы развития сайта или приложения. Отчеты о когортах позволяют отслеживать удержание пользователей. В этом примере в отчете показано, что за две недели удержание пользователей в течение четырех дней улучшилось на 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
}

Ниже приведена диаграмма для этого отчета о когорте, созданная на основе данных из этого ответа. Из этого отчета можно узнать, что за две недели показатель удержания пользователей на четвертый день вырос на 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 Аналитики.

Подробную документацию по каждому полю API можно найти в справочнике по REST для сравнения.

Как создать сравнение

Вы можете создать отдельное сравнение для каждого интересующего вас набора данных. Например, чтобы сравнить статистику сайта и приложения, можно создать одно сравнение для данных Android и iOS, а другое – для данных сайта.

Ниже приведен пример отчета, в котором определены два сравнения и возвращены данные об активных пользователях с разбивкой по странам.

Первое сравнение, "Трафик приложений", использует inListFilter, чтобы сопоставить параметр platform со значениями "iOS" и "Android". Второе сравнение, "Трафик сайта", использует stringFilter, чтобы сопоставить параметр platform со значением "web".

  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"
        }
      ]
    },

    ...

  ],

...

}