Server node.js SDK
expf-sigma-node.js предназначен для проведения тестов и работы с фича флагами, при создании приложений на node.js. После подключения модуля, SDK будет получать обновления из API и сохранять данные в кэш.
Шаг 1 - установка SDK
- NPM
- Yarn
npm i expf-sigma-node.js
yarn add expf-sigma-node.js
Шаг 2 - инициализация SDK
Импортируйте модуль SDK
const Sigma = require('expf-sigma-node.js').default;
После установки вам нужно будет подключить и инициализировать SDK с помощью токена.
Токены предназначены для встраивания SDK в приложения. При необходимости вы можете отменить или создать новые проекты для SDK.
const Sigma = require('expf-sigma-node.js').default;
const token = <TOKEN>;
Шаг 3 - создание экземпляра класса Sigma
Создайте экземпляра класса Sigma
, передайте токен.
const Sigma = require('expf-sigma-node.js').default;
const token = <TOKEN>;
const sigma = new Sigma(token);
userData
userData – объект с пользовательскими данными. SDK целиком и полностью полагаются на предоставленные данные (методы по раздаче эксперимента, фича флагов и т.п.). Подробнее...
При инициализации SDK следует предоставлять объект userData и передавать как можно больше данных, чтобы воспользоваться преимуществами расширенных условий и конфигурации (например, проверки на уровне страны или ОС/браузера).
В deviceCategory можно добавить устройство пользователя из user agent.
Можно легко изменять или удалять свойства userData
без необходимости дополнительной инициализации Sigma
.
- Метод
editUserProperties()
позволяет изменять или удалять свойстваuserData
. Этот метод содержит цепочку вызовов, в которой необходимо вызывать следующий метод для выполнения операций над свойствамиuserData
. Подробнее > - Метод
editUserProperties()
позволяет удалить часть свойств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.
С версии 3.2.0 добавлена возможность фильтровать фича-флаги и эксперименты по платформам, которые указаны в админ-панели. В UserData можно передать ключ platform (по умолчанию 'all') и значение, например 'ios'.
userData = {
userId: 'userId', // например, clientId из счетчика google analytics
platform: ['android', 'web', 'ios']
}
const Sigma = require('expf-sigma-node.js').default;
const token = <TOKEN>;
const userData = {
userId: 'userId',
email: 'example@mail.ru',
custom: {
new_user: true,
level: 2
}
}
const sigma = new Sigma(token, userData);
cacheTTL
cacheTTL - третий необязательный параметр. Number
Метка времени (по умолчанию 10 секунд), указывает через какой промежуток времени обновить данные. Измеряется в секундах. Меньше 10 поставить нельзя, если указать число меньше 10, значение будет взято по умолчанию.
Пример подключения cacheTTL в sdk
const Sigma = require('expf-sigma-node.js').default;
const token = <TOKEN>;
const userData = {
userId: 'userId',
email: 'example@mail.ru',
custom: {
new_user: true,
level: 2
}
}
const cacheTTL: number = 60;
const sigma = new Sigma(token, userData, cacheTTL);
Работа с фича флагами
Метод checkFlag(...)
принимает обязательный, строковый параметр - название 'фича-флага'
. Он используется для проверки наличия определенной фичи в конфигурации экспериментов.
Если в конфигурации существует эксперимент с таким же названием 'фича-флага'
, метод назначает группу, проверяет условия этой группы и возвращает значение условия (или значение группы по умолчанию).
Если эксперимент с таким названием не найден в конфигурации, но переданное название 'фича-флага'
существует, метод возвращает значение условия 'фича-флага'
(или значение 'фича-флага'
по умолчанию).
Если в конфигурации не найдено название 'фича-флага'
, метод вернет null
.
Тип возвращаемого значения метода может быть string
, bool
, json
или number
.
Пример использования:
/**
* @param {string} flagName
*/
const feature?: string | bool | number = await sigma.checkFlag('flagName');
Работа с экспериментами
Метод 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'));
Свойство эксперимента groupIndex
sdk v.3.1.0 и выше
groupIndex
- свойство метода getExperiment(...)
, возвращает индекс группы в которую попал пользователь, если группа не назначена вернет null
Возвращаемое значение number | null
Пример:
const Sigma = require('expf-sigma-node.js').default;
const token = <TOKEN>;
const userData = { userId: 'userId' };
const sigma = new Sigma(token, userData);
const experiment: Promise<void> = await sigma.getExperiment(...);
const groupIndex: number = experiment.groupIndex; // 0 (первая группа) || null
Получение списка экспериментов
Для оценки эффективности АБ теста, необходимо передавать в системы аналитики наименование эксперимента и вариант, который вернулся пользователю. Т.к. экспериментов много, то необходимо возвращать их все. Дальше разработчик может передавать полученную строку из кэша в системы аналитики как захочет.
Метод getAllUserExperiments()
вызывается без аргументов.
Возвращает строку (название и индекс) в которые попал пользователь.
Если пользователь не попал ни в один эксперимент, вернет null
const allExperiments?: string = await sigma.getAllUserExperiments(); // param.0|exp_name_pay.1|has_layer.2|bg_link.3
Работа с гео-локацией
версия expf-sigma-node.js 1.2.3 и выше
Есть два способа работы с экспериментами и ФФ, в которых есть условия на гео:
Передавать гео-данные пользователя в объект
userData
.Данные можно получить сторонним сервисом (но в таком случае, необходимо, чтобы наименование было идентично тому, что будет указано в условиях эксперимента/фф).
Пример:
const userGeoLocation = await exampleGetGeoLocation() // { "city": "Perm", "country": "Russia" };
const userData = {
userId: 'id',
geo: userGeoLocation,
}
const sigma = new Sigma(token, userData);Передавать
ip
пользователя в объектuserData
.SDK сделает запрос по ip, результат запишет в кэш.
Пример:
const userIp = req.ip // "5.140.69.184";
const userData = {
userId: 'id',
ip: userIp,
}
const sigma = new Sigma(token, userData);
Целевая аудитория
Версия 2.0.0 и выше
Целевая аудитория – это глобальные условия эксперимента (общий фильтр), от которого дальше происходит деление пользователей на группы и проверка правила в них внутри (если они есть).
Порядок обработки эксперимента: Принудительный список -> Целевая аудитория -> Группа.
- Целевая аудитория в лестнице приоритетов находится после проверки слоя.
Если слой есть, то проверяется бакет, а затем Целевая аудитория. - Принудительные список пользователей игнорирует Целевую аудиторию и остается в первом приоритете.
- Условия из ФФ эксперимента проверяются после глобальных условий.
Экземпляры класса sigma
В случае, когда нужно провести эксперименты с разными userId или подключить несколько проектов (токенов), можно создать новый экземпляр класса Sigma, и передать еще один userId или токен. Количество экземпляров класса Sigma не ограничено, важное условие при создании второго и последующих классов - четвертым параметром, в объект options добавить свойство с ключом postfix и любым строковым значением.
const token2 = 'token2';
const sigmaOptions = {
postfix: 'test'
};
const sigma2 = new Sigma(token2, { userId: '2' }, cacheTTL, sigmaOptions);
const allExperiments = await sigma2.getAllUserExperiments();
Работа с кэшем в SDK
Схема работы с кэшем в SDK
В SDK кэш реализован с использованием npm модуля node-cache.
Стандартный срок жизни для каждого элемента кэша 2,5 дня.
Период, используемый для интервала автоматической проверки удаления 10 минут.
При создании экземпляра класса SDK const sigma = new Sigma(...)
базовые настройки будут автоматически добавлены в кэш. Настройки зависят от того что передано в аргументах.
Например, данные идентификатора пользователя: userId, profileId, deviceId.
Если передать userId в userData, в кэш будет добавлена метка времени. Эта метка времени выполнит проверку, если в SDK не передан userId более 24 часов, userId считается устаревшим и эксперименты связанные с этим userId не будут учитываться.
При создании экземпляра класса SDK, можно указать время жизни кэша подробнее >.
На данном этапе SDK запрос за конфигом не делает.
Фактический запрос за конфигом и гео данными пользователя, а также запись полученных данных в кэш (с проверкой метки времени), происходят при первом вызове одного из следующих методов SDK:
checkFlag
getExperiment
getAllUserExperiments
Как SDK работает с гео-локацией.
Все перечисленные методы требуют данные в кэше для корректного расчета экспериментов и фича флагов.
После успешного запроса за данными, кэш считается актуальным в течение времени,
указанного в cacheTTL при создании экземпляра класса SDK. По умолчанию cacheTTL равен 10 секундам.
Повторный запрос за данными и их запись в кэш будет выполнен только через cacheTTL секунд после последнего запроса (вызова одного из методов SDK указанных выше).
В случае ошибок запроса, запись ошибки будет добавлена в консоль. Однако SDK не вызовет ошибку и не повлияет на работу приложения. Если в кэше содержатся старые данные, SDK продолжит использовать их для расчетов экспериментов и фича флагов. Старые данные будут считаться актуальным cacheTTL секунд.
После внесения изменений в админ-панели, обновленный конфигурационный файл станет доступным с задержкой до 2 минут.
Вопросы по работе с кэшем в SDK
Когда получаем кэш?
Кэш создается при создании экземпляра класса SDK, и если переданы определенные данные
Кэш с данными конфига SDK создает при вызове одного из следующих методов SDK:
- checkFlag
- getExperiment
- getAllUserExperiments
Когда обновляем?
Через cacheTTL (по умолчанию 10) секунд после последнего запроса (вызова метода SDK)
Когда не можем получить?
Ошибка соединения с сервером
Как часто обновляем кэш?
Через cacheTTL (по умолчанию 10) секунд и вызове метода SDK
Как методы взаимодействуют с кэшем?
Парсят данные конфига в кэше, производят расчет экспериментов, фича флагов
Какие методы просят актуальный кэш с веб сервера?
- checkFlag
- getExperiment
- getAllUserExperiments