Feature flags (SDK)

Para criação de flags, segmentação e mecânica de rollout, leia o guia de feature flags. Esta página é a superfície do SDK.

Lendo flags

// Checagem booleana — false até as flags carregarem, false para chaves desconhecidas
if (kilden.isFeatureEnabled('new-checkout')) {
  renderNewCheckout();
}

// Valor completo — flag booleana ou a chave da variante de uma flag multivariada
const variant = kilden.getFeatureFlag('pricing-test'); // true | false | "variant-b" | undefined

isFeatureEnabled(key: string): boolean;
getFeatureFlag(key: string): boolean | string | undefined;

As flags carregam de POST {apiHost}/decide no init e ficam em cache em memória durante a sessão. Nenhum dos getters bloqueia:

• isFeatureEnabled retorna false até as flags carregarem.
• getFeatureFlag retorna undefined até as flags carregarem — assim você distingue “desligada” (false) de “ainda não carregou” (undefined). Toda flag do projeto volta em cada resposta (as inativas como false), então uma chave ausente após o carregamento significa que a flag não existe.

onFeatureFlags()

kilden.onFeatureFlags((flags) => {
  // flags: Record<string, boolean | string>
  setupUi(flags['new-checkout'] === true);
});

O callback dispara quando as flags carregam pela primeira vez, em cada recarregamento, e imediatamente se você se inscrever depois de elas já terem carregado. Use-o para evitar renderizar antes de as flags serem conhecidas.

Quando as flags recarregam

As flags recarregam automaticamente após identify() e reset() — a avaliação depende do distinct id, então o SDK converge de imediato para os valores do novo id. Como o bucketing faz hash do distinct id, um usuário perto do limite de um rollout pode legitimamente trocar de lado ao passar de anônimo para identificado; veja o guia para entender o porquê.

Não há opção de bootstrap: a primeira avaliação de um carregamento de página é sempre uma chamada assíncrona a /decide. Condicione a UI dependente de flags a onFeatureFlags em vez de presumir valores na inicialização.

Eventos de exposição

O primeiro acesso a uma flag por sessão — por qualquer um dos getters — emite um evento $feature_flag_called com $flag_key e $flag_value, que alimenta os gráficos de exposição no painel. A deduplicação é chaveada por $session_id e sobrevive a reloads da página; ela é zerada quando a sessão rotaciona. Chaves de flags desconhecidas não emitem nada.

Com opt-out ativo, /decide não é chamado; os valores em cache continuam respondendo.