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

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

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

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

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

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

Обратите внимание, что "/" в конце адреса запроса не баг - а фича. Он действительно нужен!

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

Методы API#

Получение списка экспериментов `getFeaturesByTag`#

Метод getFeaturesByTag используется для получения списка фичей, связанных с заданным тегом. Этот метод возвращает информацию об экспериментах, в которых находится участник.

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

Параметр	Тип	Описание	Обязательный
tag	`string`	Тэг эксперимента, используемый для группировки экспериментов.	Да
platform	`string`	Фильтр по платформе, помогает уточнить данные для пользователя в зависимости от его устройства.	Да
participant	`string`	Данные о пользователе для определения группы в эксперименте, такие как ID пользователя или ID устройства.	Да

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

URL:

POST https://<host>/getFeaturesByTag/

Заголовок:

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

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

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

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

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

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

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

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

Убедитесь, что в заголовке запроса используется актуальный Bearer токен, выданный вам командой Trisigma.

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

Для оптимизации скорости ответа вашего ПО/cервиса рекомендуется запрашивать у сплиттера участие пользователя в эксперименте только один раз на каждую сессию пользователя.

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

Старт приложения хорошая точка, чтобы получить весь список текущих экспериментов и фичей.

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

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

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

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

Параметр	Тип	Описание
`exposures`	`array`	Список экспоужеров

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

URL:

POST https://<host>/exposeManyV2/

Заголовок:

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

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

{
    "exposures": [
        {
            "experimentLabel": "<ваш_эксперимент>",
            "platform": {
                "id": 1
            },
            "participant": {
                "userId": 123456
            }
        }
    ]
}

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

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

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

Убедитесь, что в заголовке запроса используется актуальный Bearer токен, выданный вам командой Trisigma.

Вы также можете отправлять события батчами по 2000 событий за 1 экспоужер ивент.

Пример тела запроса с несколькими событиями:

{
    "exposures": [
        {
            "experimentLabel": "XXL110",
            "platform": {
                "id": 0
            },
            "participant": {
                "userId": 1234567
            }
        },
        {
            "experimentLabel": "001LLX",
            "platform": {
                "id": 0
            },
            "participant": {
                "userId": 19876543
            }
        },
        //...etc
    ]
}

Мы не рекомендуем делать экспоузы сразу по получении фичей от сплиттера.

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

Экспоузы можно и нужно собирать в батчи без повторений и отправлять не реже раза в сутки.

Ошибки#

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

400 в случае некорректных данных в теле запроса
500 в случае серверной ошибки

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

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

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

error_kind - тип ошибки, повторяющий логику HTTP статусов

error_message - описание ошибки

Некоторые возможные ошибки:

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

`tag` и `experimentLabel`#

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

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

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

Он заполняется при создании эксперимента в самом UI создания эксперимента Trisigma.

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

Применение Тегов:

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

Пример:

Допустим, есть два сервиса: - Карточка товара (PDP): использует тег product_page.
- Сервис рекомендаций: использует тег recommendations.

Эксперименты распределены следующим образом: - Эксперимент A связан с тегами product_page и recommendations.
- Эксперимент B связан только с тегом product_page.

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

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

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

Применение Лейблов:

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

Пример:

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

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

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

Как использовать `tag` и `experimentLabel` вместе#

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

Параметры#

Parameter	Type	Description	Обязательный параметр	Используется в методах
`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`

Маппинг параметров#

`platform`#

Platform	ID
`Desktop`	`1`
`iOS`	`4`
`Android`	`5`
`Mobile`	`6`

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

Методы API#

Получение списка экспериментов getFeaturesByTag#

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

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

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

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

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

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

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

Ошибки#

tag и experimentLabel#

Что такое tag?#

Что такое experimentLabel?#

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

Как использовать tag и experimentLabel вместе#

Параметры#

Маппинг параметров#

platform#

Получение списка экспериментов `getFeaturesByTag`#

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

`tag` и `experimentLabel`#

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

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

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

Как использовать `tag` и `experimentLabel` вместе#

`platform`#