Skip to main content

JavaScript Client SDK

Шаг 1 - установка SDK#

<script src="https://unpkg.com/expf-sigma.js@latest/public/sigma.min.js"></script>

Шаг 2 - инициализация SDK#

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

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

  const token = 'active-token';

Шаг 3 - создание экземпляра класса Sigma#

Создайте экземпляра класса Sigma Используйте метод init для инициализации sigma и передайте токен.

sigma.init({ token })

userData options#

  • userId
  • email
  • deviceCategory
  • ip
  • custom

По дефолту все перечисленные парамеры null (за исключением userId и deviceCategory, который формируется в sigma). Чтобы переназначить один или несколько параметров, нужно при инициализации вторым аргументом передать объект userData.

Параметр deviceCategory формируется автоматически(desktop, tablet, mobile) в зависимость от устройства пользователя.

const userData = {  userId: 'userId',  email: 'example@mail.ru',  deviceCategory: 'mobile',  custom: {    new_user: true,    level: 2  }}
sigma.init({ token, userData })

cacheTTL#

cacheTTL - третий необязательный параметр.

Метка времени (по умолчанию 10 секунд), указывает через какой промежуток времени обновить данные. Измеряется в секундах. Меньше 10 поставить нельзя, если указать число меньше 10, значение будет взято по умолчанию.

const cacheTTL = 60;

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

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

  • метод checkFlag("flagId") проверит фича флаг в userData и вернет value, который можно использовать для работы с документом на сайте.
/**@param "flag" string */const flag = await sigma.checkFlag("flag");
  • после успешной проверки фича флага будут доступны параметры с типом данных:
    • string
    • integer
    • bool

Пример работы с типом данных#

example type string

  const titleFlag = sigma.getFlag("titleFlag"); //'Привет'  document.querySelector(".h1").textContent = titleFlag; // <h1>Привет</h1> 

example type integer

  const priceFlag = sigma.getFlag("priceFlag"); // 100  document.querySelector(".priceItem").textContent = 100 + priceFlag; <p>200</p>

example type bool

  const isHidden = sigma.getFlag("isHiddenFlag"); // true  document.querySelector(".btn").dataset.hidden = isHidden; // <button data-hidden="true"></button>

Шаг 5 - Работа с экпериментами#

Метод getExperiment принемает в качестве аргумента строку, название эксперимента:
Проверит наличие эксперимента и условия вхождения пользователя(по userId) в эксперимент Если экперимент есть, но пользователь не попал в эксперимент, завершит работу При выполнении условий пользователь будет назначен в группу эксперимента

/**@param "exp_id" string */await sigma.getExperiment("exp_id")

После попадания в эксперимент и добавления в группу
У метода getExperiment() есть свои два метода, первый работает с параметрами, второй с фича флагами

Экперименты с параметрами#

Метод getParamValue("paramName") полученные значения нужны для дальнейшей работы с документом тип данных

const applePay = await sigma.getExperiment('exp_id').then(res => res.getParamValue('apple_pay'));
if (applePay && applePay === true) {  applePay.textContent = `applePayVariant 1`;} else if (applePay && applePay === false) {  applePay.textContent = `applePayVariant 2`;}

Экперименты с фича флагами#

Метод getFeatureValue("paramName") работает также как работа с фича флагами , принемает строку и вернет тип данных

Шаг 6 - Получение списка экспериментов#

Для оценки эффективности АБ теста, необходимо передавать в системы аналитики наименование эксперимента и вариант, который вернулся пользователю. Т.к. экспериментов много, то необходимо возвращать их все. Дальше разработчик может передавать полученную строку из кэша в системы аналитики как захочет. Метод getAllUserExperiments вернет строку(название и индекс), и запишет в localStorage все эксперименты в которые попал пользователь. Если нет попадания в экперименты, вернет false

const allExperiments = 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()

Полный пример кода#

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 },}
async function flagUpdates(item, flag) { const price = await item.checkFlag(flag); if (price) {   document.querySelector('.h1').textContent = item.getFlag(flag); }}
sigma.init({ token, userData, onReady: () => {   flagUpdates(sigma, 'price'); },
 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.getExperiment('exp_name_pay').then(res => res.getFeatureValue('pay'));
 if (pay && pay === 'masterCard') {   button.textContent = `masterCard`; } else if (pay && pay === 'visa`) {   button.textContent = `visa`; } else {   button.textContent = `cash`; }});

Анти фликер#

Для решения проблемы рендеринга, которое может быть связано с тем, что пользователь сначала видит контент до применения сплитов, а потом может увидеть другой после их расчетов. Можно применить механизм, который скрывает элемент пока модуль работает с данными. Этот механизм также решит проблему, если модуль по какой то причине не загрузился.

Пример с подключениум модуля через cdn:

  • подключаем модуль <script src="https://unpkg.com/expf-sigma.js@latest/public/sigma.min.js"></script>
  • в скрипт, который работает с модулем sigma добавляем асинхрнную функцмю в теле которой написана логика подключения sigma, рендеринга страницы.
async function start() {  const sigma = new Sigma();  sigma.init({  token, userData })
  const price = await sigma.checkFlag(flag);  if (price) {    document.querySelector('.h1').textContent = price;  }
  el.style.opacity = 1;}
  • добавляем проверку в которой, если модуль не загрузился делаем скрытый элемент видимым, иначе вызываем функцию start
  document.addEventListener("DOMContentLoaded", () => {    if (!window.Sigma) {      el.style.opacity = 1;    } else {      start();    }  });

Пример подключения sdk для ECMAScript 2017(es5)#

  var token = 'token';  var clientid = '1';
  var start = new Promise(    function (resolve, reject) {      if (window.Sigma) {        var sigma = new Sigma();        var userData = {          userId: clientid        };        sigma.init({ token: token, userData: userData });        var exp = sigma.getExperiment('exp');        resolve(exp);      }else {        var reason = new Error("s haven't initialized");        reject(reason);      }
    }  );
  var abStart = function () {      start        .then(function (res) {          var resultExp = res.getFeatureValue('test');          console.log(resultExp);        })        .catch(function (error) {          console.log(error.message);        });    };
  abStart();