Feature flags в Android SDK

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

Требования

Pushwoosh Android SDK 6.16.0 или новее, интегрированный, как описано в руководстве по Android SDK. Feature flags входят в основную библиотеку com.pushwoosh:pushwoosh, поэтому добавлять другую зависимость не нужно. Пока SDK не инициализирован, get возвращает null.
Хотя бы один флаг, созданный в Audience → Feature Flags. Вам понадобятся его Key, а также ключи и типы его свойств. Используйте ключи точно в том виде, в каком они указаны там, с учётом регистра. Например, get("New_Checkout") не найдёт флаг с ключом new_checkout.

Чтение флага

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

import com.pushwoosh.Pushwoosh

val flags = Pushwoosh.getInstance().featureFlags

val checkout = flags.get("new_checkout")
if (checkout != null && checkout.isEnabled) {
    showNewCheckout(
        buttonColor = checkout.getString("button_color", "blue"),
        maxItems = checkout.getNumber("max_items", 3.0).toInt(),
    )
} else {
    showOldCheckout()
}

Чтобы проверить только то, включён ли флаг, используйте isEnabled:

val isNewCheckout = Pushwoosh.getInstance().featureFlags.isEnabled("new_checkout", false)

В Java вызывайте Pushwoosh.getInstance().getFeatureFlags().

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

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

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

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

Метод	Возвращает
`getString(property, defaultValue)`	Значение свойства типа String.
`getNumber(property, defaultValue)`	Значение свойства типа Number в виде `Double`.
`getBool(property, defaultValue)`	Значение свойства типа Boolean.
`getJsonObject(property, defaultValue)`	Значение свойства типа JSON, содержащего объект, в виде `JSONObject`.
`getJsonArray(property, defaultValue)`	Значение свойства типа JSON, содержащего массив, в виде `JSONArray`.

isEnabled(key, defaultValue) возвращает defaultValue, когда get(key) возвращает null.

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

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

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

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

import com.pushwoosh.featureflags.FeatureFlagsUpdateListener

private val flagsListener = FeatureFlagsUpdateListener { render() }

override fun onStart() {
    super.onStart()
    Pushwoosh.getInstance().featureFlags.addUpdateListener(flagsListener)
}

override fun onStop() {
    Pushwoosh.getInstance().featureFlags.removeUpdateListener(flagsListener)
    super.onStop()
}

Чтобы запросить флаги самостоятельно, например после действия, которое может перевести пользователя в другой сегмент, вызовите refresh. Пока сохранённые флаги действительны, метод отправляет не более одного запроса за 5 минут и в пределах этого окна отвечает сохранёнными флагами. Callback выполняется в главном потоке:

Pushwoosh.getInstance().featureFlags.refresh { result ->
    if (!result.isSuccess) {
        val status = result.exception?.httpStatus
        // the stored flags, or your defaults, stay in effect
    }
    render()
}

При ошибке result.exception — это FeatureFlagsException. Его httpStatus равен 0, если запрос не получил HTTP-ответа, и 200, если сервер ответил, но ответ не удалось использовать.

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

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

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

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

val flags = Pushwoosh.getInstance().featureFlags
val isOn = flags.isEnabled("new_checkout", false)
flags.logImpression("new_checkout")
if (isOn) {
    showNewCheckout()
} else {
    showOldCheckout()
}

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

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

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

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

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

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

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