Перейти к основному содержимому

Интеграция Switchback-тестов по API

Switchback-тестирование — это метод рандомизации экспериментов по времени и локации, используемый в условиях высокой связности данных (сетевых эффектов). В отличие от классического A/B-тестирования, где объектом распределения является пользователь, в Switchback-тестах объектом рандомизации выступает временной интервал в конкретном географическом регионе. Подробнее - "Switchback-эксперименты".

Типичный сценарий применения — тестирование алгоритмов распределения ограниченного ресурса (supply) в слабо-зависимых регионах (кластерах). В этом разделе мы разберем интеграцию на примере сервиса диспетчеризации заказов.

Архитектурный ландшафт интеграции​

Ландшафт Switchback

Интеграция. How-to.​

1. Настройка семантического слоя​

Настройте тип участника. В Switchback-экспериментах это географическая единица, например, geo_region. При конфигурации установите параметр assignments_source_enabled в значение false, чтобы отключить поиск в таблицах трафика. События связываются с группой через колонку dtm (время события).

# context_params.yaml
context_params:
  - label: geo_region
    domain: Trisigma
    type: str
    title: Geo Region
    status: active
    splitter_allocation_param: geo_region_string
    assignments_source_enabled: false
# participant_types.yaml
participant_types:
  - context_param: geo_region
    allowed_experiment_types:
      - switchback

Подробнее про настройку типов участников можно узнать в разделе "Настройка разметки трафика".

В качестве источника событий используйте таблицу dwh.delivery_events. Колонка dtm фиксирует время события и позволяет системе сопоставить его с тестовой или контрольной группой, активной в регионе в этот момент. Также укажите колонку атрибуции к бакету (типу участника).

# sources.yaml
delivery_events:
  ...
  participant: { geo_region: geo_region_string, user: user_id }
  primary_subject: user
  dtm: event_datetime
  ...

Также необходимо будет настроить метрики для отчета стандартным способом (см. "Настройка метрик")

2. Создание эксперимента​

Создайте списки с бакетами для рандомизации. При создании списков (подробнее в "Сегменты") в качестве типа участника следует выбирать geo_region. Техническое ограничение: размер одного списка — до 1 000 000 записей.

После подготовки сегментов выполняется стандартная процедура создания эксперимента в интерфейсе (см. "Switchback-эксперименты".).

3. Получение switchback-назначений для групп​

Сервис delivery-dispatcher запрашивает актуальную группу для региона через метод /api/getSwitchbackAssignments. Метод возвращает список назначений с фильтрацией по ID экспериментов, бакетам и времени.

API предназначен для получения списка назначений (assignments) switchback-экспериментов. Позволяет фильтровать по ID экспериментов, bucket ID и времени актуальности назначения, с поддержкой пагинации.

Аутентификация

Требуется аутентификация по сервисному токену. Токен выдает команда Trisigma.

Тело запроса (Request Body)

POST https://client.trisigma.io/api/getSwitchbackAssignments

Content-Type: application/json

{
  "apiKey": "someVerySecureTokenGivenByTrisigmaTeam",
  "bucketIds": ["h1", "h2", "h3"],
  "experimentIds": [1, 2, 3],
  "page": 1,
  "pageLimit": 50,
  "validAt": "2025-11-26T12:00:00+05:00"
}

Поля:

  • bucketIds (array of strings, опционально): Список ID бакетов для фильтрации
  • experimentIds (array of integers, опционально): Список ID экспериментов для фильтрации
  • page (integer > 0, опционально): Номер страницы (начиная с 1)
  • pageLimit (integer > 0, опционально): Количество элементов на странице
  • validAt (string в формате date-time, опционально): Время валидности назначений в часовом поясе +05:00. Если не указано, используется текущее время.

Ответ (Response)

200 OK

Content-Type: application/json

{
  "result": {
    "items": [
      {
        "bucketId": "h1",
        "experimentId": 1,
        "experimentLabel": "experiment_1",
        "feature": "feature_a",
        "timezone": "Europe/Moscow",
        "windowEnd": "2025-11-26T15:00:00+05:00",
        "windowStart": "2025-11-26T12:00:00+05:00"
      },
      {
        "bucketId": "h2",
        "experimentId": 2,
        "experimentLabel": "experiment_2",
        "feature": "feature_b",
        "timezone": "Europe/Moscow",
        "windowEnd": "2025-11-26T16:00:00+05:00",
        "windowStart": "2025-11-26T13:00:00+05:00"
      }
    ],
    "total": 100
  }
}

Поля ответа:

  • result (объект, обязательно): Контейнер с результатами
  • items (array of SwitchbackAssignmentDTO, обязательно): Список назначений
  • bucketId (string, обязательно): ID бакета
  • experimentId (integer, обязательно): ID эксперимента
  • experimentLabel (string, обязательно): Метка эксперимента
  • feature (string, обязательно): Название фичи
  • timezone (string, обязательно): Часовой пояс
  • windowEnd (string в формате date-time, обязательно): Конец временного окна в часовом поясе +05:00
  • windowStart (string в формате date-time, обязательно): Начало временного окна в часовом поясе +05:00
  • total (integer >= 0, обязательно): Общее количество элементов (без учета пагинации)

Примеры запросов

Пример 1: Получение всех назначений без фильтров

curl -X POST "https://client.trisigma.io/api/getSwitchbackAssignments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-oauth-token>" \
  -d '{"apiKey": "someVerySecureTokenGivenByTrisigmaTeam"}'

Пример 2: Фильтрация по экспериментам с пагинацией

curl -X POST "https://client.trisigma.io/api/getSwitchbackAssignments" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "someVerySecureTokenGivenByTrisigmaTeam",
    "experimentIds": [1, 2],
    "page": 1,
    "pageLimit": 10
  }'

Пример 3: Фильтрация по бакетам и времени

curl -X POST "https://client.trisigma.io/api/getSwitchbackAssignments" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "someVerySecureTokenGivenByTrisigmaTeam",
    "bucketIds": ["h3:akytjuhfwjkahtdjkauh", "h3:alkujdgwlkajdg"],
    "validAt": "2025-11-26T12:00:00+05:00"
  }'

Возможные ошибки

  • 401 Unauthorized: Отсутствует или некорректная аутентификация
  • 400 Bad Request: Некорректные параметры запроса
  • 500 Internal Server Error: Внутренняя ошибка сервера

Особенности

  • Если параметры пагинации не указаны, возвращаются все подходящие элементы
  • Параметр validAt влияет на фильтрацию назначений по времени их действия
  • Все временные поля возвращаются в формате ISO 8601 с указанием часового пояса.

4. Наполнение источника dwh.delivery_events​

Сервис delivery-dispatcher использует информацию о назначениях групп для выбора алгоритма на основе того, в каком регионе он применяется. Также, он отправляет события в dwh.delivery_events c обязательным указанием geo_region_id и времени, чтобы при вычислении отчета событие можно было соотнести с актуальным состоянием назначений групп в тот момент времени.

5. Вычисление отчета​

На основании настроек семантического слоя, событий в dwh.delivery_events и информации о распределениях групп в бакетах, Trisigma каждые сутки вычисляет отчет на основе событий за прошедшие 24 часа.

FAQ​

В чем главное отличие Switchback-теста от классического A/B-тестирования?​

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

Что выступает в качестве «участника» в таких экспериментах?​

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

Почему при настройке типа участника нужно отключать assignments_source_enabled?​

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

Существуют ли технические ограничения на размер сегментов?​

Да, размер одного списка с бакетами для рандомизации не должен превышать 1 000 000 записей. Если данных больше, используйте несколько списков в рамках одного эксперимента.

Как система сопоставляет событие с тестовой или контрольной группой?​

Для корректной атрибуции используются два параметра из таблицы событий (например, dwh.delivery_events): географический идентификатор и метка времени dtm. Поскольку локация переключается между группами через интервалы времени, метка dtm позволяет определить, какая группа была активна в момент события.

Как фиксируются экспоужеры в Switchback-тестах?​

Интеграция со сплиттером не предусмотрена, а система не записывает данные об экспоужерах автоматически; система создает только назначения (assignments) в фоновом режиме. По умолчанию можно считать, что switchback - это эксперимент, где событие exposure для бакета (участника) "уже произошло".

Что делать, если метод /api/getSwitchbackAssignments недоступен или отдает пустой ответ?​

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

Какой срок жизни (TTL) у назначений для получения по API?​

Время жизни данных о назначениях, возвращаемых API в системе ограничено и составляет 3 суток. В DWH для вычисления отчета данные сохраняются бессрочно в рамках общих лимитов на глубину хранения данных.

Можно ли получить назначения на будущие периоды?​

В системе существует параметр SWITCHBACK_ASSIGNMENTS_LEAD_TIME, обозначающий, насколько заранее будут вычисляться назначения групп. Например, при lead time равном 15 минутам, назначения будут готовы на 15 минут вперед, но не более того. Параметр системный и не изменяется между экспериментами.

Когда вступают в силу изменения размера окна?​

Новые настройки размера временного окна применяются только после завершения текущего активного окна. Например, если вы поменяли размер окна с часа до 15 минут, то изменения вступят в силу только тогда, когда закончится текущее часовое окно.

В каких случаях пересчитывается Switchback-отчет?​

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