Skip to main content

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

Целевая аудитория

info

Версия 2.0.0 и выше

Целевая аудитория – это глобальные условия эксперимента (общий фильтр), от которого дальше происходит деление пользователей на группы и проверка правила в них внутри (если они есть).
Порядок обработки эксперимента: Принудительный список -> Целевая аудитория -> Группа.

  • Целевая аудитория в лестнице приоритетов находится после проверки слоя.
    Если слой есть, то проверяется бакет, а затем Целевая аудитория.
  • Принудительные список пользователей игнорирует Целевую аудиторию и остается в первом приоритете.
  • Условия из ФФ эксперимента проверяются после глобальных условий.