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-адрес пользователя.