SigmaSDK - iOS

Sigma - это платформа для экспериментов, которая позволяет вам быстро оценивать влияние новых функций и предлагать продукты, которые нравятся вашим клиентам.

Требования

iOS 11+

Установка SDK

Cocoapods

Если ваш проект использует Cocoapods, добавьте зависимость SigmaSDK в Podfile:

use_frameworks!
target 'MyApp' do
    pod 'SigmaSDK', '~> X.Y.Z'
    # ...
end

Swift Package Manager

Если ваш проект использует Swift Package Manager, добавьте пакет SigmaSDK через Xcode:

File > Add Package > Search or Enter Package URL > https://github.com/expfdev/sigma_ios

Или вручную в файле Package.swift:

dependencies: [
    .package(url: "https://github.com/expfdev/sigma_ios"),
],
targets: [
    .target(name: "MyApp", dependencies: ["SigmaSDK"])
],

Работа с SDK

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

Для работы с SDK необходимо создать объект типа SigmaUser. Он хранит информацию о пользователе, такую как его уникальный идентификатор.

Пример создания объекта SigmaUser:

import SigmaSDK

let user = SigmaUser.Builder()
    .setUserId("123")
    .setCustomProperty(true, key: "isAuthorized")
    .setEmail("user123@expf.ru")
    .build()

SigmaUser.Builder обладает следующими методами:

func setUserId(_ id: String) -> SigmaUser.Builder - назначение ID анонимного пользователя. Используется для раздачи экспериментов и фича-флагов. (если не назначен, то не будет работать сплит экспериментов по userId).
func setProfileId(_ id: String) -> SigmaUser.Builder - назначение ID авторизованного пользователя (например, в личном кабинете). (если не назначен, то не будет работать сплит экспериментов по profileId).
func setDeviceId(_ id: String) -> SigmaUser.Builder - переопределение Device ID, определенного SDK.
func setEmail(_ email: String) -> SigmaUser.Builder - назначение параметра пользователя с названием email.
func setAppVersion(_ version: String) -> SigmaUser.Builder - переопределение версии приложения, определенной SDK.
func setOsName(_ name: String) -> SigmaUser.Builder - переопределение названия операционной системы, определенной SDK.
func setOsVersion(_ version: String) -> SigmaUser.Builder - переопределение версии операционной системы, определенной SDK.
func setGeoCode(_ code: String) -> SigmaUser.Builder - переопределение гео кода, определенного SDK.
func setGeoCountry(_ country: String) -> SigmaUser.Builder - переопределение страны, определенной SDK.
func setGeoState(_ state: String) -> SigmaUser.Builder - переопределение региона, определенного SDK.
func setGeoCity(_ code: String) -> SigmaUser.Builder - переопределение города, определенного SDK.
func setCustomProperty<Value: CustomStringConvertible>(_ value: Value, key: String) -> SigmaUser.Builder - назначение custom-параметра пользователя (все названия таких параметров имеют префикс custom.).

После создания объекта SigmaUser, необходимо вызывать метод инициализации SDK:

import SigmaSDK

do {
    let client = try Sigma.initializeClient(projectToken: token, initialUser: user)
} catch let error {
    // Handle error
}

Метод initializeClient обладает следующими параметрами:

projectToken: String - токен проекта (указан в панели управления).
initialUser: SigmaUser? - Объект SigmaUser. Необязательный параметр. При отсутствии, SDK автоматически создаст объект SigmaUser, сгенерировав ему случайный идентификатор.
cacheTTL: UInt - частота (в секундах) запрашивания конфигурации из сети. Необязательный параметр. По умолчанию равен 10 секундам.
retryCount: UInt - количество повторных попыток запрашивания конфигурации при неудачном запросе. Необязательный параметр. По умолчанию равен 3.
tag: String - тег клиента Sigma. Необязательный параметр. По умолчанию равен "default". Необходим для создания нескольких экземпляров SigmaClient.

Для получения клиента SigmaClient используется метод Sigma.getClient(tag: String). Для завершения работы над клиентом используется метод Sigma.removeClient(tag: String)

При инициализации уже инициализированного клиента (с уже существующим тегом) будет выброшена ошибка SigmaError.initializationOfExistingClient.

Получение значений Feature Flag

Для получения значений Feature Flag используются следующие методы SigmaClient:

func checkFlag<T: SigmaPropertyType>(flagName: String, onSuccess: SigmaSuccessCallback<T?>?, onError: SigmaErrorCallback?)
func checkFlag<T: SigmaPropertyType>(flagName: String) async throws -> T?

Значение FeatureFlag может быть типа Bool, Int, Double, String или [String: Any].

Пример получения значений Feature Flag:

import SigmaSDK

guard let client = Sigma.getClient() else { return }

// Callback версия
client.checkFlag(
    flagName: "my_first_flag",
    onSuccess: { (value: Bool?) in
        // Обработка значения Feature Flag
    },
    onError: { error in
        // Обработка ошибки
    }
)

// Async-await версия
do {
    let firstFlag: Bool? = try await client.checkFlag(flagName: "my_first_flag")
    // Обработка значения Feature Flag
} catch let error {
    // Обработка ошибки
}

Несмотря на то, что методы получения Feature Flag выбрасывают ошибки, даже при отсутствии ошибок значение флага может быть nil. Эта ситуация может возникнуть, например, в случае, если флаг привязан к эксперименту, в который пользователь не попал. Эта ситуация не ошибочная: ожидаемо, что для данного пользователя значение Feature Flag недоступно, поэтому SDK возвращает nil.

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

Для получения всех экспериментов, в которые попал пользователь, используются следующие методы SigmaClient:

func getAllUserExperiments(onSuccess: SigmaSuccessCallback<[SigmaExperiment]>?, onError: SigmaErrorCallback?)
func getAllUserExperiments() async throws -> [SigmaExperiment]

Для получения эксперимента по названию, используются следующие методы SigmaClient:

func getExperiment(name: String, onSuccess: SigmaSuccessCallback<SigmaExperiment?>?, onError: SigmaErrorCallback?)
func getExperiment(name: String) async throws -> SigmaExperiment?

Все вышеописанные методы возвращают только те эксперименты, в которые попал пользователь.

Примеры получения экспериментов:

import SigmaSDK

guard let client = Sigma.getClient() else { return }
let flagName = "my_first_flag"

// Callback версии
client.getAllUserExperiments(
    onSuccess: { experiments in
        // Обработка всех экспериментов, в которые попал пользователь
    },
    onError: { error in
        // Обработка ошибки
    }
)

client.getExperiment(
    name: "my_first_experiment",
    onSuccess: { experiment in
        // Обработка эксперимента
    },
    onError: { error in
        // Обработка ошибки
    }
)

// Async-await версии
do {
    let allExperiments = try await client.getAllUserExperiments()
    // Обработка всех экспериментов, в которые попал пользователь
} catch let error {
    // Обработка ошибки
}

do {
    let userExperiment = try await client.getExperiment(name: "my_first_experiment")
    // Обработка эксперимента
} catch let error {
    // Обработка ошибки
}

Получение информации из эксперимента

После получения эксперимента, информация об эксперименте доступна из методов объекта SigmaExperiment:

func getParamValue<T: SigmaPropertyType>(name: String) -> T?
func getFeatureFlagValue<T: SigmaPropertyType>(flagName: String) throws -> T?

Значение FeatureFlag или параметра эксперимента может быть типа Bool, Int, Double, String или [String: Any].

Список параметров, автоматически определяющихся на стороне SDK:

appVersion - версия приложения пользователя.
deviceId - уникальный идентификатор устройства.
os.version - номер версии iOS на устройстве пользователя.
os.name - название операционной системы пользователя (iOS/macOS/watchOS/tvOS).
time - текущее время пользователя.
date - текущая дата пользователя.
geo.country - страна пользователя.
geo.state - район пользователя.
geo.city - город пользователя.
geo.ip - IP-адрес пользователя.

SigmaSDK - iOS

Установка SDK​

Cocoapods​

Swift Package Manager​

Работа с SDK​

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

Получение значений Feature Flag​

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

Получение информации из эксперимента​

Список параметров, автоматически определяющихся на стороне SDK:​