Tracking API

Статус документа

Оглавление

Общее описание

Данный документ описывает Tracking API, служащий для отправки статистической информации на серверы аналитики Инетры.

Данное решение довольно общее, но в то же время достаточно простой способ для описания любых событий в приложении. Отличительными свойствами от аналогичных API являются следующие:

1. Отсутствует ограничения на тип и количество пользовательских переменных.
2. Единый формат передачи данных для стандартных параметров и пользовательских переменных (упрощается разбор на стороне сервера).

Точка входа — адрес http://analytics.cn.ru/2/collect/<product_id>. Где:

• 2 — мажорная версия данного документа,
• <product_id> — идентификатор продукта.

Идентификаторы продуктов

В API заложена передача событий от различных продуктов. Информацию о продукте могут предоставлять различные приложения (например, о продукте Пирс информацию могут предоставлять: хаб, клиент Peers 1, клиент Peers 3). Для избежания путаницы продуктов и программ, которые их реализуют, вводятся их идентификаторы.

Принцип работы

Передача параметров

Все параметры передаются с помощью GET–запроса на сервер, экранированные при необходимости с помощью процентного кодирования, описанного в RFC3986. Зарезервированные символы, входящие в состав значений параметров, должны быть заэкранированы.

Все строки передаются в кодировке UTF–8.

Возвращаемый результат

Возвращаемый результат — всегда пустой ответ с HTTP–кодом ответа 2xx.

Все остальное (таймаут соединения, коды с ответом 4xx и 5xx) означает, что сервер сбора статистики не принял данные и необходима их повторная отправка. При этом, как описано в RFC2616, коды 4xx означает неверно сформированный запрос на стороне клиента и клиенту рекомендуется изменить запрос.

При переотправке события клиент ДОЛЖЕН передать уникальный идентификатор события в неизмененном виде.

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

Ограничения

Длина каждой строки запроса не должна превышать 8192 байт.

Описание окружения

Окружение описывается в заголовке UserAgent или в параметре ua, если изменение заголовка UserAgent невозможно.

В окружении рекомендуется указывать, в указанном порядке:

1. Обязательно: идентификатор приложения / его версию
2. Обязательно: идентификатор операционной системы / ее версию
3. Тип устройства (обязательно) и если известно, имя производителя устройства через символ /
4. Если известно, то модель устройства / ее версию

Строка версии не должна содержать пробелов. При наличии, они должны быть заменены символом _.

Типы устройств

1. desktop — компьютер или ноутбук
2. phone — смартфон
3. tablet — планшет
4. stb — Set Top Box, телеприставка
5. tv — Smart TV, телевизор
6. browser — браузер (для web–приложений)

Идентификаторы операционных систем

1. Windows — операционная система Windows (95, 98, ME)
2. WindowsNT — операционная система Windows, начиная с Windows NT 3
3. OS_X — операционные системы Apple для десктопов
4. iOS — операционные системы Apple для устройств
5. Android — операционная система Google для устройств

Примеры

Использование UUID

API используется следующие идентификаторы:

• идентификатор установки — создается при первом запуске приложения и сохраняется между запусками приложения.
• идентификатор сессии — пересоздается при каждом запуске приложения.

В качестве идентификаторов используется строковое представление UUID.

Общее количество уникальных ключей UUID составляет 2¹²⁸ = 256¹⁶ или около 3.4 × 10³⁸. Это означает, что генерируя 1 триллион ключей каждую наносекунду, перебрать все возможные значения удастся лишь за 10 миллиардов лет.

Wikipedia

Стандартные параметры

Служебная информация

Передача параметров о пользователе

Передача времени

Информация о событии

Информация о странице (только для веб–приложений)

Дополнительные параметры

В данном документе описаны лишь общие параметры, используемые во всех продуктах для отправки информации о любых событиях. Однако события могут иметь дополнительные параметры, необходимые для передачи серверу.

Для использования таких событий должны быть соблюдены следующие условия:

1. Все события продукта должны быть описаны в документе, за актуальность которого отвечает руководитель продукта.
2. Требования к документу:
   1. Документ должен быть версионирован согласно принципу major.minor, где версия major повышается при любых изменениях событий или параметров, а minor — при любых других изменениях.
   2. В любой момент любому участнику проекта должны быть доступны все версии документа.
   3. Для каждого события должно быть указано:
      1. Идентификатор события, который будет передаваться в стандартном параметре t
      2. Дополнительные параметры, для каждого параметра должны быть перечислены:
         1. имя параметра
         2. тип передаваемых данных: булев, число, строка, константа
         3. единицы измерения (для чисел)
         4. смысл параметра
         5. необязательность параметра, если таковая возможна
      3. Значения перечисленных констант и их смысл
   4. Требования к именам дополнительных параметров:
      1. должны начинаться с символа _ и должны состоять только из латинских символов в нижнем регистре, цифр и символа _
      2. параметры разных событий могут иметь одинаковые имена только в случае, если они содержат один и тот же логический смысл
   5. Требования к значениям дополнительных параметров:
      1. Булев тип должен передавать два значения: 1, если подразумевается истина, 0 — если ложь
      2. Числовой тип должен отделять дробную часть от целой с помощью символа .
3. Приложение при отправке события должно передавать major версию документа, которому соответствует событие, в стандартном параметре vext
4. Контроль соответствия отправляемых приложением данных указанной версии документа лежит на руководителе проекта.

Cобытия, не соответствующие версии расширения или с версиями расширений, отсутствующих в документации, будут проигнорированы сервером обработки статистики.

История версий

Изменения в версии 2.0

1. Версия трекинга переехала в неизменяемую часть URL, по аналогии с другими API
2. Идентификатор продукта вынесен в неизменяемую часть URL для удобства обработки на стороне сервера
3. Понятие “сервис” заменено понятием “продукт”
4. Уточнен алгоритм экранирования параметров
5. Изменен способ передачи информации о приложении, операционной системы и устройстве, на котором работает приложение в сторону более простой обработки принимающей стороной
6. Добавлен стандартный параметр vext, описывающий версию сопроводительного документа по статистике продукта
7. Добавлены требования на сопроводительный документ по статистике продукта

Изменения в версии 2.0.1

1. Добавлен идентификатор продукта BitFog — peer-to-peer доставки контента.

Изменения в версии 2.0.2

1. Добавлено требование обязательного экранирования зарезервированных символов, входящих в значения параметров.

Изменения в версии 2.0.3

1. Исправлено значение константы операционной системы Apple для десктопов

Изменения в версии 2.0.4

1. Уточнено именование продукта ByteFog

Изменения в версии 2.0.5

1. Изменено описание параметра tz, обновлен пример, чтобы избежать неоднозначности толкования;
2. Уточнено описание параметра qt.

Изменения в версии 2.1.0

1. Добавлен рекомендуемый параметр eid.