Trisigma.initialize

static func initialize(
    key: String,
    tag: String,
    participant: TrisigmaParticipant,
    options: TrisigmaOptions
) async throws -> TrisigmaClientProtocol

Создаёт клиент Trisigma, загружает начальную конфигурацию экспериментов и запускает фоновые обновления. SDK разрешает использовать каждую пару host и tag один раз за время работы процесса. Значения participant.visitorId, включая nil, должны совпадать у всех клиентов процесса.

Параметры

Параметр	Тип	Обязательность	Пример	Описание
key	String	Да	"project-key"	Ключ авторизации Trisigma.
tag	String	Да	"checkout"	Тег для фильтрации конфигурации экспериментов. Например, тег ограничивает конфигурацию экспериментами вашего приложения.
participant	TrisigmaParticipant	Да	TrisigmaParticipant(userId: 42)	Участник эксперимента.
options	TrisigmaOptions	Да	TrisigmaOptions(host: ..., platformVersion: ...)	Адрес сервера, версия приложения, интервалы, кеш, очередь экспозиций и логирование.

TrisigmaParticipant

TrisigmaParticipant описывает участника эксперимента. Все поля структуры необязательны. Если visitorId равен nil, SDK создаёт стабильный UUID и сохраняет его между запусками приложения.

Параметр	Тип	Обязательность	По умолчанию	Пример	Описание
userId	Int?	Нет	nil	42	Стабильный идентификатор авторизованного пользователя.
visitorId	String?	Нет	nil	"device-7f3a"	Идентификатор анонимного пользователя. Если значение не задано, SDK создаёт его автоматически.
attributes	[String: String]	Нет	[:]	["city": "moscow"]	Атрибуты пользователя для фильтрации аудитории эксперимента.

TrisigmaOptions

TrisigmaOptions задаёт подключение к Splitter, кеширование, фоновые обновления, отправку экспозиций и логирование. host и platformVersion обязательны. Все числовые значения должны быть больше нуля и задаются в секундах, кроме exposureQueueMaxSize.

Параметр	Тип	Обязательность	По умолчанию	Пример	Описание
host	String	Да	-	"https://client.example.trisigma.io"	Базовый HTTPS URL Splitter.
platformVersion	String	Да	-	"1.0.0"	Версия приложения в формате semver.
sourceName	String?	Нет	nil	"checkout-app"	Значение заголовка X-Source. SDK использует CFBundleDisplayName, CFBundleName, bundle identifier или "Unknown", если значение не задано.
cacheEnabled	Bool	Нет	true	false	Включает сохранение конфигурации экспериментов на устройстве.
cacheTTL	Int	Нет	86400	43200	Срок актуальности сохранённой конфигурации экспериментов в секундах.
requestTimeout	Int	Нет	1	2	Тайм-аут сетевого запроса в секундах.
featuresRefreshInterval	Int	Нет	180	300	Интервал обновления конфигурации экспериментов в секундах.
exposureQueueMaxSize	Int	Нет	50	100	Количество экспозиций в очереди до автоматической отправки.
exposureFlushInterval	Int	Нет	30	60	Интервал автоматической отправки экспозиций в секундах.
shutdownTimeout	Int	Нет	5	10	Максимальное время выполнения flush() внутри shutdown() в секундах.
logLevel	LogLevel	Нет	.error	.debug	Минимальный уровень логирования: .none, .error, .warning или .debug.
logHandler	((LogLevel, String) -> Void)?	Нет	nil	handleTrisigmaLog	Пользовательский обработчик логов. При nil SDK использует os_log.

Возвращаемое значение

Тип	Описание
TrisigmaClientProtocol	Инициализированный клиент. При сетевой ошибке первой загрузки SDK возвращает клиент в режиме fail-open.

Клиент в режиме fail-open продолжает работать. Метод checkFeature использует кеш или возвращает defaultGroup, а SDK записывает ошибку в лог.

Ошибки

Ошибка	Когда возникает
Validation error	key или tag пустой; host не является HTTPS URL; platformVersion не соответствует semver; строковая или числовая опция не проходит проверку.
Validation error пары клиентов	SDK уже использовал эту пару host и tag в текущем процессе.
Validation error участника	Значение participant.visitorId, включая nil, отличается от других клиентов процесса.
Ошибка локального хранилища	SDK не может создать или прочитать хранилище событий экспозиции.
CancellationError	Задача инициализации отменена во время операции с локальным хранилищем.

SDK записывает сетевые и серверные ошибки первой загрузки в лог и не передаёт их в вызывающий код.

Использование

import TrisigmaSDK

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

do {
    let client = try await Trisigma.initialize(
        key: "project-key",
        tag: "checkout",
        participant: participant,
        options: options
    )
} catch {
    // Исправьте параметры и повторите инициализацию.
}

Для кода без Swift Concurrency используйте перегрузку с completion. SDK вызывает completion в главном потоке:

Trisigma.initialize(
    key: "project-key",
    tag: "checkout",
    participant: participant,
    options: options
) { result in
    switch result {
    case .success(let client):
        use(client)
    case .failure(let error):
        handle(error)
    }
}