Общие положения API Сплиттера

В этом разделе описаны основные детали API Trisigma Splitter.

Для работы с API потребуется получить Bearer-токен авторизации, который предоставляется менеджером Trisigma. Данный токен необходимо включать в заголовок Authorization каждого запроса.

API сплиттера использует RPC-протокол на базе HTTP.

API можно тестировать без предварительно настроенных экспериментов. Однако для более точного тестирования рекомендуется завести эксперимент в Trisigma.

Для выполнения запроса необходимо делать POST-запросы вида: https://<host>/<method_name>/.

Обратите внимание: косая черта (/) в конце адреса запроса обязательна.

Параметр <host> можно узнать у менеджера Trisigma, так как для каждого клиента он является уникальным.

Методы API

Получение списка фичей (`getFeaturesByTag`)

Метод getFeaturesByTag используется для получения списка фичей, связанных с заданным тегом.

Параметры запроса

Эта таблица описывает все поля, которые необходимо передать в теле JSON-запроса.

Параметр	Тип	Описание	Обязательный
`tag`	`string`	Тэг эксперимента, используемый для группировки.	Да
`platform.id`	`int`	ID платформы (например, `1` для Desktop).	Да
`platform.version`	`string`	Версия платформы (например, версия приложения: "2.15.0").	Да
`participant.userId`	`int`	ID пользователя. Хотя бы один из идентификаторов (`userId` или `visitorId`) должен быть передан.	Условно
`participant.visitorId`	`string`	ID устройства или анонимного посетителя. Хотя бы один из идентификаторов (`userId` или `visitorId`) должен быть передан.	Условно
`randomizationUnits`	`list`		Нет
`randomizationUnits.type`	`string`	Тип параметра пользователя
`randomizationUnits.value`	`string`	Значение параметра пользователя

Формирование запроса

URL:

POST https://<host>/getFeaturesByTag/

Заголовки:

Authorization: Bearer <ваш_токен>
Content-Type: application/json
X-Source: local

Тело запроса:

{
  "tag": "<ваш_тег>",
  "platform": {
    "id": 1,
    "version": "2.15.0"
  },
  "participant": {
    "userId": 123456
  },
  "randomizationUnits": [
    {
      "type": "phone_hash",
      "value": "33AFF380-6289-4B76-BB19-46EB8B7D8998"
    },
    {
      "type": "age",
      "value": "30"
    },
    {
      "type": "rating",
      "value": "78"
    }
  ]
}

Пример успешного ответа

{
  "result": {
    "features": [
      {
        "label": "test_group",
        "experimentLabel": "demo_experiment",
        "exposureParams": "1:2:12345"
      }
    ]
  }
}

Расшифровка ответа:

Параметр	Тип	Описание
`label`	`string`	Группа, в которую попал пользователь.
`experimentLabel`	`string`	Лейбл эксперимента, который задается при создании в Trisigma.
`exposureParams`	`string`	Внутренний параметр. Будет удален из ответа в будущих версиях.

Алгоритм работы

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

Обратите внимание: В случае, когда конфигурация эксперимента требует проверки какого-то параметра пользователя (см Условия попадания в эксперимент), которого нет в запросе, эксперимент не попадёт в ответ метода. Ошибка возвращена не будет
Сохранение информации о запросе фичи пользователя для аналитики.
Формирование ответа

Общие рекомендации

Убедитесь, что в заголовке запроса используется актуальный Bearer токен, выданный вам командой Trisigma.
Передавайте максимум возможной информации о пользователе, чтобы гарантировать прохождение всех фильтров эксперимента.
При формировании запроса на получение фичей, в параметре tag укажите значение, связанное с конкретным сервисом или страницей, для которых вы хотите получить данные.
Кеширование ответа. Для оптимизации скорости ответа вашего сервиса рекомендуется запрашивать у сплиттера участие пользователя в эксперименте только один раз за сессию. Такой подход используется, например, в мобильных приложениях. Группы скачиваются редко, что позволяет экономить трафик, так как они изменяются нечасто.
Точка запроса. Старт приложения или начало сессии. хорошая точка, чтобы получить весь список текущих экспериментов и фичей.

Вы также можете прочитать про SLA сплиттера здесь.

Регистрация участия пользователя (`exposeManyV2`)

Метод exposeManyV2 фиксирует факт показа фичи пользователю в рамках эксперимента. Отправка этих событий (exposures) необходима для последующего анализа данных и формирования отчетов.

Параметры запроса

Параметр	Тип	Описание	Обязательный
`exposures`	`array`	Массив объектов, описывающих события показа фичи пользователю.	Да

Структура объекта в массиве exposures:

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

Параметр	Тип	Описание	Обязательный
`experimentLabel`	`string`	Лейбл эксперимента, к которому относится событие.	Да
`platform.id`	`int`	ID платформы, на которой произошло событие.	Да
`platform.version`	`string`	Версия платформы (например, приложения) в момент события.	Да
`participant.userId`	`int`	ID пользователя. Хотя бы один из идентификаторов (`userId` или `visitorId`) должен быть передан.	Условно
`participant.visitorId`	`string`	ID устройства или анонимного посетителя. Хотя бы один из идентификаторов (`userId` или `visitorId`) должен быть передан.	Условно
`randomizationUnits`	`list`		Нет
`randomizationUnits.type`	`string`	Тип параметра пользователя
`randomizationUnits.value`	`string`	Значение параметра пользователя

Формирование запроса

URL:

POST https://<host>/exposeManyV2/

Заголовки:

Authorization: Bearer <ваш_токен>
Content-Type: application/json
X-Source: local

Тело запроса:

{
  "exposures": [
    {
      "experimentLabel": "new_checkout_flow_2023",
      "platform": {
        "id": 1,
        "version": "2.5.1"
      },
      "participant": {
        "userId": 1234567,
        "visitorId": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8"
      },
      "randomizationUnits": [
        {
          "type": "phone_hash",
          "value": "33AFF380-6289-4B76-BB19-46EB8B7D8998"
        }
      ]
    },
    {
      "experimentLabel": "homepage_banner_test_Q4",
      "platform": {
        "id": 5,
        "version": "4.12.0"
      },
      "participant": {
        "userId": 9876543,
        "visitorId": "z9y8x7w6-v5u4-t321-s9r8-q7p6o5n4m3l2"
      }
    }
  ]
}

Пример успешного ответа

{
  "result": {
    "ok": true
  }
}

Алгоритм работы

Метод всегда и сразу возвращает ok = True. Дальнейшая обработка идёт параллельно, чтобы не блокировать клиента
Для каждого события из пачки: 1. По данным клиента и лейблу эксперимента вычисляется группа пользователя 2. Если группа вычислена, то сохраняются данные для построения отчета

Обратите внимание: При обработке экспоужера происходит повторное вычисление группы. Т.е. если в эксперименте были заданы "условия попадания в эксперимент", то в при отправке экспоужера обязательно должны быть указаны те же самые значения platform, participant и randomizationUnits, которые использовались при вычислении группы. Иначе событие не будет отправлено.

Общие рекомендации

Данные клиента. Требуется передавать в событиях экспоуза те же параметры platform, participant, randomizationUnits, которые передавались при вычислении фичи в ручке GetFeaturesByTag. Это позволит избежать потери данных при повторной проверке участия.
Время отправки. НЕ рекомендуется отправлять событие сразу после получения фичей от сплиттера. Лучшая практика. отправлять его в тот момент, когда пользователь непосредственно взаимодействует с экспериментальной фичей. Это обеспечивает точность данных в отчетах.
Пакетная отправка (батчинг). События можно и нужно накапливать и отправлять пакетами (батчами) для снижения нагрузки. Рекомендуется отправлять накопленные события не реже одного раза в сутки. Один запрос может содержать до 2000 событий.

Обработка ошибок

Статусы ответа:

400 Bad Request. в случае некорректных данных в теле запроса.
500 Internal Server Error. в случае серверной ошибки.

В случае ошибки тело ответа будет содержать JSON следующего вида:

{
  "error": {
    "kind": "<error_kind>",
    "message": "<error_message>"
  }
}

kind. тип ошибки, повторяющий логику HTTP-статусов.
message. текстовое описание ошибки.

Примеры распространенных ошибок:

Статус	Сообщение	Пояснение и действия
400	`"decode input DTO: Decode: field 'tag' is required..."`	Ошибка валидации. Обязательный параметр `tag` не был передан. Решение: Убедитесь, что в теле запроса указан параметр `tag`.
400	`"decode input DTO: Decode: field 'id' is required..."`	Ошибка валидации. В объекте `platform` отсутствует обязательный параметр `id`. Решение: Добавьте в объект `platform` параметр `id`.
400	`"bad request: все возможные параметры сплитования не заполнены"`	Ошибка валидации. Не передан ни один идентификатор пользователя. Решение: Убедитесь, что в объекте `participant` передан хотя бы один из параметров: `userId` или `visitorId`.

Ключевые понятия: `tag` и `experimentLabel`

При работе со сплиттером Trisigma используются два понятия: Тег и Лейбл. Понимание их назначения и разницы между ними является важной частью эффективной интеграции.

Что такое `tag`?

tag. это средство группировки экспериментов. Он позволяет ограничить набор экспериментов, которые возвращаются для конкретного сервиса, страницы или компонента. Тег задается при создании эксперимента в интерфейсе Trisigma.

Назначение тегов:

Группировка по сервисам. Каждый сервис может использовать свой уникальный тег для получения только релевантных ему экспериментов.
Оптимизация запросов. Вместо получения всех активных экспериментов сервис запрашивает данные только по нужному тегу.
Гибкое управление. Теги позволяют легко подключать новые эксперименты к разным сервисам без изменения их кода.

Пример:

Карточка товара (PDP): использует тег product_page.

Сервис рекомендаций: использует тег recommendations.

Эксперименты распределены следующим образом:

Эксперимент A связан с тегами product_page и recommendations.
Эксперимент B связан только с тегом product_page.

При запросе сервиса рекомендаций с тегом recommendations, он получит только эксперимент A.

Что такое `experimentLabel`?

experimentLabel. это уникальный идентификатор (имя) конкретного эксперимента. Он используется для того, чтобы ваш код мог определить, какой именно эксперимент активен для пользователя, и отобразить соответствующую фичу.

Назначение лейблов:

Управление функциональностью. Лейблы позволяют управлять логикой в коде: if (experimentLabel === 'new_blue_button') { ... }.
Тестирование и отчетность. Лейблы помогают точно отслеживать, в каком эксперименте участвует пользователь, и собирать данные для аналитики.

Пример:

Эксперимент A с лейблом test_banner тестирует новый баннер. Сервис, получив этот лейбл, включает баннер для пользователей в тестовой группе.

Ключевые различия между `tag` и `experimentLabel`

Характеристика	`tag`	`experimentLabel`
Назначение	Группировка экспериментов	Уникальный идентификатор эксперимента
Применение	Фильтрация списка экспериментов при запросе	Управление логикой в коде
Уникальность	Может быть одинаковым для нескольких экспериментов	Уникален в рамках системы
Пример	`product_page`, `recommendations`	`blue_button_2024`, `test_banner_Q1`

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

Сводная таблица параметров

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

Параметр	Тип	Описание	Обязательный	Используется в методах
`tag`	`string`	Тэг эксперимента для группировки и фильтрации.	Да	`getFeaturesByTag`
`experimentLabel`	`string`	Лейбл эксперимента для идентификации.	Да	`exposeManyV2`
`label`	`string`	Лейбл фичи (группа, в которую попал пользователь).	Нет	В ответе `getFeaturesByTag`
`platform.id`	`int`	ID платформы, идентифицирует устройство или среду.	Да	`getFeaturesByTag`, `exposeManyV2`
`platform.version`	`string`	Версия платформы (например, версия приложения).	Да	`getFeaturesByTag`, `exposeManyV2`
`participant.userId`	`int`	ID пользователя.	Условно*	`getFeaturesByTag`, `exposeManyV2`
`participant.visitorId`	`string`	ID устройства или анонимного посетителя (кука).	Условно*	`getFeaturesByTag`, `exposeManyV2`
`randomizationUnits`	`list`		Нет	`getFeaturesByTag`, `exposeManyV2`
`randomizationUnits.type`	`string`	Тип параметра пользователя		`getFeaturesByTag`, `exposeManyV2`
`randomizationUnits.value`	`string`	Значение параметра пользователя		`getFeaturesByTag`, `exposeManyV2`

Справочник идентификаторов

Маппинг платформ (`platform`)

Платформа	ID
`Desktop`	`1`
`iOS`	`4`
`Android`	`5`
`Mobile` (мобильный веб)	`6`

Методы API​

Получение списка фичей (getFeaturesByTag)​

Параметры запроса​

Формирование запроса​

Пример успешного ответа​

Алгоритм работы​

Общие рекомендации​

Регистрация участия пользователя (exposeManyV2)​

Параметры запроса​

Формирование запроса​

Пример успешного ответа​

Алгоритм работы​

Общие рекомендации​

Обработка ошибок​

Ключевые понятия: tag и experimentLabel​

Что такое tag?​

Что такое experimentLabel?​

Ключевые различия между tag и experimentLabel​

Сводная таблица параметров​

Справочник идентификаторов​

Маппинг платформ (platform)​

Методы API

Получение списка фичей (`getFeaturesByTag`)

Параметры запроса

Формирование запроса

Пример успешного ответа

Алгоритм работы

Общие рекомендации

Регистрация участия пользователя (`exposeManyV2`)

Параметры запроса

Формирование запроса

Пример успешного ответа

Алгоритм работы

Общие рекомендации

Обработка ошибок

Ключевые понятия: `tag` и `experimentLabel`

Что такое `tag`?

Что такое `experimentLabel`?

Ключевые различия между `tag` и `experimentLabel`

Сводная таблица параметров

Справочник идентификаторов

Маппинг платформ (`platform`)