Feature flags en el SDK de Android

Pushwoosh.getInstance().featureFlags proporciona a su aplicación Android los feature flags configurados para la aplicación en el Panel de control. Pushwoosh evalúa las reglas del flag en el servidor para el dispositivo y el usuario actuales, y el SDK devuelve el resultado: si el flag está activado para este dispositivo y qué valores de propiedades se aplican.

Requisitos previos

Pushwoosh Android SDK 6.16.0 o posterior, integrado como se describe en la guía del SDK de Android. Los feature flags forman parte de la biblioteca principal com.pushwoosh:pushwoosh, por lo que no necesita agregar otra dependencia. Hasta que el SDK se inicializa, get devuelve null.
Al menos un flag creado en Audience → Feature Flags. Necesita su Key y las claves y los tipos de sus propiedades. Use las claves exactamente como aparecen allí, incluidas mayúsculas y minúsculas. Por ejemplo, get("New_Checkout") no encuentra un flag con la clave new_checkout.

Leer un flag

Pase siempre un valor predeterminado. Se aplica hasta que el SDK tenga flags para el dispositivo, y siempre que el flag no exista, esté archivado o el plan no incluya 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()
}

Para comprobar solo si el flag está activado, use isEnabled:

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

En Java, llame a Pushwoosh.getInstance().getFeatureFlags().

Qué devuelve un flag

get(key) devuelve un objeto FeatureFlag, o null cuando el SDK aún no tiene flags para el dispositivo o el flag no está en la respuesta. Un flag archivado no está en la respuesta. get solo lee los flags almacenados y nunca espera a la red. El objeto tiene estos campos:

Campo	Tipo	Descripción
`key`	String	La clave del flag.
`isEnabled`	Boolean	Si el flag está activado para este dispositivo.
`ruleId`	String	La regla que decidió el resultado, por ejemplo `r_1a2b3c4d`. `default` cuando ninguna regla coincidió con el dispositivo, y una cadena vacía cuando el flag está desactivado de emergencia (killed).

Lea los valores de las propiedades con el getter que corresponda al tipo de la propiedad. Cada getter devuelve su valor predeterminado cuando la propiedad falta o contiene un valor de otro tipo. Cuando el flag está desactivado, las propiedades contienen los valores predeterminados establecidos en el Panel de control.

Método	Devuelve
`getString(property, defaultValue)`	El valor de una propiedad String.
`getNumber(property, defaultValue)`	El valor de una propiedad Number, como `Double`.
`getBool(property, defaultValue)`	El valor de una propiedad Boolean.
`getJsonObject(property, defaultValue)`	El valor de una propiedad JSON que contiene un objeto, como `JSONObject`.
`getJsonArray(property, defaultValue)`	El valor de una propiedad JSON que contiene un array, como `JSONArray`.

isEnabled(key, defaultValue) devuelve defaultValue cuando get(key) devuelve null.

Mantener los flags actualizados

El SDK almacena la última respuesta en el dispositivo durante un máximo de 24 horas. Los flags almacenados solo son válidos para el User ID para el que se solicitaron. El SDK los actualiza:

Cuando comienza una sesión, es decir, cuando la aplicación pasa a primer plano por primera vez o después de al menos 30 minutos en segundo plano.
Cada hora mientras la aplicación está en primer plano.
Después de que el dispositivo se registra por primera vez.
Justo después de que cambia el User ID con setUserId. Los flags almacenados del usuario anterior se descartan, por lo que un usuario nuevo nunca los ve.

Para reaccionar a los nuevos valores, registre un listener. Se llama después de una actualización que cambió el valor de algún flag:

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()
}

Para solicitar los flags usted mismo, por ejemplo después de una acción que puede mover al usuario a otro segmento, llame a refresh. Mientras los flags almacenados son válidos, envía como máximo una solicitud cada 5 minutos y, dentro de ese intervalo, responde con los flags almacenados. El callback se ejecuta en el hilo principal:

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

En caso de error, result.exception es una FeatureFlagsException. Su httpStatus es 0 cuando la solicitud no obtuvo respuesta HTTP, y 200 cuando el servidor respondió pero la respuesta no se pudo usar.

Si Pushwoosh no puede determinar a tiempo los segmentos del dispositivo, devuelve una respuesta parcial. El SDK no la almacena, y la siguiente actualización trae la respuesta completa.

Cuando un flag se desactiva de emergencia (kill) en el Panel de control, los dispositivos lo reciben desactivado y con los valores predeterminados de las propiedades en la siguiente actualización. Cuando el SDK no puede conectarse con el servidor, sigue usando los flags almacenados hasta que tienen 24 horas de antigüedad, y después sus valores predeterminados.

Registrar impresiones

Una impresión le indica a Pushwoosh que un usuario realmente llegó al código que controla un flag, para que pueda comparar a los usuarios que recibieron la función con los que no. Llame a logImpression(key) en el momento en que el usuario ve la función o su versión anterior, tanto en la rama activada como en la desactivada, porque los usuarios con el flag desactivado son su grupo de comparación:

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

El SDK envía el evento PW_FeatureFlagImpression con estos atributos:

Atributo	Tipo	Valor
`flag_key`	string	La clave del flag.
`rule_id`	string	La regla que decidió el resultado, como en `ruleId`.
`enabled`	boolean	Si el flag estaba activado.

No necesita crear el evento de antemano, porque Pushwoosh agrega PW_FeatureFlagImpression con estos atributos a Audience → Events cuando llega la primera impresión. El SDK envía una impresión por flag, regla y estado en una sesión, y no envía nada cuando no hay flag para la clave.

Las impresiones también permiten a los equipos de marketing crear un segmento de usuarios que llegaron a la función: el estado vio la función (30 días) de la condición de feature flag.

Referencia de métodos

Pushwoosh.getInstance().featureFlags tiene estos métodos:

Método	Descripción
`get(key)`	Devuelve el `FeatureFlag` de la clave, o `null`. Solo lee los flags almacenados.
`isEnabled(key, defaultValue)`	Devuelve si el flag está activado, o `defaultValue` cuando no hay flag.
`refresh(callback)`	Solicita los flags, con un límite de una vez cada 5 minutos mientras los flags almacenados son válidos. El callback recibe un `Result` con una `FeatureFlagsException` en caso de error, y puede ser `null`.
`addUpdateListener(listener)`	Llama a `listener` después de cada actualización que cambió el valor de un flag.
`removeUpdateListener(listener)`	Elimina un listener agregado con `addUpdateListener`.
`logImpression(key)`	Envía un evento `PW_FeatureFlagImpression` para la regla y el estado actuales del flag.