JavaScript Client SDK

Установка SDK

Script
NPM
Yarn

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

npm install expf-sigma.js

yarn add expf-sigma.js

Инициализация 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. Подробнее >
Метод clearUserProperties() позволяет удалить часть свойств userData. Подробнее >

cacheTTL

cacheTTL?: number

Необязательный параметр, задающий промежуток времени, через который данные в кэше будут считаться устаревшими и потребуют обновления. Значение по умолчанию: 10 секунд.

Минимально допустимое значение — 10 секунд. Если передано значение меньше 10, будет автоматически использовано значение по умолчанию.

Пример:

const cacheTTL: number = 60;

sigma.init({ token, userData, cacheTTL });

fetchTimeout

к сведению

С версии v3.7.3 и выше

fetchTimeout?: number

Необязательный параметр, задающий максимальное время ожидания ответа от сервера. Значение по умолчанию: 5000 мс.

Минимально допустимое значение — 500 мс. Если передано значение меньше 500, будет автоматически использовано значение по умолчанию (5000 мс).

Пример:

const fetchTimeout: number = 3000;

sigma.init({ token, userData, fetchTimeout });

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

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

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

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

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

Пример:

let featureValue;

try {
  featureValue = await sigma.checkFlag('payment_method')
} catch (error) {
  // Обработка ошибки
}

// Применяем значение фича-флага
if (featureValue === 'card') {
  showPaymentForm(featureValue);
} else {
  showPaymentForm('crypto');
}

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

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

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

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

let buttonColor = '#007bff';
let buttonText = 'Купить';

try {
  const experiment = await sigma.getExperiment('checkout_button_test');
  buttonColor = experiment.getFeatureValue('button_color') ?? buttonColor;
  buttonText = experiment.getFeatureValue('button_text') ?? buttonText;
} catch (error) {
  // Обработка ошибки
}

applyButtonStyles(buttonColor, buttonText);

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

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

Пример:

let paramValue = 10;
let featureValue = false;
let group = null;

try {
  const experiment = await sigma.getExperiment('pricing_test');

  paramValue = experiment.getParamValue('discount_percent') ?? paramValue;
  featureValue = experiment.getFeatureValue('show_badge') ?? featureValue;
  group = experiment.groupIndex;
  
  console.log(`Пользователь в группе: ${group}`);
} catch (error) {
  // Обработка ошибки
}

// Применяем параметры эксперимента
if (featureValue) {
  showBadge(`${paramValue}%`);
}

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

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

Проверяет условия для участия в эксперименте.
Назначает группу.
Получает адрес страницы пользователя (адрес, домен, путь, query-параметры).
Проверяет условия правил в админ-панели.
Выполняет редирект или завершает работу.

Параметры: url, pathname, query, domain — определяются в SDK автоматически. Можно переопределить любой из перечисленных параметров, передав в userData ключ с названием параметра и строковым значением.

Пример:

const sigma = new Sigma();
const token = '<TOKEN>';
const userData = {
  userId: 'user_12345',
  url: window.location.href,
  pathname: window.location.pathname,
  query: window.location.search,
  domain: window.location.hostname
}

try {
  sigma.init({ token, userData });
  await sigma.useSplitUrl();
} catch (error) {
  // Обработка ошибки
}

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

к сведению

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

На странице должен быть подключён скрипт внутри тега <head>:

<script src="https://api.expf.ru/editor.init.js"></script>

Пример:

const sigma = new Sigma();
const token = '<TOKEN>';
const userData = { 
  userId: 'user_' + Date.now(),
  deviceId: getDeviceId()
}

try {
  await sigma.init({ token, userData, webBuilder: true });
} catch (error) {
  // Обработка ошибки
}

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

к сведению

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

к сведению

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

try {
  sigma.init({ token, userData });
  await sigma.useWebBuilder();
} catch (error) {
  // Обработка ошибки
}

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

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

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

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

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

try {
  const experiments = await sigma.getAllUserExperiments(false);
  
  if (experiments) {
    sendAnalytics('experiments', experiments);
  }
} catch (error) {
  // Обработка ошибки
}

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

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

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

let featureFlags = [];

try {
  featureFlags = await sigma.getUserFeatureFlagsDetails();
  
  // Применяем фича-флаги к интерфейсу
  featureFlags.forEach(flag => {
    if (flag.name === 'enable_dark_mode' && flag.value === true) {
      enableDarkMode();
    }
    if (flag.name === 'show_promo_banner' && flag.value === true) {
      showPromoBanner();
    }
  });
} catch (error) {
  // Обработка ошибки
}

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

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

Экземпляры класса Sigma

В случае, когда нужно провести эксперименты с разными userId или подключить несколько проектов (токенов), можно создать новый экземпляр класса Sigma и передать в метод init этого класса другой userId или токен. Количество экземпляров класса Sigma не ограничено. Важное условие: при создании второго и последующих экземпляров в метод init нужно добавить свойство с ключом postfix и любым строковым значением.

const sigma2 = new Sigma();
const token2 = '<TOKEN_2>';

try {
  sigma2.init({
    token: token2,
    userData: { userId: 'user_123' },
    postfix: 'mobile_app'
  });

  const allExperiments = await sigma2.getAllUserExperiments();
  
  if (allExperiments) {
    trackExperiments('mobile_app', allExperiments);
  }
} catch (error) {
  // Обработка ошибки
}

Полный пример

import Sigma from 'expf-sigma.js';

const sigma = new Sigma();
const token = '<TOKEN>';
const userData = {
  userId: 'user_abc123',
  email: 'user@example.com',
  appVersion: '1.2.3',
  ip: '70.123.12.84',
  deviceCategory: 'desktop',
  custom: {
    isPremium: true,
    registrationSource: 'landing_page'
  },
}

try {
  sigma.init({
    token,
    userData,
  });

  // Проверяем эксперимент с кнопкой оплаты
  const applePayVariant = await sigma.getExperiment('apple_pay_test').then(res => res.getParamValue('apple_pay'));
  
  if (applePayVariant === true) {
    applePayButton.textContent = 'Оплатить через Apple Pay';
    applePayButton.style.display = 'block';
  } else {
    applePayButton.style.display = 'none';
  }

  // Проверяем фича-флаг метода оплаты
  const paymentMethod = await sigma.checkFlag('default_payment_method');
  
  if (paymentMethod === 'mastercard') {
    paymentButton.textContent = 'Оплатить Mastercard';
    paymentButton.setIcon('mastercard');
  } else if (paymentMethod === 'visa') {
    paymentButton.textContent = 'Оплатить Visa';
    paymentButton.setIcon('visa');
  } else {
    // Если фича-флаг не найден или experiment не активен
    paymentButton.textContent = 'Оплатить';
    paymentButton.setIcon('default');
  }
} catch (error) {
  applePayButton.style.display = 'none';
  paymentButton.textContent = 'Оплатить';
  paymentButton.setIcon('default');
  
  sendErrorToMonitoring(error);
}

JavaScript Client SDK

Установка SDK​

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

Создание экземпляра класса Sigma​

userData​

cacheTTL​

fetchTimeout​

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

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

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

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

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

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

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

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

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

Экземпляры класса Sigma​

Полный пример​

Установка SDK

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

Создание экземпляра класса Sigma

userData

cacheTTL

fetchTimeout

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

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

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

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

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

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

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

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

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

Экземпляры класса Sigma

Полный пример