Fazer rollout de uma flag para 10% dos usuários e aumentar com segurança

Este tutorial agenda um rollout que começa em 10% de exposição e avança a partir daí, explica a matemática de bucketing que mantém o resultado de um mesmo usuário estável entre os estágios, e mostra como intervir se um estágio não estiver saindo como esperado.

1. Agende um rollout começando em 10%

Um rollout fica atrelado à configuração de um ambiente da flag, não à flag em si, então ele é criado com POST /v1/environment-flag-configs/{environment_flag_config_id}/rollouts. O environment_flag_config_id é o id retornado quando você faz o PUT da configuração da flag naquele ambiente (veja "Criar uma feature flag"). A configuração não pode ter regras manuais nem outro rollout agendado ou ativo quando você cria este.

Um rollout é uma lista de estágios, cada um com um target_percentage e um horário activate_at. Os percentuais precisam crescer estritamente e o último estágio precisa chegar a 100:

const res = await fetch(
  `https://api.rollfuse.com/v1/environment-flag-configs/${environmentFlagConfigId}/rollouts`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      target_variation_id: onVariationId,
      stages: [
        { target_percentage: 10, activate_at: "2026-09-06T12:00:00Z" },
        { target_percentage: 50, activate_at: "2026-09-08T12:00:00Z" },
        { target_percentage: 100, activate_at: "2026-09-10T12:00:00Z" },
      ],
    }),
  }
);
const rollout = await res.json();
console.log(rollout.id, rollout.state); // "scheduled"

O rollout começa no estado scheduled e passa a active conforme seus estágios disparam. Você pode conferir o estado atual, e qual foi o último estágio aplicado, com GET /v1/rollouts/{rollout_id}:

const check = await fetch(`https://api.rollfuse.com/v1/rollouts/${rollout.id}`, {
  headers: { Authorization: `Bearer ${token}` },
});
const current = await check.json();
console.log(current.state, current.last_applied_stage_position);

2. Por que o mesmo usuário fica do mesmo lado conforme o percentual sobe

O @rollfuse/sdk-js exporta uma função bucket(), que é exatamente a mesma função determinística que a plataforma usa para decidir quem entra em um determinado percentual de rollout:

import { bucket, BUCKET_MODULUS } from "@rollfuse/sdk-js";

const b = bucket("new-checkout-flow", "user-42");
console.log(b, BUCKET_MODULUS); // ex: 3821 10000

bucket(flagKey, subjectKey) calcula o hash de flagKey + ":" + subjectKey com FNV-1a e reduz o resultado módulo BUCKET_MODULUS (10000), o que dá granularidade de 0,01%. Um estágio em 10% inclui todo subject cujo valor de bucket seja menor que 1000 em 10000. Como o hash depende só da chave da flag e da chave do subject, o valor de bucket de um usuário nunca muda para aquela flag entre os estágios. É isso que impede o rollout de alternar usuários para dentro e para fora conforme ele avança: passar de um estágio de 10% para um de 50% só adiciona usuários, nunca remove quem já estava incluído.

function isIncludedAtPercentage(flagKey, subjectKey, percentage) {
  return bucket(flagKey, subjectKey) < (percentage / 100) * BUCKET_MODULUS;
}

isIncludedAtPercentage("new-checkout-flow", "user-42", 10); // false, se b = 3821
isIncludedAtPercentage("new-checkout-flow", "user-42", 50); // true, já que 3821 < 5000

3. Intervenha no meio do rollout se algo parecer errado

Você não edita o percentual de um estágio depois que ele foi criado; em vez disso, controla o ciclo de vida do rollout diretamente:

• POST /v1/rollouts/{rollout_id}/pause congela o rollout no percentual atual.
• POST /v1/rollouts/{rollout_id}/resume retoma um rollout pausado.
• POST /v1/rollouts/{rollout_id}/abort encerra o rollout antes de chegar a 100%.

await fetch(`https://api.rollfuse.com/v1/rollouts/${rollout.id}/pause`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
});

Se você quiser que isso aconteça automaticamente em vez de manualmente, veja o tutorial de rollback automático por guardrail: anexar um guardrail a esse mesmo rollout permite que uma métrica que viole o limite pause ou aborte o rollout por conta própria.

4. Confirme no código da aplicação

A avaliação pelo @rollfuse/sdk-js já reflete o estágio atual do rollout automaticamente; você não calcula buckets no código da aplicação, só quando quer raciocinar sobre o comportamento do rollout ou testá-lo offline:

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

Próximo passo

Um rollout em estágios trata todo subject igual em cada percentual. Se você precisa priorizar um grupo específico antes de todo mundo, por exemplo clientes enterprise antes dos demais, isso é uma regra de targeting na configuração da flag, coberta no tutorial de targeting com segmentos, já que uma configuração com regras manuais não pode ter um rollout percentual ao mesmo tempo.