Перейти к основному содержимому

JavaScript Client SDK

Установка SDK​

<script src="https://api.expf.ru/sigma.min.js"></script>

Инициализация SDK​

После установки вам нужно будет инициализировать SDK с помощью токена.

Токены предназначены для встраивания SDK в приложения. При необходимости вы можете отменить или создать новые проекты для SDK.

import Sigma from expf-sigma.js;

const token = <TOKEN>;
const sigma = new Sigma();

Создание экземпляра класса 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 и передавать как можно больше данных, чтобы воспользоваться преимуществами расширенных условий и конфигурации (например, проверки на уровне страны или ОС/браузера).

Расчет соли и прочего происходит по полю, указанному в split_by.

const userData = {
  userId: 'userId',       // например, clientId из счетчика google analytics 
  profileId: 'profileId', // например, ID пользователя при регистрации 
  deviceId: 'deviceId',   // например, ID устройства с которого зашел пользователь
  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, значение будет взято по умолчанию.

Пример:

const cacheTTL: number = 60;
sigma.init({ token, userData, cacheTTL })

Работа с фича флагами​

Метод checkFlag(...) принимает обязательный, строковый параметр - название 'фича-флага'. Он используется для проверки наличия определенной фичи в конфигурации экспериментов.

Если в конфигурации существует эксперимент с таким же названием 'фича-флага', метод проверит условия эксперимента, назначит группу и вернет значение условия (или значение группы по умолчанию) эксперимента.

Если эксперимент с таким названием не найден в конфигурации, или пользователь не попал в условия эксперимента но переданное название 'фича-флага' существует, метод вернет значение условия 'фича-флага' (или значение 'фича-флага' по умолчанию).

Если в конфигурации не найден фича флаг с переданным параметром, метод вернет null.

Пример:

/** 
 * @param {string} flagName
*/
const feature = await sigma.checkFlag('flagName'); // string | boolean | number | null

Получение списка фича флагов​

Метод getUserFeatureFlagsDetails() вызывается без аргументов. Вернет список всех фича флагов пользователя, где каждый фича флаг представлен объектом с ключами name, value.

const allFF = await sigma.getUserFeatureFlagsDetails() // [{"name": "main_flag","value": 1}, {"name": "new_flag","value": "new"}]

Работа с экспериментами​

Метод getExperiment(...) принимает обязательный строковый параметр — идентификатор эксперимента. Он проверяет наличие эксперимента и условия участия пользователя в эксперименте. При выполнении условий пользователь будет назначен в группу эксперимента. Чтобы получить результат, в зависимости от типа эксперимента, нужно передать одно из свойств интерфейса:

  • getParamValue(...)
  • getFeatureValue(...)
  • groupIndex

Пример, получить информацию об эксперименте с типом фича флаг:

/**
* @param {string} exp_id
* @param {string} ff_name
*/
const experiment = await sigma.getExperiment('exp_id');
const feature = experiment.getFeatureValue('ff_name'); // number | string | boolean | null

Получение информации из эксперимента​

После получения эксперимента, информация об эксперименте доступна из методов объекта getExperiment(...):

Пример:

const experiment = await sigma.getExperiment('exp_id');

const feature = experiment.getParamValue('param_name'); // number | string | boolean | null
const feature = experiment.getFeatureValue('ff_name');  // number | string | boolean | null 
const feature = experiment.groupIndex; // number | null

Эксперименты с переадресацией​

Метод 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

Эксперименты с веб-редактором​

к сведению

Рекомендуется настроить прелоадер для элементов участвующих в эксперименте или анти-фликер

На странице должен быть подключен скрипт внутри тега <head>
<script src="https://api.expf.ru/editor.init.js"></script>

Пример:

const sigma = new Sigma();
const token = <TOKEN>;
const userData = { userId: 'id' }

await sigma.init({ token, userData, webBuilder: true });

Для использования SDK с экспериментом веб-редактор необходимо при инициализации SDK указать флаг webBuilder: true.

к сведению

Что бы SDK не делало лишних запросов за конфигом метод init(...) должен быть асинхронным

к сведению

С версии v.3.6.2 и выше, добавлен новый метод useWebBuilder(). Метод полезен для динамического контента, при инициализации SDK, поле webBuilder: true можно не передавать.

sigma.init({ token, userData });
await sigma.useWebBuilder();

URL эксперимента​

При создании эксперимента в админ-панели, помимо указания домена, есть возможность указать путь и query-параметры, определяющие место проведения эксперимента. SDK будет проводить проверку настроек адресной строки с параметрами адресной строки пользователя в соответствии с установленными правилами.

Как работает webBuilder:​

  • Проверяет адресную строку из правил админ-панели с адресной строкой пользователя.
  • Проверяет условия для участия в эксперименте.
  • Назначает группу.
  • Читает правила веб-редактора.
  • Выполняет перерендер элементов или глобальных условий в соответствии с правилами.

Получение списка экспериментов​

await sigma.getAllUserExperiments(estimateHoldouts?: boolean); // null | string

Возвращает строку (название и индекс) в которые попал пользователь. Если пользователь не попал ни в один эксперимент, вернет null

Параметр estimateHoldouts?: boolean необязательный. По умолчанию true. Если true - метод вернет все эксперименты, включая холдауты, в которые попал пользователь. Если false - метод вернет только эксперименты, не являющиеся холдаутами. По умолчанию true.

Получение списка фича флагов​

await sigma.getUserFeatureFlagsDetails() // [{"name": "main_flag","value": 1}, {"name": "new_flag","value": "new"}]

Метод getUserFeatureFlagsDetails() вызывается без аргументов.

Возвращает список всех фича флагов пользователя, где каждый фича флаг представлен объектом с ключами name, value

Экземпляры класса 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`;
}