Data API для сайтов

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

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

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

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

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

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

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

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

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

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

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

Шаг 1. Добавить токен
Полученный токен добавьте в поле Token — Save.

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

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

Шаг 3. Запросить результат по задаче
Варианты запроса:

• Получить информацию о задаче и её статус по id.
• Получить ответ по всем задачам без пагинации.
• Получить ответ по всем задачам с пагинацией.

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

Предоставляемые параметры событий и сессий
В таблице можно найти параметры, такие как flowId, ma_process_dttm, ma_referer_host, ma_hit_id и другие.

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. В открывшееся окно перенесите файл

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Шаг 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": "WEB_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	Название события	WEB_HIT, SESSION
Model	Название модели атрибуции	LAST_CLICK, LAST_PAID_CLICK, POST_CLICK, POST_VIEW
Window	Окно атрибуции	1 — 180
receiveFrom	Начало временного периода, когда событие принято на стороне сервера	Заполняется как время сервера по стандарту ISO 8601
receiveTo	Окончание временного периода, когда событие принято на стороне сервера	Заполняется как время сервера по стандарту ISO 8601
occurrenceFrom	Начало временного периода, когда событие принято на стороне клиента	Заполняется как время клиента в стандартном виде
occurrenceTo	Окончание временного периода, когда событие принято на стороне клиента	Заполняется как время клиента в стандартном виде
occurrenceDttmFrom	Актуален только для задач без атрибуции. Начало временного периода, когда событие принято на стороне клиента, по местному времени	Заполняется как время клиента в стандартном виде без указания часового пояса
occurrenceDttmTo	Актуален только для задач без атрибуции. Окончание временного периода, когда событие принято на стороне клиента, по местному времени	Заполняется как время клиента в стандартном виде без указания часового пояса

Ответ:

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

{
    "id": "0ad8fafe-8030-818b-3cd0001",
    "event": "WEB_HIT",
    "status": "CREATED",
    "attribution": {
        "model": "LAST_CLICK",
        "window": 30
    },
    "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": "WEB_HIT",
  "status": "SUCCESS",
  "attribution": {
    "model": "LAST_CLICK",
    "window": 1
  },
  "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 с указанием части (страницы):

Заметка

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

Ответ:

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

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

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

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

Название	Тип	Описание
flowId	UUID	Уникальный идентификатор потока, который присваивается МТС Аналитикой, — значение Flow ID
ma_process_dttm	DateTime	Время завершения выполнения запроса на сервере
ma_process_offset	Int16	Смещение на сервере (время сервера)
ma_referer_host	String	Хост URL источника, из которого пользователь перешел на ваш ресурс. В МТС Аналитике этот адрес проставляется в каждое событие сессии
ma_hit_id	UInt64	Уникальный идентификатор события
ma_session_id	UInt64	Уникальный идентификатор сессии
ma_client_id	UInt64	Уникальный идентификатор клиента: 1st-party cookie файл браузера. Формируется в авторизованной и в неавторизованной зоне, отправляется автоматически с каждым событием с SDK
ma_hit_name	String	Уникальное название конкретного события
ma_hit_type	String	Тип события. Возможные значения: pageview — просмотр страницы, event — событие, ecommerce — событие электронной коммерции
ma_hit_data	String	Перечень параметров события электронной коммерции. Заполняется автоматически, если реализована разметка электронной коммерции
contentObject	String	Набор пользовательский параметров события
ma_hit_indx	UInt32	Порядковый номер события пользователя в его сессии
ma_session_indx	UInt32	Порядковый номер сессии пользователя
ma_cs_fingerprint	String	Цифровой отпечаток на клиенте
ma_screen_title	String	Название страницы, на которой произошло событие. Передаётся, только если оно указано в коде сайта
ma_url_host	String	Домен сайта. Например, a.mts.ru
ma_url_path	String	Страница, на которой произошло событие пользователя
ma_url_params	String	Дополнительные параметры ссылки после знака ?. В них могут содержаться, например, UTM-метки
ma_geo_subdivision_name	String	Название региона, где находится устройство
ma_geo_city_name	String	Название населённого пункта, где находится устройство
ma_user_age	String	Возрастной диапазон пользователя
ma_user_sex	String	Пол пользователя
ma_screen_resolution	String	Разрешение экрана устройства
ma_device_name	String	Название устройства пользователя
ma_device_type	String	Возможные значения: ПК, игровые консоли, смартфоны, планшеты, цифровые медиа-ресиверы
ma_browser_name	String	Название браузера, в котором пользователь просматривает сайт
ma_os_name	String	Название операционной системы устройства
ma_occurrence_dttm	DateTime	Дата и время в точности до секунды, когда событие произошло у клиента
ma_occurrence_offset	Int16	Часовой пояс устройства в формате отклонения времени совершения события от UTC в минутах. Например, 180 означает, что клиентское время GMT+3
ma_receive_dttm	DateTime	Дата и время в точности до секунды, когда событие пришло событие на сервер МТС Аналитики
UserAuth	String	Признак авторизации на ресурсе. Например, возможные значения: 1 — авторизован, 0 — не авторизован
own_user_id	String	Уникальный идентификатор пользователя. Генерируется на стороне ресурса. Позволяет связать сессии в разных браузерах с одним пользователем
ProjectName	String	Проект, с которым связано событие. Например, название акции
Region	String	Регион, установленный пользователем на устройстве
TouchPoint	String	Точка касания с продуктом. Например, лендинг или сайт
ClientID	String	Идентификатор, который проставляется другой системой аналитики. Может использоваться для сравнения данных систем аналитики
mclientID	String	Пользовательский идентификатор, который используется, например, для определения ветки A/B-теста
mtsID	String	Рекламный идентификатор МТС. Например, заполняется, если нужно запустить рекламную кампанию в МТС AdTech
mtsIDLastSync	String	Время последней авторизации
MultiAccountType	String	Тип аккаунта, если на вашем ресурсе один пользователь может создать несколько учётных записей
AccountType	String	Тип аккаунта. Используйте, если на ресурсе можно создать несколько аккаунтов. Например, B2C и B2B
CurrentTariff	String	Тип подписки или тарифа пользователя
ProfileType	String	Любой атрибут профиля пользователя. Например, пол или уровень среднего чека
GRClientID	String	Любой атрибут пользователя. Например, email
GRID	String	Например, статус подтверждения профиля пользователя. Возможные значения: 1 — профиль подтверждён, 0 — профиль не подтверждён
ProductUID	String	Идентификатор продукта, с которым связано событие. Например, ID категории товара
ProfileStatus	String	Статус подтверждения профиля пользователя
AdvertID	String	Рекламный идентификатор. Например, значение ID рекламной системы, которую она формирует в браузере пользователя
DeviceID	String	Произвольный идентификатор устройства
SessionID	String	Кастомный идентификатор сессии. Например, номер сессии из другой системы аналитики. Можно использовать для сравнения систем
HitID	String	Кастомный идентификатор события
TimeStamp	String	Время, когда произошло событие в формате UNIX
InteractionType	String	Тип совершённого события. Например, возможные значения: non-interactions, interactions, conversions
EventGroup	String	Группа, которая объединяет категории событий. Например, покупка техники
EventName	String	Группа, которая объединяет разные EventGroup
ScreenName	String	Кастомное название страницы
EventCategory	String	Категория события
EventAction	String	Взаимодействие пользователя с объектом сайта. Например, клик по кнопке или просмотр баннера
EventLabel	String	Ярлык события. Например, «Подключить»
EventContent	String	Контент в событии. Например, текст кнопки или поисковый запрос на ресурсе
EventContext	String	Контекст, в котором было совершено событие. Например, сценарий покупки смартфона
EventValue	String	Ценность события. Например, стоимость товара или другая нематериальная ценность
ProductCategory	String	Категория продукта
ProductName	String	Название категории товара, с которой связано событие. Например, аксессуары
ProductId	String	Идентификатор продукта, с которым связано событие. Например, ID категории товара
funnelName	String	Название воронки. Если передаёте, обязательно заполните параметр «funnelStep»
funnelStep	String	Шаг воронки
ButtonLocation	String	Место расположения кнопки на экране. Например, pop-up
FilterName	String	Названия применённых фильтров
AppTheme	String	Тема браузера. Например, тёмная
Eco	String	Название экосистемного модуля
FormID	String	Идентификатор формы на сайте
FormOrderId	String	Идентификатор отправленной заявки
ElementPosition	String	Номер элемента интерфейса. Например, порядковый номер карточки в каталоге
EventPosition	String	Устаревшее поле ElementPosition. Сохранено для обратной совместимости
ProductPromo	String	Наличие акции на продукт
EventProductPromoLabel	String	Устаревшее поле ProductPromo. Сохранено для обратной совместимости
ProductAvailability	String	Наличие товара в электронной коммерции. Например, возможные значения: 1 — товар в наличии, 0 — товара нет в наличии
EventProductAvailability	String	Устаревшее поле ProductAvailability. Сохранено для обратной совместимости. Наличие товара в электронной коммерции. Например, возможные значения: 1 — товар в наличии, 0 — товара нет в наличии
DeliveryTerms	String	Условия доставки
EventProductDeliveryTerms	String	Устаревшее поле DeliveryTerms. Сохранено для обратной совместимости. Условия доставки
PaymentType	String	Способ оплаты
DeliveryType	String	Способ доставки
BannerId	String	Идентификатор рекламного баннера
BannerName	String	Название баннера
abName	String	Название А/В-теста. Актуально, если эксперимент запускается не в МТС Аналитике, а в другом сервисе
abVariant	String	Варианты в А/В-тесте. Актуально, если эксперимент запускается не в МТС Аналитике, а в другом сервисе
LastUTMSource	String	Последний источник по вашей версии
LastUTMMedium	String	Последний канал по вашей версии
LastUTMCampaign	String	Последняя кампания по вашей версии
MtsIDAuthState	String	ID сессии авторизации
CD1	String	Пользовательский параметр №1
CD2	String	Пользовательский параметр №2
CD3	String	Пользовательский параметр №3
CD4	String	Пользовательский параметр №4
CD5	String	Пользовательский параметр №5
CD6	String	Пользовательский параметр №6
CD7	String	Пользовательский параметр №7
CD8	String	Пользовательский параметр №8
CD9	String	Пользовательский параметр №9
CD10	String	Пользовательский параметр №10