Feature flags

As feature flags do Kilden são booleanas ou multivariadas, segmentadas por propriedades de pessoa e coortes, liberadas por percentual de rollout e avaliadas em um serviço dedicado de baixa latência (/decide). Este guia cobre a mecânica; os métodos do SDK estão na referência do SDK.

Criando uma flag

No painel, em Feature flags do seu projeto, crie uma flag com uma key (o que você vai checar no código), segmentação opcional e um percentual de rollout. Ver flags exige ser membro do projeto; criar ou editar exige papel de admin — flags mudam o comportamento do produto, então são tratadas como configuração sensível.

Segmentação

A segmentação é uma lista de grupos de condições. Grupos se combinam com OR; condições dentro de um grupo, com AND. Nenhum grupo significa “todo mundo”.

Condições podem casar com:

• Propriedades de pessoa: plan exact "pro", company icontains "acme". Os operadores são exact e icontains (contém, sem diferenciar maiúsculas); valores não-string são comparados na sua forma textual.
• Pertencimento a coorte: a pessoa está em uma coorte. O pertencimento é pré-computado e atualizado a cada ~10 minutos — as flags não avaliam definições de coorte ao vivo.

O percentual de rollout se aplica depois que a segmentação casa: “50% dos usuários do plano pro” significa metade dos usuários que satisfazem as condições.

Para flags multivariadas, defina variantes com pesos que somem 100 (control: 50, test: 50); o valor avaliado é a key da variante como string.

Bucketing determinístico

Se um dado usuário cai dentro de um rollout é uma função pura da key da flag e do seu distinct id — um hash mapeado para [0, 100). Sem estado, sem coordenação, sem armazenamento:

• O mesmo usuário recebe o mesmo valor em toda requisição, todo SDK, todo deploy.
• Subir um rollout de 30% → 50% só adiciona usuários; ninguém que tinha a flag a perde.
• A atribuição de variante usa um hash independente, então as variantes não se correlacionam com o corte do rollout.

Um trade-off aceito: o bucket depende do distinct id, então quando identify() troca um usuário do id anônimo para o id de usuário, alguém perto da fronteira do rollout pode mudar de lado. Esse é o custo documentado da avaliação sem estado (persistir atribuições significaria escritas no hot path e divergência da config). O SDK recarrega as flags imediatamente após identify() e reset(), então o valor converge na hora.

Lendo flags na sua aplicação

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

// ou checagens pontuais:
kilden.isFeatureEnabled('new-checkout');   // false até carregar
kilden.getFeatureFlag('pricing-test');     // 'control' | 'test-b' | true | false | undefined

As flags carregam de forma assíncrona via POST {apiHost}/decide no init — não há bootstrap síncrono, então condicione a renderização dependente de flags ao onFeatureFlags. Toda resposta carrega todas as flags do projeto (as inativas como false), permitindo ao SDK distinguir “desligada” de “desconhecida”.

Você também pode chamar o /decide diretamente de código que não usa o SDK. A avaliação nunca escreve nada: person_properties na requisição sobrescreve os traits armazenados apenas para aquela avaliação.

Rastreamento de exposição

Na primeira vez que uma sessão lê uma flag, o SDK emite $feature_flag_called com $flag_key e $flag_value. O painel plota essas exposições por flag (série diária por valor, totais de 7 dias com detalhamento por variante), para você confirmar que um rollout está de fato chegando aos usuários antes de confiar nele.

Notas sobre atualização dos dados

• Mudanças na config de flags chegam ao /decide em ~10 segundos (ele serve de uma réplica em memória da tabela de flags).
• O pertencimento a coortes é materializado a cada ~10 minutos.
• Mudanças em propriedades de pessoa propagam pelo pipeline de eventos e passam por um cache curto de avaliação (~30 s). Se você precisa de um override agora, passe person_properties na requisição ao /decide.