Criar uma feature flag e ler o valor dela na sua aplicação

Este tutorial cobre o ciclo completo para uma flag nova: criar com suas variações, configurar em um ambiente e depois avaliar a partir do código da aplicação.

1. Crie a flag com suas variações

Uma feature flag pertence a um projeto, não a um único ambiente, e é criada junto com suas variações: POST /v1/projects/{project_id}/feature-flags exige pelo menos duas.

const res = await fetch(
  `https://api.rollfuse.com/v1/projects/${projectId}/feature-flags`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "New Checkout Flow",
      key: "new-checkout-flow",
      variations: [
        { key: "on", value: true },
        { key: "off", value: false },
      ],
    }),
  }
);
const flag = await res.json();
console.log(flag.id, flag.key);
// flag.variations = [{ id, key: "on", value: true }, { id, key: "off", value: false }]

O token aqui é um token de sessão ou uma API key com um papel que tenha permissão para gerenciar feature flags no projeto. O key é o identificador que o código da sua aplicação referencia na avaliação; o id de cada variação é o que a configuração de ambiente do próximo passo vai apontar.

Nesse ponto a flag já existe, mas ainda não tem configuração por ambiente, então qualquer avaliação vai cair no valor de fallback passado na chamada de avaliação.

2. Ative em um ambiente

As flags são configuradas por ambiente, então uma flag pode estar ativa em staging e intocada em production ao mesmo tempo. Defina (ou substitua) essa configuração com PUT /v1/environments/{environment_id}/feature-flags/{feature_flag_id}/config, apontando default_variation_id para a variação retornada como "on":

const onVariationId = flag.variations.find((v) => v.key === "on").id;

const configRes = await fetch(
  `https://api.rollfuse.com/v1/environments/${environmentId}/feature-flags/${flag.id}/config`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      enabled: true,
      default_variation_id: onVariationId,
      rules: [],
    }),
  }
);
const config = await configRes.json();

Repare que é um PUT, não um PATCH: ele substitui por completo a configuração da flag naquele ambiente, incluindo o array rules. Um rules vazio significa que todo subject recebe default_variation_id. Se depois você adicionar regras de targeting ou um rollout percentual sobre essa configuração, você estará atualizando esse mesmo recurso, não criando um novo.

3. Leia a flag no código da aplicação

A avaliação acontece pelo @rollfuse/sdk-js, que lê de um snapshot local sincronizado, e não faz uma chamada REST a cada avaliação:

import { RollfuseClient } from "@rollfuse/sdk-js";

const client = new RollfuseClient({
  baseUrl: "https://api.rollfuse.com",
  credential: process.env.ROLLFUSE_CREDENTIAL!, // set before running
});
await client.start();

const result = client.evaluate("user-42", "new-checkout-flow", {
  attributes: { plan: "pro" },
  fallback: false,
});

console.log(result.value); // true, assim que a config do passo anterior estiver no ar
console.log(result.reason); // por que esse valor foi retornado
console.log(result.variation_key); // "on"

O credential aqui é uma credencial de ambiente própria do SDK, diferente do token usado contra a REST API nos dois passos anteriores. A REST API é o meio pelo qual você administra flags; o SDK é o meio pelo qual a sua aplicação em produção as lê.

Se você precisar do valor de todas as flags para um mesmo subject de uma vez, em vez de uma flag por vez, use client.evaluateAll("user-42", { attributes: { plan: "pro" } }), que retorna o mesmo formato indexado pela chave de cada flag.

Próximo passo

Depois que uma flag lê corretamente a 100% em um ambiente, o próximo passo geralmente não é "ligar para todo mundo de uma vez": veja o tutorial de rollout percentual para aumentar a exposição de forma gradual com bucketing determinístico.