SigmaSDK - Kotlin
Sigma - это платформа для экспериментов, которая позволяет вам быстро оценивать влияние новых функций и предлагать продукты, которые нравятся вашим клиентам.
Требования
- Android API level 21+
Настройка Gradle Scripts
В модуле вашего приложения (обычно app
) создайте папку с названием libs и поместите туда *.aar
файл который вы получили от команды Sigma.
В этом же модуле найдите файл Gradle (build.gradle
) и добавьте туда следущее.
dependencies {
...
//SigmaSDK
implementation fileTree(dir: "libs", include: ["*.aar"])
...
}
Инициализация SigmaSDK
Для инициализации SigmaSDK в классе, унаследованном от класса Application
, в теле переопределенного метода onCreate()
добавьте вызов статического метода Sigma.initializeClient()
.
Данный метод принимает следующие параметры:
- application - объект класса приложения.
- projectToken - токен проекта (указан в панели управления).
- initialUser - необязательный параметр, объект класса
SigmaUser
. - cacheTtlMillis - необязательный параметр, частота запрашивания конфига из сети (по умолчанию равен 60 секундам).
- retryCount - необязательный параметр, количество повторных попыток запрашивания конфига при неудачном запросе (по умолчанию равен 3).
- tag - необязательный параметр, тег клиента Sigma (по умолчанию равен 'default'). Необходим для создания нескольких инстансов SigmaClient.
Пример вызова метода:
import ru.expf.sigma.Sigma
...
Sigma.initializeClient(
application = this,
projectToken = projectToken,
initialUser = sigmaUser,
cacheTtlMillis = 20,
retryCount = 10,
)
Получение объекта SigmaClient
Чтобы получить инстанс SigmaClient используется статический метод Sigma.getClient()
.
Данный метод принимает следующие параметры:
- tag - необязательный параметр, тег клиента Sigma (по умолчанию равен 'default').
Приостановка работы клиента
Для того, чтобы приостановить запросы в сеть исполняющиеся SigmaSDK клиентом используется метод SigmaClient.shutdown()
.
Пример вызова метода:
import ru.expf.sigma.Sigma
...
val client = Sigma.getClient()
client.shutdown()
Продолжение работы SigmaSDK
Для того, чтобы продолжить запросы в сеть исполняющиеся SigmaSDK клиентом используется метод SigmaClient.start()
.
Пример вызова метода:
import ru.expf.sigma.Sigma
...
val client = Sigma.getClient()
client.start()
Завершение работы клиента
Для того, чтобы полностью завершить работу клиента используется статический метод Sigma.removeClient()
.
Данный метод принимает следующие параметры:
- tag - необязательный параметр, тег клиента Sigma (по умолчанию равен 'default').
Создание объекта класса SigmaUser
Объект SigmaUser
создается с помощью его подкласса SigmaUser.Builder
.
import ru.expf.sigma.SigmaUser
...
val builder = SigmaUser.Builder()
Данный подкласс обладает следующими методами:
setUserId()
- назначение идентификатора пользователя (если не назначен, то сгенерируется автоматически).
builder.setUserId("***")
setEmail()
- назначение параметра пользователя с названием e-mail.
builder.setEmail("***")
setCustomProperty()
- назначение custom-параметра пользователя (все названия таких параметров имеют префикс custom.). Данный метод принимает название и значения параметра и имеет 3 варианта использования:
builder.setCustomProperty("***" to "***")
builder.setCustomProperty { "***" to "***" }
builder.setCustomProperty("***", "***")
build()
- создание объектаSigmaUser
.
builder.build()
Назначение текущего пользователя
Для назначения пользователя используется метод SigmaClient.setUser()
.
Данный метод принимает следующие параметры:
- user - объект класса
SigmaUser
.
Пример вызова метода:
import ru.expf.sigma.Sigma
...
val client = Sigma.getClient()
client.setUser(user = sigmaUser)
Помимо этого назначить пользователя можно и при инициализации SigmaSDK (см. Инициализация SigmaSDK).
Получение значения Feature Flag
Для получения значения Feature Flag используется несколько статических методов: SigmaClient.checkFlagBoolean()
, SigmaClient.checkFlagLong()
, SigmaClient.checkFlagFloat()
, SigmaClient.checkFlagString()
.
Каждый из них принимает следующие параметры:
- name - название Feature Flag.
- callback - необязательный параметр при использовании suspend версии метода, объект интерфейса
SigmaCheckFlagCallback
реализующий его методыonSuccess()
иonError()
.
Примеры вызова метода:
*Без использования kotlin.coroutines*
import ru.expf.sigma.Sigma
import ru.expf.sigma.SigmaCheckFlagCallback
...
val client = Sigma.getClient()
client.checkFlagString(
name = "***",
callback = object : SigmaCheckFlagCallback<String> {
override fun onSuccess(value: String?) {
/** Some code with received value */
}
override fun onError(throwable: Throwable) {
/** Some code with received error */
}
}
)
*С использованием kotlin.coroutines*
import ru.expf.sigma.Sigma
...
async {
val client = Sigma.getClient()
val flagValue = client.checkFlagString(name = "***")
}.await()
Стоит обратить внимание на то, что в случае несоответсвия ни одному условию в правилах результат работы метода будет равен null.
Получение эксперимента
Для получения эксперимента используется метод SigmaClient.getExperiment()
.
Данный метод принимает следующие параметры:
- id - идентификатор эксперимента.
- callback - необязательный параметр при использовании suspend версии метода, объект интерфейса
SigmaGetExperimentCallback
реализующий его методыonSuccess()
иonError()
.
Примеры вызова метода:
*Без использования kotlin.coroutines*
import ru.expf.sigma.Sigma
import ru.expf.sigma.SigmaExperiment
import ru.expf.sigma.SigmaGetExperimentCallback
...
val client = Sigma.getClient()
client.getExperiment(
id = "***",
callback = object : SigmaGetExperimentCallback {
override fun onSuccess(experiment: SigmaExperiment?) {
/** Some code with received experiment */
}
override fun onError(throwable: Throwable) {
/** Some code with received error */
}
}
)
*С использованием kotlin.coroutines*
import ru.expf.sigma.Sigma
import ru.expf.sigma.SigmaExperiment
...
async {
val client = Sigma.getClient()
val experiment = client.getExperiment(id = "***")
}.await()
Стоит обратить внимание на то, что в случае непопадания пользователем в эксперимент результат работы метода будет равен null.
Данный метод возвращает объект интерфейса SigmaExperiment
, который имеет следующие методы:
getExperimentId()
- возвращает идентификатор эксперимента.getParamValueString()
,getParamValueFloat()
,getParamValueLong()
,getParamValueBoolean()
- принимают название параметра, возвращают его значение преобразованное в указанный тип или null.getFeatureFlagValueString()
,getFeatureFlagValueFloat()
,getFeatureFlagValueLong()
,getFeatureFlagValueBoolean()
- работают аналогичноSigma.checkFlag()
, но в пределах эксперимента. (см. Получение значения Feature Flag)
Получение всех экспериментов пользователя
Для получения всех экспериментов пользователя используется статический метод Sigma.getAllUserExperiments()
.
Данный метод принимает следующие параметры:
- callback - необязательный параметр при использовании suspend версии метода, объект интерфейса
SigmaGetAllUserExperimentsCallback
реализующий его методыonSuccess()
иonError()
.
Примеры вызова метода:
*Без использования kotlin.coroutines*
import ru.expf.sigma.Sigma
import ru.expf.sigma.SigmaGetAllUserExperimentsCallback
...
val client = Sigma.getClient()
client.getAllUserExperiments(
callback = object : SigmaGetAllUserExperimentsCallback {
override fun onSuccess(experiments: String?) {
/** Some code with received experiments string */
}
override fun onError(throwable: Throwable) {
/** Some code with received error */
}
}
)
*С использованием kotlin.coroutines*
import ru.expf.sigma.Sigma
...
async {
val client = Sigma.getClient()
val experiments = client.getAllUserExperiments()
}.await()
Данный метод возвращает строку вида "expName.userGroupIndex|expName.userGroupIndex|...", где expName - название эксперимента и userGroupIndex индекс группы пользователя в эксперименте.
Стоит обратить внимание на то, что в случае непопадания пользователем ни в один эксперимент результат работы метода будет равен null.
Получение названия эксперимента по названию Feature Flag
Для получения название эксперимента по названию Feature Flag используется метод SigmaClient.getExperimentByFeatureFlag()
.
Данный метод принимает следующие параметры:
- flagName - название Feature Flag.
- callback - необязательный параметр при использовании suspend версии метода, объект интерфейса
SigmaGetExperimentByFeatureFlagCallback
реализующий его методыonSuccess()
иonError()
.
Примеры вызова метода:
*Без использования kotlin.coroutines*
import ru.expf.sigma.Sigma
import ru.expf.sigma.SigmaGetExperimentByFeatureFlagCallback
...
val client = Sigma.getClient()
client.getExperimentByFeatureFlag(
flagName = "***",
callback = object : SigmaGetExperimentByFeatureFlagCallback {
override fun onSuccess(experimentName: String?) {
/** Some code with received experiment name */
}
override fun onError(throwable: Throwable) {
/** Some code with received error */
}
}
)
*С использованием kotlin.coroutines*
import ru.expf.sigma.Sigma
...
async {
val client = Sigma.getClient()
val experimentName = client.getExperimentByFeatureFlag(flagName = "***")
}.await()
Список параметров автоматически определяющихся на стороне SDK
- appVersion - версия приложения пользователя (используется versionCode, а не versionName).
- os.version - номер версии Android на устройстве пользователя (допустимые значения можно посмотреть тут).
- os.name - название операционной системы пользователя (сейчас всегда будет равно "android").
- time - текущее время пользователя.
- date - текущая дата пользователя.
- geo.country - страна пользователя.
- geo.state - район пользователя.
- geo.city - город пользователя.
- geo.ip - IP-адрес пользователя.
Целевая аудитория
Версия 2.0.0 и выше
Целевая аудитория – это глобальные условия эксперимента (общий фильтр), от которого дальше происходит деление пользователей на группы и проверка правила в них внутри (если они есть).
Порядок обработки эксперимента: Принудительный список -> Целевая аудитория -> Группа.
- Целевая аудитория в лестнице приоритетов находится после проверки слоя.
Если слой есть, то проверяется бакет, а затем Целевая аудитория. - Принудительные список пользователей игнорирует Целевую аудиторию и остается в первом приоритете.
- Условия из ФФ эксперимента проверяются после глобальных условий.