Перейти к основному содержимому

Data API для приложений

Краткое содержание

Data API позволяет получать неагрегированные данные (события и сессии), собранные МТС Аналитикой. Используйте API, если необходимо самостоятельно обрабатывать статистические данные, не используя интерфейс МТС Аналитики.

Как работает API
API работает асинхронно. Сначала создается задача, где описываются параметры выгрузки, затем задача выполняется сервисом. Далее можно скачать результат задачи в формате файла.

Какую программу использовать
Вы можете использовать удобную для вас программу, например, Postman или Insomnia. В тексте описана работа с Data API через Postman. Версия Postman должна быть не ниже v 11.1.3.

Этап 1. Добавить коллекцию в Postman
Коллекция — файл, который содержит все примеры запросов к системе.

  1. Скачайте Коллекцию.
  2. Импортируйте коллекцию в Postman.

Этап 2. Получить авторизационный токен и ID потока
Для доступа к API и потоку данных ресурса вам необходимы:

  1. Авторизационный токен.
  2. Flow ID (идентификатор потока).

Этап 3. Запросить данные
Все возможные запросы размещены в коллекции. Рекомендуется отправлять их последовательно. Перед отправкой каждого укажите актуальные для ваших задач параметры. После POST-запроса установите параметр request_id в окружение, чтобы он автоматически добавлялся в GET-запросы.

Этап 4. Выгрузить файлы
Чтобы получить данные, используйте task id. Скачать данные можно в течение суток, потом файл будет недоступен. Файл сформируется в формате CSV.

Предоставляемые параметры событий и сессий
В таблице указаны названия, типы и описания параметров событий и сессий, включая идентификаторы потоков, время, UTM-метки, данные о пользователях, устройствах, сессиях и т.д.

Возможные статусы задачи
В тексте приведены возможные статусы задачи (CREATED, IN_PROGRESS, SUCCESS, FAILED и др.) с кратким описанием каждого.

Data API позволяет получать неагрегированные данные (события и сессии), собранные МТС Аналитикой. Используйте API, если необходимо самостоятельно обрабатывать статистические данные, не используя интерфейс МТС Аналитики.

Как работает API​

API работает aсинхронно. Сначала создается задача, где описываются параметры выгрузки, затем задача выполняется сервисом. Далее можно скачать результат задачи в формате файла.

Этапы работы с Data API
  1. Добавление коллекции с запросами.
  2. Получение авторизационного токена.
  3. Запрос данных.

Какую программу использовать​

Вы можете использовать удобную для вас программу, например, Postman или Insomnia.

Важно

В этой статье описана работа с Data API через Postman. Версия Postman должна быть не ниже v 11.1.3.

Этап 1. Добавить коллекцию в Postman​

Коллекция — файл, который содержит все примеры запросов к системе.

  1. Скачайте Коллекцию.

  2. Импортируйте коллекцию. Выберите в левом верхнем углу File — Import. В открывшееся окно перенесите файл

import

Результат этапа 1

Вы добавили в Postman коллекцию с запросами.

Этап 2. Получить авторизационный токен и ID потока​

Для доступа к API и потоку данных ресурса вам необходимы:

  1. Авторизационный токен.
  2. Flow ID (идентификатор потока).

Чтобы их получить, обратитесь на почту analytics.support@mts.ru.

Результат этапа 2

Вы получили токен, Flow ID и имя технического пользователя (для доступов) от команды МТС Аналитики.

Этап 3. Запросить данные​

Все возможные запросы размещены в коллекции. Рекомендуем отправлять их последовательно. Перед отправкой каждого укажите актуальные для ваших задач параметры — описаны ниже.

Если запросы выполняются вручную

После POST-запроса установите параметр request_id в окружение, чтобы он автоматически добавлялся в GET-запросы.

Шаг 1. Добавить токен​

Полученный токен добавьте в поле Token — Save

img

Шаг 2. Создать задачу​

  1. Выберите тип задачи без указания модели атрибуции.

  2. Заполните значения параметров, которые соответствуют задачам вашего продукта. В заголовок добавьте токен.

Заметка

receiveFrom и receiveTo можно заменить на:

  • occurrenceFrom / occurrenceTo
  • occurrenceDttmFrom / occurrenceDttmTo

Пример запроса:

curl --request POST \
  --url https://gw.intp.mts-corp.ru/mtsa-data-api/2/v2/dataexporttasks \
  --header 'Accept-Encoding: gzip' \
  --header 'Content-Type: application/json' \
  --header 'Authorization:Bearer {{TOKEN}}'
  --data '{
    "event": "MOBILE_HIT",
    "filter": {
        // "occurrenceFrom": "2023-04-01T00:00:00+03:00",
        // "occurrenceTo": "2024-05-01T00:00:00+03:00"
        "receiveFrom": "2024-04-01T00:00:00+03:00",
        "receiveTo": "2024-05-01T00:00:00+03:00"
        // "occurrenceDttmFrom": "2024-09-20T17:00:00",
        // "occurrenceDttmTo": "2024-10-20T18:00:00"
    },
    "flowIds": [
        "0ad8fafe-8030-818b-3cd000167",
        "0ad8fafe-8030-818b-3cd000166"
    ]
}'

Описания параметров запроса:

ПараметрОпределениеДопустимое значение
URLСсылка на сервер для обращения
flowIdsИдентификаторы потоков данных
EventНазвание событияMOBILE_HIT
receiveFromНачало временного периода, когда событие принято на стороне сервераЗаполняется как время сервера по стандарту ISO 8601
receiveToОкончание временного периода, когда событие принято на стороне сервераЗаполняется как время сервера по стандарту ISO 8601
occurrenceFromНачало временного периода, когда событие принято на стороне клиентаЗаполняется как время клиента в стандартном виде
occurrenceToОкончание временного периода, когда событие принято на стороне клиентаЗаполняется как время клиента в стандартном виде
occurrenceDttmFromАктуален только для задач без атрибуции. Начало временного периода, когда событие принято на стороне клиента, по местному времениЗаполняется как время клиента в стандартном виде без указания часового пояса
occurrenceDttmToАктуален только для задач без атрибуции. Окончание временного периода, когда событие принято на стороне клиента, по местному времениЗаполняется как время клиента в стандартном виде без указания часового пояса

Ответ:

Структура задачи с заполненным task id (в скрипте — id). Он пригодится для отслеживания статуса выполнения задачи

{
    "id": "0ad8fafe-8030-818b-3cd0001",
    "event": "MOBILE_HIT",
    "status": "CREATED",
    "filter": {
        "occurrenceFrom": "2023-03-31T21:00:00Z",
        "occurrenceTo": "2024-04-30T21:00:00Z",
        "receiveFrom": null,
        "receiveTo": null
    },
    "flowIds": [
        "0ad8fafe-8030-818b-3cd000166",
        "0ad8fafe-8030-818b-3cd000167"
    ],
    "result": {
        "partsCount": 1
    }
}

Шаг 3. Запросить результат по задаче​

Варианты запроса:

  • Получить информацию о задаче и её статус по id (идентификатор получен в ответе на Шаге 2)
  • Получить ответ по всем задачам без пагинации
  • Получить ответ по всем задачам с пагинацией. Список задач разбивается по страницам — это полезно, когда задач много

Пример ответа:

При успешном завершении задачи в поле status будет значение SUCCESS

{
  "id": "0ad8fafe-8b39-1030-818b-3cd5660001",
  "event": "MOBILE_HIT",
  "status": "SUCCESS",
  "filter": {
    "occurrenceFrom": null,
    "occurrenceTo": null,
    "receiveFrom": "2023-09-27T20:00:00Z",
    "receiveTo": "2023-09-28T14:00:00Z"
  },
  "result": {
    "partsCount": 1
  }
}

PartsCount — количество файлов, которые были созданы по запросу.

Возможные статусы
СтатусОписание
CREATEDЗадание создано
IN_PROGRESSВыполняется задание выборки данных
SUCCESSВыборка выполнена, результат сохранен
FAILEDПроизошла ошибка
RESULT_CLEANED_AS_TOO_OLDРезультат устарел

Шаг 4. Выгрузить файлы​

Чтобы получить данные, используйте task id. Для отправки запроса нажмите Send and Download.

Запрос по task id с указанием части (страницы):

task

Заметка

Скачать данные можно в течение суток, потом файл будет недоступен. Первому файлу присваивается номер 0.

Ответ:

Один или несколько файлов. В ответе может быть несколько файлов, если объем данных будет слишком большим для одного файла. Файл сформируется в формате CSV.

Результат этапа 4

Вы получили файл для дальнейшей работы с данными.

Предоставляемые параметры событий и сессий​

НазваниеТипОписание
d:flowIdUUIDУникальный идентификатор потока, который присваивается МТС Аналитикой, — значение Flow ID
d:processDttmDateTimeВремя завершения выполнения запроса на сервере
d:processOffsetInt16Смещение на сервере (время сервера)
d:UTMCampaignStringUTM campaign. Название рекламной кампании. Идентифицирует конкретную рекламную кампанию
d:UTMMediumStringUTM medium. Канал трафика. Например, СМС
d:UTMSourceStringUTM source. Источник трафика. Место, откуда пользователи переходят на ваш ресурс. Например, Яндекс
d:UTMContentStringUTM content. Содержание рекламной кампании. Идентифицирует конкретное объявление или баннер, на который кликнул пользователь перед переходом на сайт
d:UTMTermStringUTM Term. Ключевая фраза
d:hitIdUInt64Уникальный идентификатор события
d:sessionIdUInt64Уникальный идентификатор сессии
d:clientIdUInt64 / UUIDУникальный идентификатор клиента.
Клиент — это уникальный идентификатор пользователя, который формируется в авторизованной и неавторизованной зоне. Отправляется автоматически с каждым событием.
1. WEB — 1st-party cookie файл браузера.
2. APP — Id устройства (Android: app_set_id, iOS: idfv)
d:hitNameStringУникальное название конкретного события
d:hitTypeStringТип события. Возможные значения: pageview — просмотр страницы, event — событие, ecommerce — событие электронной коммерции
d:hitDataStringПеречень параметров события электронной коммерции. Заполняется автоматически, если реализована разметка электронной коммерции
d:contentObjectStringНабор пользовательский параметров события.
d:hitCountUInt32Порядковый номер события пользователя в его сессии
d:newUserUInt8Признак того, что пользователь был новым
d:sessionCountUInt32Порядковый номер сессии пользователя
d:activationCountUInt32Число активаций одной сессии. Например, пользователь 2 раза в течение 30 минут сворачивал приложение. Количество активаций: 2
d:hitCartItemsArray(Array(String))Состав корзины при покупке Формат: Вода(2ед.),T-Shirt(1ед.)
d:hitRevenueDECIMAL(18,2)Выручка от одного события
d:screenTitleStringНазвание страницы, на которой произошло событие. Передаётся, только если оно указано в коде сайта
d:subdivisionISOCodeStringБуквенный ISO-код региона, который идентифицируется на устройстве
d:subdivisionNameStringНазвание региона, где находится устройство
d:localeCodeStringКод идентификации географического местоположения устройства. Возможные значения: ru — устройство находится в Российской Федерации, NA — устройство находится в другой стране
d:cityNameStringНазвание населённого пункта, где находится устройство
d:countryISOCodeStringКод страны, который идентифицируется на устройстве
d:userAgeStringВозрастной диапазон пользователя
d:userSexStringПол пользователя
d:connectionTypeStringТип подключения устройства. Например, Wi-Fi
d:MNCUInt16MNC (Mobile Network Code). Например, «1» для MTS RUS
d:MCCUInt16Мобильный код страны. Например, 250
d:screenResolutionStringРазрешение экрана устройства
d:SDKVersionStringВерсия SDK МТС Аналитики, установленного на сайте
d:mobileOperatorStringМобильный оператор пользователя
d:deviceTypeStringВозможные значения: ПК, игровые консоли, смартфоны, планшеты, цифровые медиа-ресиверы
d:deviceLanguageStringЯзык браузера/устройства
d:deviceManufacturerStringПроизводитель устройства. Например, Apple
d:deviceOriginalModelStringЗаводская модель устройства. Например, SM-G9950 для Galaxy S8
d:OSNameStringНазвание операционной системы устройства
d:OSVersionStringВерсия операционной системы устройства
d:APPVersionNameStringВерсия приложения, указанная разработчиком
d:APPIdStringУникальный идентификатор приложения. Формируется при добавлении приложения в Google Play
d:APPPackageNameStringНазвание пакета приложения. Уникальный идентификатор приложения на Android-устройстве, в Google Play и в сторонних магазинах
d:APPBuildNumberStringНомер сборки приложения
d:hitDateTimeDateTimeДата и время в точности до секунды, когда было совершено событие
d:dateDateTimeДень, когда произошло событие: dd.mm.yyyy
d:weekDateTimeНеделя, когда произошло событие: dd.mm.yyyy - dd.mm.yyyy
d:monthDateTimeМесяц, когда произошло событие: mm.yyyy
d:occurrenceDateTimeDateTimeДата и время в точности до секунды, когда событие произошло у клиента
d:UTCOffsetInt16Часовой пояс устройства в формате отклонения времени совершения события от UTC в минутах. Например, 180 означает, что клиентское время GMT+3
d:experimentVariantsArray(UInt64)Перечень ID экспериментов в МТС Аналитике, в которых участвует пользователь
d:CDUserAuthStringПризнак авторизации на ресурсе. Например, возможные значения: 1 — авторизован, 0 — не авторизован
d:CDUserIDStringУникальный идентификатор пользователя. Генерируется на стороне ресурса. Позволяет связать сессии в разных браузерах с одним пользователем
d:CDProjectNameStringПроект, с которым связано событие. Например, название акции
d:CDRegionStringРегион, установленный пользователем на устройстве
d:CDTouchPointStringТочка касания с продуктом. Например, лендинг или сайт
d:CDClientIDStringИдентификатор, который проставляется другой системой аналитики. Может использоваться для сравнения данных систем аналитики
d:CDmclientIDStringПользовательский идентификатор, который используется, например, для определения ветки A/B-теста
d:CDMultiAccountTypeStringТип аккаунта, если на вашем ресурсе один пользователь может создать несколько учётных записей
d:CDAccountTypeStringТип аккаунта. Используйте, если на ресурсе можно создать несколько аккаунтов. Например, B2C и B2B
d:CDCurrentTariffStringТип подписки или тарифа пользователя
d:CDProfileTypeStringЛюбой атрибут профиля пользователя. Например, пол или уровень среднего чека
d:CDGRClientIDStringЛюбой атрибут пользователя. Например, email
d:CDGRIDStringНапример, статус подтверждения профиля пользователя. Возможные значения: 1 — профиль подтверждён, 0 — профиль не подтверждён
d:CDProductUIDStringИдентификатор продукта, с которым связано событие. Например, ID категории товара
d:CDProfileStatusStringСтатус подтверждения профиля пользователя
d:CDAdvertIDStringРекламный идентификатор. Например, значение ID рекламной системы, которую она формирует в браузере пользователя
d:CDDeviceIDStringПроизвольный идентификатор устройства
d:CDSessionIDStringКастомный идентификатор сессии. Например, номер сессии из другой системы аналитики. Можно использовать для сравнения систем
d:CDHitIDStringКастомный идентификатор события
d:CDTimeStampStringВремя, когда произошло событие в формате UNIX
d:CDInteractionTypeStringТип совершённого события. Например, возможные значения: non-interactions, interactions, conversions
d:CDScreenNameStringКастомное название страницы
d:CDEventCategoryStringКатегория события
d:CDEventActionStringВзаимодействие пользователя с объектом сайта. Например, клик по кнопке или просмотр баннера
d:CDEventLabelStringЯрлык события. Например, «Подключить»
d:CDEventContentStringКонтент в событии. Например, текст кнопки или поисковый запрос на ресурсе
d:CDEventContextStringКонтекст, в котором было совершено событие. Например, сценарий покупки смартфона
d:CDEventValueStringЦенность события. Например, стоимость товара или другая нематериальная ценность
d:CDProductCategoryStringКатегория продукта
d:CDProductNameStringНазвание категории товара, с которой связано событие. Например, аксессуары
d:CDProductIdStringИдентификатор продукта, с которым связано событие. Например, ID категории товара
d:CDfunnelNameStringНазвание воронки. Если передаёте, обязательно заполните параметр «funnelStep»
d:CDfunnelStepStringШаг воронки
d:CDButtonLocationStringМесто расположения кнопки на экране. Например, pop-up
d:CDFilterNameStringНазвания применённых фильтров
d:CDAppThemeStringТема браузера. Например, тёмная
d:CDEcoStringНазвание экосистемного модуля
d:CDFormIDStringИдентификатор формы на сайте
d:CDFormOrderIdStringИдентификатор отправленной заявки
d:CDElementPositionStringНомер элемента интерфейса. Например, порядковый номер карточки в каталоге
d:CDProductPromoStringНаличие акции на продукт
d:CDProductAvailabilityStringНаличие товара в электронной коммерции. Например, возможные значения: 1 — товар в наличии, 0 — товара нет в наличии
d:CDDeliveryTermsStringУсловия доставки
d:CDPaymentTypeStringСпособ оплаты
d:CDDeliveryTypeStringСпособ доставки
d:CDBannerIdStringИдентификатор рекламного баннера
d:CDBannerNameStringНазвание баннера
d:CDabNameStringНазвание А/В-теста. Актуально, если эксперимент запускается не в МТС Аналитике, а в другом сервисе
d:CDabVariantStringВарианты в А/В-тесте. Актуально, если эксперимент запускается не в МТС Аналитике, а в другом сервисе
d:CDAppsFlyerIDStringИдентификатор пользователя, который присваивается Appsflyer
d:CD1StringПользовательский параметр №1
d:CD2StringПользовательский параметр №2
d:CD3StringПользовательский параметр №3
d:CD4StringПользовательский параметр №4
d:CD5StringПользовательский параметр №5
d:CD6StringПользовательский параметр №6
d:CD7StringПользовательский параметр №7
d:CD8StringПользовательский параметр №8
d:CD9StringПользовательский параметр №9
d:CD10StringПользовательский параметр №10