Feature flags en el Web SDK

Pushwoosh.featureFlags proporciona a su sitio web 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 visitante y qué valores de propiedades se aplican.

Función beta

Los feature flags están en beta y solo están disponibles en los planes que los incluyen. En otros planes, el servidor no devuelve ningún flag, por lo que cada flag recurre al valor predeterminado que usted pasa en el código.

Requisitos previos

• Web SDK 3.94.1 o posterior, cargado desde la CDN de Pushwoosh como se describe en la guía de Web SDK 3.0, o el paquete npm web-push-notifications 3.95.0 o posterior.
• 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

Lea los flags cuando el SDK esté listo. Pase siempre un valor predeterminado: se aplica hasta que el SDK tenga flags para la página, y siempre que el flag no exista, esté archivado o el plan no incluya 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);
});

Con el paquete npm, use la instancia de Pushwoosh que creó:

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);
  // ...
});

El SDK no realiza solicitudes de flags en una página hasta que su código llama por primera vez a get(), isEnabled(), refresh() o addUpdateListener(), por lo que las páginas que no usan flags no generan tráfico adicional.

Qué devuelve un flag

get(key) devuelve un objeto FeatureFlag, o null cuando el SDK aún no tiene flags para la página o el flag no está en la respuesta. Un flag archivado no está en la respuesta. El objeto tiene estos campos:

Campo	Tipo	Descripción
key	string	La clave del flag.
enabled	boolean	Si el flag está activado para este visitante.
ruleId	string	La regla que decidió el resultado, por ejemplo r_1a2b3c4d. default cuando ninguna regla coincidió con el visitante, 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.
getBool(property, defaultValue)	El valor de una propiedad Boolean.
getJson(property, defaultValue)	El valor de una propiedad JSON, como un valor JSON analizado.
getProperties()	Una copia de todos los valores de propiedades del flag.

isEnabled(key, defaultValue) es un atajo para get(key)?.enabled que devuelve defaultValue cuando no hay flag.

Mantener los flags actualizados

El SDK almacena la última respuesta en el IndexedDB del navegador 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:

• en el primer uso en una página, cuando los flags almacenados tienen más de 15 minutos o no existen;
• cada hora mientras la página permanece abierta;
• después de que el dispositivo se registra, cuando los flags se solicitaron antes del registro;
• justo después de que cambia el User ID. 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:

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

Para solicitar los flags usted mismo, por ejemplo después de una acción que puede mover al visitante a otro segmento, llame a refresh(). Mientras los flags almacenados son válidos, envía como máximo una solicitud cada 5 minutos y se resuelve de inmediato dentro de ese intervalo. La promesa se rechaza cuando la solicitud falla, y los flags almacenados siguen en uso.

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

Si Pushwoosh no puede determinar a tiempo los segmentos del visitante, devuelve una respuesta parcial. El SDK la usa solo en la página actual, solo cuando no tiene flags almacenados válidos, y nunca la almacena. La siguiente actualización trae la respuesta completa.

Cuando un flag se desactiva de emergencia (kill) en el Panel de control, los visitantes 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 visitante realmente llegó al código que controla un flag, para que pueda comparar a los visitantes que recibieron la función con los que no. Llame a logImpression(key) en el momento en que el visitante ve la función o su versión anterior, tanto en la rama activada como en la desactivada, porque los visitantes con el flag desactivado son su grupo de comparación:

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

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 página, y omite las repeticiones desde otras pestañas del mismo navegador durante 30 minutos. logImpression() nunca se rechaza y no envía nada cuando no hay flag para la clave.

Las impresiones también permiten a los especialistas en marketing crear un segmento de visitantes 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.featureFlags tiene estos métodos:

Método	Descripción
get(key)	Devuelve el FeatureFlag de la clave, o null. Solo lee los flags almacenados y nunca espera a la red.
isEnabled(key, defaultValue)	Devuelve si el flag está activado, o defaultValue cuando no hay flag.
refresh()	Solicita los flags, con un límite de una vez cada 5 minutos mientras los flags almacenados son válidos. Devuelve una promesa.
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. Devuelve una promesa.