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

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

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

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

примечание

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

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

Методы API

warning

Поле participant - устаревший способ

Параметры пользователя передавайте через randomizationUnits - он поддерживает любые типы партисипантов: стандартные (user_id, visitor_id) и кастомные (например, storeid, kioskid, phone_hash).

Поле participant (userId/visitorId/passportId) устарело и оставлено для обратной совместимости. Удаление не планируется - существующие интеграции продолжат работать. В новых интеграциях используйте randomizationUnits.

value в randomizationUnits всегда передаётся строкой, даже для числовых типов. При переходе с participant: userId: 123456 (int) -> {"type": "user_id", "value": "123456"} (string).

Передача обоих полей одновременно ошибки не вызывает. Значения объединяются: при совпадении типа (например, user_id) побеждает randomizationUnits. Несовпадающие типы суммируются (см. подробнее ниже).

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

Метод getFeaturesByTag возвращает список фичей по заданному тегу.

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

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

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

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

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

Пустые и нулевые идентификаторы не дают ошибку, но ломают распределение

Если передать userId: 0, пустой visitorId: "" или пустой список randomizationUnits, Splitter не определит группу пользователя и вернёт пустой список фичей. При этом ошибки 400 может не быть - придёт 200 с пустым результатом.

Всегда передавайте хотя бы один ненулевой идентификатор.

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

Параметр	Тип	Обязательность	Пример	Описание
`tag`	`string`	Да	`"product_page"`	Тэг эксперимента, используемый для группировки.
`platform.id`	`int`	Да	`1`	ID платформы, идентифицирует устройство или среду.
`platform.version`	`string`	Нет	`"2.15.0"`	Версия платформы (например, версия приложения).
`randomizationUnits`	`list`	Условно	`[{"type": "user_id", "value": "12345"}]`	Параметры пользователя (рекомендуемый способ). Хотя бы один параметр должен быть передан.
`randomizationUnits.type`	`string`	Да	`"user_id"`	Тип параметра пользователя: `"user_id"`, `"visitor_id"`, кастомные типы.
`randomizationUnits.value`	`string`	Да	`"12345"`	Значение параметра пользователя. Всегда строка, даже для числовых типов.
`participant.userId`	`int`	Условно	`123456`	Устаревший. ID пользователя. Используйте `randomizationUnits` с `type: "user_id"`.
`participant.visitorId`	`string`	Условно	`"a1b2c3d4"`	Устаревший. ID устройства или анонимного посетителя. Используйте `randomizationUnits` с `type: "visitor_id"`.

к сведению

Одновременная передача participant и randomizationUnits

Оба поля можно передавать в одном запросе - ошибки не будет. Splitter объединяет их по следующим правилам:

При совпадении типа (например, user_id) значение из randomizationUnits имеет приоритет над participant.
При отсутствии пересечений типы суммируются: participant.userId + randomizationUnits: [{type: "phone_hash", ...}] дадут оба идентификатора.

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

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

URL:

POST https://<host>/getFeaturesByTag/

Заголовки:

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

Тело запроса (рекомендуемый способ - randomizationUnits):

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

Тело запроса (устаревший способ - participant, оставлен для совместимости)

{
  "tag": "<ваш_тег>",
  "platform": {
    "id": 1,
    "version": "2.15.0"
  },
  "participant": {
    "userId": 123456
  }
}

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

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

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

Параметр	Тип	Пример	Описание
`label`	`string`	`"test_group"`	Группа, в которую попал пользователь.
`experimentLabel`	`string`	`"demo_experiment"`	Лейбл эксперимента, который задается при создании в Trisigma.
`exposureParams`	`string`	`"1:2:12345"`	Внутренний параметр. Устарел, запланирован к удалению.

SLA Splitter описан здесь.

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

Метод exposeManyV2 фиксирует факт показа фичи пользователю в рамках эксперимента (exposure). Без этих событий пользователи не попадают в отчёт - аналитика по эксперименту не строится.

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

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

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

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

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

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

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

Параметр	Тип	Обязательность	Пример	Описание
`experimentLabel`	`string`	Да	`"demo_experiment"`	Лейбл эксперимента, к которому относится событие.
`platform.id`	`int`	Да	`1`	ID платформы, на которой произошло событие.
`platform.version`	`string`	Нет	`"2.15.0"`	Версия платформы (например, приложения) в момент события.
`randomizationUnits`	`list`	Условно	`[{"type": "user_id", "value": "12345"}]`	Параметры пользователя (рекомендуемый способ). Должны совпадать с теми, что передавались в `getFeaturesByTag`.
`randomizationUnits.type`	`string`	Да	`"user_id"`	Тип параметра пользователя: `"user_id"`, `"visitor_id"`, кастомные типы.
`randomizationUnits.value`	`string`	Да	`"12345"`	Значение параметра пользователя. Всегда строка, даже для числовых типов.
`participant.userId`	`int`	Условно	`123456`	Устаревший. ID пользователя. Используйте `randomizationUnits` с `type: "user_id"`.
`participant.visitorId`	`string`	Условно	`"a1b2c3d4"`	Устаревший. ID устройства или анонимного посетителя. Используйте `randomizationUnits` с `type: "visitor_id"`.

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

URL:

POST https://<host>/exposeManyV2/

Заголовки:

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

Тело запроса (рекомендуемый способ - randomizationUnits):

{
  "exposures": [
    {
      "experimentLabel": "new_checkout_flow_2023",
      "platform": {
        "id": 1,
        "version": "2.5.1"
      },
      "randomizationUnits": [
        {
          "type": "user_id",
          "value": "1234567"
        },
        {
          "type": "visitor_id",
          "value": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8"
        },
        {
          "type": "phone_hash",
          "value": "33AFF380-6289-4B76-BB19-46EB8B7D8998"
        }
      ]
    }
  ]
}

Тело запроса (устаревший способ - participant, оставлен для совместимости)

{
  "exposures": [
    {
      "experimentLabel": "homepage_banner_test_Q4",
      "platform": {
        "id": 5,
        "version": "4.12.0"
      },
      "participant": {
        "userId": 9876543,
        "visitorId": "z9y8x7w6-v5u4-t321-s9r8-q7p6o5n4m3l2"
      }
    }
  ]
}

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

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

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

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

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: все возможные параметры сплитования не заполнены"`	Ошибка валидации. Не передан ни один идентификатор пользователя. Решение: Передайте хотя бы один параметр пользователя в `randomizationUnits` (например, `{"type": "user_id", "value": "12345"}`).

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

При работе со Splitter 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, сгруппированные по методам. «Условно» - в запросе обязателен хотя бы один идентификатор пользователя: randomizationUnits (рекомендуемый способ) или устаревший participant.

Параметры getFeaturesByTag

Параметр	Тип	Обязательность	Пример	Описание
`tag`	`string`	Да	`"product_page"`	Тэг эксперимента для группировки и фильтрации.
`platform.id`	`int`	Да	`1`	ID платформы, идентифицирует устройство или среду.
`platform.version`	`string`	Нет	`"2.15.0"`	Версия платформы (например, версия приложения).
`randomizationUnits`	`list`	Условно	`[{"type": "user_id", "value": "12345"}]`	Параметры пользователя (рекомендуемый способ).
`randomizationUnits.type`	`string`	Да	`"user_id"`	Тип параметра пользователя (`"user_id"`, `"visitor_id"`, кастомные).
`randomizationUnits.value`	`string`	Да	`"12345"`	Значение параметра (всегда строка, даже для числовых типов).
`participant.userId`	`int`	Условно	`123456`	Устаревший. ID пользователя. Используйте `randomizationUnits`.
`participant.visitorId`	`string`	Условно	`"a1b2c3d4"`	Устаревший. ID устройства/посетителя. Используйте `randomizationUnits`.

В ответе метод возвращает label (string) - лейбл фичи, группа, в которую попал пользователь.

Параметры exposeManyV2

Параметр	Тип	Обязательность	Пример	Описание
`experimentLabel`	`string`	Да	`"demo_experiment"`	Лейбл эксперимента для идентификации.
`platform.id`	`int`	Да	`1`	ID платформы, идентифицирует устройство или среду.
`platform.version`	`string`	Нет	`"2.15.0"`	Версия платформы (например, версия приложения).
`randomizationUnits`	`list`	Условно	`[{"type": "user_id", "value": "12345"}]`	Параметры пользователя (рекомендуемый способ). Должны совпадать с переданными в `getFeaturesByTag`.
`randomizationUnits.type`	`string`	Да	`"user_id"`	Тип параметра пользователя (`"user_id"`, `"visitor_id"`, кастомные).
`randomizationUnits.value`	`string`	Да	`"12345"`	Значение параметра (всегда строка, даже для числовых типов).
`participant.userId`	`int`	Условно	`123456`	Устаревший. ID пользователя. Используйте `randomizationUnits`.
`participant.visitorId`	`string`	Условно	`"a1b2c3d4"`	Устаревший. ID устройства/посетителя. Используйте `randomizationUnits`.

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

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

Методы API​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Что такое tag?​

Что такое experimentLabel?​

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

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

Параметры getFeaturesByTag​

Параметры exposeManyV2​

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

Методы API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Что такое tag?

Что такое experimentLabel?

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

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

Параметры getFeaturesByTag

Параметры exposeManyV2

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