Feature flags

Los feature flags de Kilden son booleanos o multivariantes, se segmentan por properties de persona y cohortes, se despliegan por porcentaje, y se evalúan en un servicio dedicado de baja latencia (/decide). Esta guía cubre la mecánica; los métodos del SDK están en la referencia del SDK.

Crear un flag

En el panel, dentro de Feature flags de tu proyecto, crea un flag con una key (lo que vas a chequear en código), targeting opcional, y un porcentaje de rollout. Ver los flags requiere ser miembro del proyecto; crearlos o editarlos requiere rol de admin — los flags cambian el comportamiento del producto, así que son de nivel configuración.

Targeting

El targeting es una lista de grupos de condiciones. Los grupos se combinan con OR; las condiciones dentro de un grupo, con AND. Sin grupos significa “todos”.

Las condiciones pueden coincidir con:

Properties de persona: plan exact "pro", company icontains "acme". Los operadores son exact e icontains (contiene, sin distinguir mayúsculas); los valores no string se comparan en su forma de texto.
Pertenencia a cohortes: la persona está en una cohorte. La pertenencia se precomputa y se refresca aproximadamente cada 10 minutos — los flags no evalúan definiciones de cohortes en vivo.

El porcentaje de rollout aplica después de que el targeting coincide: “50% de los usuarios del plan pro” significa la mitad de los usuarios que cumplen las condiciones.

Para flags multivariantes, define variantes con pesos que sumen 100 (control: 50, test: 50); el valor evaluado es la key de la variante como string.

Bucketing determinístico

Que un usuario dado caiga dentro de un rollout es una función pura de la key del flag y su distinct id — un hash mapeado a [0, 100). Sin estado, sin coordinación, sin almacenamiento:

El mismo usuario obtiene el mismo valor en cada request, cada SDK, cada deploy.
Subir un rollout de 30% → 50% solo agrega usuarios; nadie que tenía el flag lo pierde.
La asignación de variante usa un hash independiente, así que las variantes no se correlacionan con el corte del rollout.

Un trade-off aceptado: el bucket depende del distinct id, así que cuando identify() cambia a un usuario de su id anónimo a su id de usuario, alguien cerca del borde del rollout puede cambiar de lado. Este es el costo documentado de la evaluación sin estado (persistir asignaciones significaría escrituras en el hot path y deriva respecto de la config). El SDK recarga los flags inmediatamente después de identify() y reset() para que el valor converja de inmediato.

Leer flags en tu app

kilden.onFeatureFlags((flags) => {
  render(flags['new-checkout'] === true);
});

// o chequeos puntuales:
kilden.isFeatureEnabled('new-checkout');   // false hasta que carguen
kilden.getFeatureFlag('pricing-test');     // 'control' | 'test-b' | true | false | undefined

Los flags cargan de forma asíncrona desde POST {apiHost}/decide en el init — no hay bootstrap síncrono, así que condiciona el rendering dependiente de flags a onFeatureFlags. Cada respuesta trae todos los flags del proyecto (los inactivos como false), lo que permite al SDK distinguir “apagado” de “desconocido”.

También puedes llamar a /decide directamente desde código que no usa el SDK. La evaluación nunca escribe nada: person_properties en la request sobreescribe los traits guardados solo para esa evaluación.

Tracking de exposiciones

La primera vez que una sesión lee un flag, el SDK emite $feature_flag_called con $flag_key y $flag_value. El panel grafica estas exposiciones por flag (serie diaria por valor, totales a 7 días con desglose por variante), para que puedas confirmar que un rollout realmente está llegando a los usuarios antes de confiar en él.

Notas sobre frescura

Los cambios de config de flags llegan a /decide en ~10 segundos (sirve desde una réplica en memoria de la tabla de flags).
La pertenencia a cohortes se materializa aproximadamente cada 10 minutos.
Los cambios de properties de persona se propagan por el pipeline de eventos, más un cache corto de evaluación (~30 s). Si necesitas un override ahora, pasa person_properties en la request a /decide.