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 и выше

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

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