Feature flags в Web SDK

Pushwoosh.featureFlags передаёт вашему сайту feature flags, настроенные для приложения в Панели управления. Pushwoosh вычисляет правила флага на сервере для текущего устройства и пользователя, а SDK возвращает результат: включён ли флаг для этого посетителя и какие значения свойств действуют.

Требования

Web SDK 3.94.1 или новее, загруженный с CDN Pushwoosh, как описано в руководстве по Web SDK 3.0, или npm-пакет web-push-notifications 3.95.0 или новее.
Хотя бы один флаг, созданный в Audience → Feature Flags. Вам понадобятся его Key, а также ключи и типы его свойств. Используйте ключи точно в том виде, в каком они указаны там, с учётом регистра. Например, get('New_Checkout') не найдёт флаг с ключом new_checkout.

Чтение флага

Считывайте флаги после того, как SDK готов. Всегда передавайте значение по умолчанию: оно действует, пока у SDK нет флагов для страницы, а также когда флаг не существует, архивирован или тариф не включает feature flags.

Pushwoosh.push(() => {
  const flags = Pushwoosh.featureFlags;

  const render = () => {
    const checkout = flags.get('new_checkout');
    if (checkout && checkout.enabled) {
      showNewCheckout({
        buttonColor: checkout.getString('button_color', 'blue'),
        maxItems: checkout.getNumber('max_items', 3),
      });
    } else {
      showOldCheckout();
    }
  };

  render();
  flags.addUpdateListener(render);
});

С npm-пакетом используйте созданный вами экземпляр Pushwoosh:

import { Pushwoosh } from 'web-push-notifications';

const pushwoosh = new Pushwoosh();
pushwoosh.push(['init', { applicationCode: 'XXXXX-XXXXX' /* ... */ }]);

pushwoosh.push(() => {
  const isNewCheckout = pushwoosh.featureFlags.isEnabled('new_checkout', false);
  // ...
});

SDK не отправляет запросов флагов на странице, пока ваш код впервые не вызовет get(), isEnabled(), refresh() или addUpdateListener(), поэтому страницы, которые не используют флаги, не создают дополнительного трафика.

Что возвращает флаг

get(key) возвращает объект FeatureFlag или null, если у SDK ещё нет флагов для страницы или флага нет в ответе. Архивированного флага в ответе нет. У объекта есть следующие поля:

Поле	Тип	Описание
`key`	string	Ключ флага.
`enabled`	boolean	Включён ли флаг для этого посетителя.
`ruleId`	string	Правило, определившее результат, например `r_1a2b3c4d`. `default`, если посетителю не подошло ни одно правило, и пустая строка, если флаг аварийно отключён (killed).

Считывайте значения свойств геттером, который соответствует типу свойства. Каждый геттер возвращает ваше значение по умолчанию, если свойство отсутствует или содержит значение другого типа. Когда флаг выключен, свойства содержат значения по умолчанию, заданные в Панели управления.

Метод	Возвращает
`getString(property, defaultValue)`	Значение свойства типа String.
`getNumber(property, defaultValue)`	Значение свойства типа Number.
`getBool(property, defaultValue)`	Значение свойства типа Boolean.
`getJson(property, defaultValue)`	Значение свойства типа JSON в виде разобранного JSON-значения.
`getProperties()`	Копию всех значений свойств флага.

isEnabled(key, defaultValue) — сокращённая запись для get(key)?.enabled, которая возвращает defaultValue, если флага нет.

Актуальность флагов

SDK хранит последний ответ в IndexedDB браузера до 24 часов. Сохранённые флаги действительны только для того User ID, для которого они были запрошены. SDK обновляет их:

при первом использовании на странице, если сохранённым флагам больше 15 минут или их нет;
каждый час, пока страница открыта;
после регистрации устройства, если флаги были запрошены до регистрации;
сразу после смены User ID. Сохранённые флаги предыдущего пользователя удаляются, поэтому новый пользователь их никогда не увидит.

Чтобы реагировать на новые значения, зарегистрируйте слушатель. Он вызывается после обновления, которое изменило значение какого-либо флага:

const onFlagsChanged = () => render();
Pushwoosh.featureFlags.addUpdateListener(onFlagsChanged);
// later
Pushwoosh.featureFlags.removeUpdateListener(onFlagsChanged);

Чтобы запросить флаги самостоятельно, например после действия, которое может перевести посетителя в другой сегмент, вызовите refresh(). Пока сохранённые флаги действительны, метод отправляет не более одного запроса за 5 минут и в пределах этого окна сразу завершается. Если запрос не удался, promise отклоняется, а сохранённые флаги продолжают использоваться.

try {
  await Pushwoosh.featureFlags.refresh();
} catch (error) {
  // the stored flags, or your defaults, stay in effect
}
render();

Если Pushwoosh не успевает определить сегменты посетителя, он возвращает частичный ответ. SDK использует его только на текущей странице, только когда у него нет действительных сохранённых флагов, и никогда его не сохраняет. Следующее обновление приносит полный ответ.

Когда флаг аварийно отключают (kill) в Панели управления, посетители при следующем обновлении получают его выключенным со значениями свойств по умолчанию. Когда SDK не может связаться с сервером, он продолжает использовать сохранённые флаги, пока им не исполнится 24 часа, а после этого — ваши значения по умолчанию.

Запись показов

Показ (impression) сообщает Pushwoosh, что посетитель действительно дошёл до кода, которым управляет флаг, чтобы вы могли сравнить посетителей, получивших функцию, с теми, кто её не получил. Вызывайте logImpression(key) в момент, когда посетитель видит функцию или её старую версию, — и во включённой, и в выключенной ветке, потому что посетители с выключенным флагом и есть ваша группа сравнения:

const checkout = Pushwoosh.featureFlags.get('new_checkout');
if (checkout) {
  Pushwoosh.featureFlags.logImpression('new_checkout');
}

SDK отправляет событие PW_FeatureFlagImpression со следующими атрибутами:

Атрибут	Тип	Значение
`flag_key`	string	Ключ флага.
`rule_id`	string	Правило, определившее результат, как в `ruleId`.
`enabled`	boolean	Был ли флаг включён.

Создавать событие заранее не нужно: Pushwoosh добавляет PW_FeatureFlagImpression с этими атрибутами в Audience → Events, когда приходит первый показ. SDK отправляет один показ на флаг, правило и состояние на странице и в течение 30 минут пропускает повторы из других вкладок того же браузера. logImpression() никогда не отклоняется и ничего не отправляет, если для ключа нет флага.

Показы также позволяют маркетологам собрать сегмент посетителей, которые дошли до функции: состояние видел фичу (30 дней) в условии по feature flag.

Справочник методов

У Pushwoosh.featureFlags есть следующие методы:

Метод	Описание
`get(key)`	Возвращает `FeatureFlag` для ключа или `null`. Читает только сохранённые флаги и никогда не ждёт сети.
`isEnabled(key, defaultValue)`	Возвращает, включён ли флаг, или `defaultValue`, если флага нет.
`refresh()`	Запрашивает флаги не чаще одного раза за 5 минут, пока сохранённые флаги действительны. Возвращает promise.
`addUpdateListener(listener)`	Вызывает `listener` после каждого обновления, которое изменило значение флага.
`removeUpdateListener(listener)`	Удаляет слушатель, добавленный через `addUpdateListener`.
`logImpression(key)`	Отправляет событие `PW_FeatureFlagImpression` для текущего правила и состояния флага. Возвращает promise.