JavaScript Client SDK
Шаг 1 - установка SDK
- Script
- NPM
- Yarn
<script src="https://api.expf.ru/sigma.min.js"></script>
npm install expf-sigma.js
yarn add expf-sigma.js
Шаг 2 - инициализация SDK
После установки вам нужно будет инициализировать SDK с помощью токена.
Токены предназначены для встраивания SDK в приложения. При необходимости вы можете отменить или создать новые проекты для SDK.
import Sigma from expf-sigma.js;
const token = <TOKEN>;
const sigma = new Sigma();
Шаг 3 - создание экземпляра класса Sigma
Создайте экземпляра класса Sigma
, используйте метод init
для инициализации sigma
и передайте токен.
import Sigma from expf-sigma.js;
const token = <TOKEN>;
const sigma = new Sigma();
sigma.init({ token });
userData
userData – объект с пользовательскими данными. SDK целиком и полностью полагаются на предоставленные данные (методы по раздаче эксперимента, фича флагов и т.п.). Подробнее...
При инициализации SDK следует предоставлять объект userData и передавать как можно больше данных, чтобы воспользоваться преимуществами расширенных условий и конфигурации (например, проверки на уровне страны или ОС/браузера).
С версии 3.0.0 и выше, добавлена обработка поля split_by. В UserData можно передать поля userId, deviceId, profileId.
userData = {
userId: 'userId', // например, clientId из счетчика google analytics
profileId: 'profileId' // например, ID пользователя при регистрации
deviceId: 'deviceId' // например, ID устройства с которого зашел пользователь
}
Расчет соли и прочего происходит не по userId, а по полю, указанному в split_by.
Пример userData с подключением в sdk при инициализации
const userData = {
userId: 'userId',
email: 'example@mail.ru',
deviceCategory: 'mobile',
custom: {
new_user: true,
level: 2
}
}
sigma.init({ token, userData })
В процессе взаимодействия с приложением можно легко изменять или удалять свойства
userData
без необходимости дополнительной инициализации Sigma
.
- Метод
editUserProperties()
позволяет изменять или удалять свойстваuserData
. Этот метод содержит цепочку вызовов, в которой необходимо вызывать следующий метод для выполнения операций над свойствамиuserData
. Подробнее > - Метод
editUserProperties()
позволяет удалить часть свойствuserData
. Подробнее >
cacheTTL
cacheTTL - третий необязательный параметр. Number
.
Метка времени (по умолчанию 10 секунд), указывает через какой промежуток времени обновить данные. Измеряется в секундах. Меньше 10 поставить нельзя, если указать число меньше 10, значение будет взято по умолчанию.
Пример подключения cacheTTL в sdk при инициализации
const cacheTTL: number = 60;
sigma.init({ token, userData, cacheTTL })
Шаг 4 - Работа с фича флагами
Метод checkFlag(...)
принимает обязательный, строковый параметр - название 'фича-флага'
. Он используется для проверки наличия определенной фичи в конфигурации экспериментов.
Если в конфигурации существует эксперимент с таким же названием 'фича-флага'
, метод назначает группу, проверяет условия этой группы и возвращает значение условия (или значение группы по умолчанию).
Если эксперимент с таким названием не найден в конфигурации, но переданное название 'фича-флага'
существует, метод возвращает значение условия 'фича-флага'
(или значение 'фича-флага'
по умолчанию).
Если в конфигурации не найдено название 'фича-флага'
, метод вернет null
.
Тип возвращаемого значения метода может быть string
, bool
, json
или number
.
Пример использования:
/**
* @param {string} flagName
*/
const feature?: string | bool | number = await sigma.checkFlag('flagName');
Пример с типом данных при работе с документом
type string
const titleFlag?: string = await sigma.checkFlag('titleFlag'); //'Привет'
document.querySelector('.h1').textContent = titleFlag || 'Hello'; // <h1>Привет</h1>
type number
const priceFlag?: number = await sigma.checkFlag('priceFlag'); // 100
document.querySelector('.priceItem').textContent = 100 + priceFlag; <p>200</p>
type bool
const isHidden?: bool = await sigma.checkFlag('isHiddenFlag'); // true
document.querySelector('.btn').dataset.hidden = isHidden; // <button data-hidden="true"></button>
Шаг 5 - Работа с экспериментами
Метод getExperiment(...)
принимает обязательный, строковый параметр - идентификатор эксперимента.
Он проверяет наличие эксперимента и условия вхождения пользователя в эксперимент.
Если эксперимент существует, но пользователь не попал в него вернет null
.
При выполнении условий пользователь будет назначен в группу эксперимента.
/**
* @param {string} exp_id
*/
await sigma.getExperiment('exp_id') // interface || null
При успешном определении группы эксперимента, методу getExperiment(...)
будет доступен объект интерфейса для работы с параметрами и фича флагами.
Эксперименты с параметрами
Метод getParamValue(...)
принимает обязательный, строковый параметр - название параметра эксперимента.
Возвращаемое значение string | number | boolean | json
зависит от настройки эксперимента.
/**
* @param {string} exp_id
* @param {string} apple_pay
*/
const applePay?: string | number | boolean = await sigma.getExperiment('exp_id').then(res => res.getParamValue('apple_pay'));
Эксперименты с фича флагами
Метод getFeatureValue(...)
принимает обязательный, строковый параметр - название фича-флага эксперимента.
Возвращаемое значение string | number | boolean | json
зависит от настройки эксперимента.
/**
* @param {string} exp_id
* @param {string} apple_pay
*/
const applePay?: string | number | boolean = await sigma.getExperiment('exp_id').then(res => res.getFeatureValue('apple_pay'));
Эксперименты с переадресацией
Версия SDK v.1.2.0 и выше.
Проекты, в которых есть эксперименты с переадресацией.Метод useSplitUrl() вызывается без аргументов:
- Проверяет условия для участия в эксперименте.
- Назначает группу.
- Получает адрес страницы пользователя(адрес, домен, путь, query-параметры)
- Проверяет условия правил в админ-панели
- Выполняет редирект или завершит работу
Параметры: url, pathname, query, domain - определяются в sdk автоматически. Можно переназначить любой из перечисленных параметров, передав в userData ключ с названием параметра и строковым значением
Пример:
const sigma = new Sigma();
const token = <TOKEN>;
const userData = {
userId: 'id',
url: 'url',
pathname: 'pathname',
query: 'query',
domain: 'domain'
}
sigma.init({ token, userData });
await sigma.useSplitUrl(); // redirect || null
Свойство эксперимента groupIndex
Версия SDK v.3.1.0 и выше
groupIndex
- свойство метода getExperiment(...)
, возвращает индекс группы в которую попал пользователь, если группа не назначена вернет null
Возвращаемое значение number | null
Пример:
const sigma = new Sigma();
const token = <TOKEN>;
const userData = {
userId: 'id'
}
sigma.init({ token, userData });
const experiment: Promise<void> = await sigma.getExperiment(...);
const groupIndex: number = experiment.groupIndex; // 0 (первая группа) || null
Эксперименты с веб-редактором
Версия SDK 3.3.2 и выше.
Рекомендуется настроить прелоадер для элементов участвующих в эксперименте или анти-фликер
Пример:
const sigma = new Sigma();
const token = <TOKEN>;
const userData = { userId: 'id' }
await sigma.init({ token, userData, webBuilder: true });
Для использования SDK с экспериментом веб-редактор необходимо
при инициализации SDK указать флаг webBuilder: true
.
Что бы SDK не делало лишних запросов за конфигом метод init(...)
должен быть асинхронным
SDK автоматически попытается найти эксперименты веб-редактора.
URL эксперимента
При создании эксперимента в админ-панели, помимо указания домена, есть возможность указать путь и query-параметры, определяющие место проведения эксперимента. SDK будет проводить проверку настроек адресной строки с параметрами адресной строки пользователя в соответствии с установленными правилами.
Как работает webBuilder
:
- Проверяет адресную строку из правил админ-панели с адресной строкой пользователя.
- Проверяет условия для участия в эксперименте.
- Назначает группу.
- Читает правила веб-редактора.
- Выполняет перерендер элементов или глобальных условий в соответствии с правилами.
Шаг 6 - Получение списка экспериментов
Для оценки эффективности АБ теста, необходимо передавать в системы аналитики наименование эксперимента и вариант, который вернулся пользователю. Т.к. экспериментов много, то необходимо возвращать их все. Дальше разработчик может передавать полученную строку из кэша в системы аналитики как захочет.
Метод getAllUserExperiments()
вызывается без аргументов.
Возвращает строку(название и индекс), и запишет в кэш все эксперименты в которые попал пользователь.
Если пользователь не попал ни в один эксперимент, вернет null
const allExperiments?: string = await sigma.getAllUserExperiments(); // param.0|exp_name_pay.1|has_layer.2|bg_link.3
Экземпляры класса sigma
В случае, когда нужно провести эксперименты с разными userId или подключить несколько проектов (токенов), можно создать новый экземпляр класса Sigma, и передать в метод init этого класса еще один userId или токен. Количество экземпляров класса Sigma не ограничено, важное условие при создании второго и последующих классов - в метод init добавить свойство с ключом postfix и любым строковым значением.
const sigma2 = new Sigma();
const token2 = 'token2';
sigma2.init({
token: token2,
userData: { userId: '123' },
postfix: 'test'
});
const allExperiments = await sigma2.getAllUserExperiments()
Полный пример
import Sigma from expf-sigma.js;
const sigma = new Sigma();
const token = 'token';
const userData = {
userId: 'userId',
email: 'example@mail.ru',
appVersion: '1.2.3',
ip: '70.123.12.84',
custom: {
cookieKey: "1",
example: false
},
}
sigma.init({
token,
userData,
}),
const applePay = await sigma.getExperiment('exp_name').then(res => res.getParamValue('apple_pay'));
if (applePay && applePay === true) {
applePay.textContent = `applePayVariant 1`;
} else if (applePay && applePay === false) {
applePay.textContent = `applePayVariant 2`;
}
const pay = await sigma.checkFlag('pay'));
if (pay && pay === 'masterCard') {
button.textContent = `masterCard`;
} else if (pay && pay === 'visa`) {
button.textContent = `visa`;
} else {
button.textContent = `cash`;
}