iOS SDK

Установка

Добавьте iOS SDK версии 0.1.2 или новее через Swift Package Manager:

dependencies: [
    .package(
        url: "https://github.com/Trisigma-Official/ios-sdk",
        from: "0.1.2"
    ),
]

Подключите продукт TrisigmaSDK к target приложения. SDK поддерживает iOS 14.0+ и Swift 5.7+.

Quickstart

Инициализируйте SDK один раз, затем используйте созданный client в нужных сценариях.

Инициализация SDK

Передайте ключ проекта, тег, участника эксперимента и параметры подключения к Splitter.

import TrisigmaSDK

let participant = TrisigmaParticipant(userId: 42)
let options = TrisigmaOptions(
    host: "https://client.example.trisigma.io",
    platformVersion: "1.0.0"
)

let client = try await Trisigma.initialize(
    key: clientKey,
    tag: "app-name",
    participant: participant,
    options: options
)

initialize - async throws-метод, поэтому вызывайте его из асинхронного контекста и обработайте ошибку. Метод загружает конфигурацию экспериментов и запускает её фоновое обновление. Ошибка первой сетевой загрузки не блокирует запуск приложения: клиент использует кеш или значения по умолчанию.

Получение группы эксперимента

Получите назначенную группу и выберите соответствующий вариант интерфейса.

let group = client.checkFeature(
    label: "new_checkout_flow", // Лейбл эксперимента
    defaultGroup: "control"
)

switch group {
case "test":
    showNewCheckout()
default:
    showCurrentCheckout()
}

SDK возвращает defaultGroup, если не находит эксперимент или доступную конфигурацию.

Регистрация экспозиции

Зарегистрируйте экспозицию после того, как пользователь увидел экспериментальную функциональность.

client.logExposure(
    label: "new_checkout_flow" // Лейбл эксперимента
)

SDK сохраняет событие в локальную очередь и отправляет события пакетами. SDK отправляет очередь автоматически при достижении exposureQueueMaxSize или по истечении exposureFlushInterval. Перед завершением работы с клиентом вызовите shutdown(): метод пытается отправить оставшиеся экспозиции в пределах shutdownTimeout.

Регистрируйте exposure, когда пользователь дошёл до показа варианта и назначенный вариант начинает влиять на его опыт. Вызывайте logExposure симметрично для control и test, до действий и событий, зависящих от варианта. Не ставьте exposure в зависимость от клика, конверсии и т.д.: это искажает результаты эксперимента.

Типовые сценарии

Сценарий	Действие разработчика	Причина
Группа получена заранее, но пользователь не дошёл до экспериментальной функциональности	Не вызывать `logExposure`	SDK не может определить, увидел ли пользователь вариант, и добавляет событие в очередь при наличии назначения
Exposure вызывается только после клика, конверсии или другого действия пользователя	Не использовать такое действие как условие	SDK не распознаёт статистическую ошибку и добавляет событие в очередь при наличии назначения
Exposure вызывается только после успешного отображения фичи	Не ставить вызов в зависимость от успеха отображения	Асимметричный триггер отправки приводит к SRM

Отправка накопленных экспозиций

SDK сам отправляет экспозиции при переходе приложения в background. Вызовите flush(), если нужно дождаться отправки в другом сценарии.

let allEventsSent = await client.flush()
if !allEventsSent {
    logger.warning("Trisigma exposures were not sent")
}

Метод возвращает true, если очередь пуста или SDK отправил все события.

flush() отправляет только экспозиции, которые ранее попали в очередь через logExposure. Метод не регистрирует показ автоматически.

Ручное назначение группы

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

client.setOverride(
    label: "new_checkout_flow",
    group: "test"
)
defer {
    client.removeOverride(label: "new_checkout_flow")
}

let group = client.checkFeature(
    label: "new_checkout_flow",
    defaultGroup: "control"
)
renderCheckout(group)

Удаляйте override в defer или teardown, чтобы он не повлиял на следующие проверки.

Работа с SDK

Каждый публичный метод описан на отдельной странице:

Метод	Назначение
`Trisigma.initialize`	Инициализировать SDK и создать клиент.
`TrisigmaClient.checkFeature`	Получить группу эксперимента.
`TrisigmaClient.getVisitorId`	Получить фактический `visitorId`.
`TrisigmaClient.logExposure`	Зарегистрировать показ эксперимента.
`TrisigmaClient.clearCache`	Очистить дисковый кеш.
`TrisigmaClient.setOverride`	Задать локальную группу.
`TrisigmaClient.removeOverride`	Удалить один override.
`TrisigmaClient.removeAllOverrides`	Удалить все overrides.
`TrisigmaClient.getAllOverrides`	Получить все overrides.
`TrisigmaClient.flush`	Немедленно отправить накопленные экспозиции.
`TrisigmaClient.shutdown`	Завершить работу клиента.

Кеш конфигурации экспериментов

SDK поддерживает сохранение загруженного конфига экспериментов между запусками приложения в памяти устройства. Кеш включён по умолчанию. Не отключайте его в production.

Во время initialize SDK загружает непросроченный кеш, а затем запрашивает актуальный конфиг у Splitter. После успешного ответа SDK сохраняет новый конфиг и обновляет его с интервалом featuresRefreshInterval.

Если загрузка конфига завершилась ошибкой, SDK использует последнюю успешно загруженную версию.

Если кеш отключён через cacheEnabled или в кеше нет актуального конфига, checkFeature возвращает defaultGroup.

checkFeature ищет группу в следующем порядке:

Локальный override.
Последний конфиг в памяти, в том числе загруженный с диска или помеченный как устаревший после ошибки обновления.
defaultGroup.

cacheTTL определяет, как долго сохранённый конфиг считается актуальным. По умолчанию кеш хранится 86 400 секунд.

clearCache() удаляет сохранённый кеш текущего client, но не удаляет локальные overrides.

Lifecycle

iOS SDK сам обрабатывает переходы приложения между foreground и background. При UIApplication.didEnterBackgroundNotification и UIApplication.willTerminateNotification SDK останавливает обновление features и пытается отправить очередь в background task. При UIApplication.willEnterForegroundNotification SDK возобновляет обновление.

Вызовите shutdown(), когда client больше не нужен. Метод прекращает фоновые задачи и пытается отправить очередь событий экспозиции в пределах shutdownTimeout.

Установка​

Quickstart​

Инициализация SDK​

Получение группы эксперимента​

Регистрация экспозиции​

Типовые сценарии​

Отправка накопленных экспозиций​

Ручное назначение группы​

Работа с SDK​

Кеш конфигурации экспериментов​

Lifecycle​