Feature flags

Uma feature flag é um interruptor liga/desliga para um recurso do seu aplicativo ou site. Você a alterna no Control Panel, sem uma nova versão.

Para cada flag, você escolhe quem recebe o recurso: os usuários de um segmento, uma porcentagem de todos os usuários ou ambos. Por exemplo, mostre uma nova tela primeiro para 10% dos usuários e depois aumente a porcentagem. Se algo der errado, você pode desativar o recurso para todos com o botão Desligar para todos. Uma flag também pode carregar propriedades, como a cor de um botão ou um limite de desconto, que você define para cada público.

Recurso beta

As feature flags estão em beta. Sites e aplicativos móveis podem ler as flags com o Web SDK, o Android SDK e o iOS SDK.

Antes de começar

• Plano: as feature flags estão disponíveis apenas nos planos que as incluem. Em outros planos, Feature flags não aparece no menu Público. Para ativá-las, entre em contato com seu gerente de conta.
• Acesso: Feature flags aparece em todos os aplicativos que você pode ver. Para criar e alterar flags, você precisa da permissão Modificar aplicativos ou da mesma permissão para este aplicativo nas suas permissões específicas do aplicativo.
• Configuração pelos desenvolvedores: uma flag afeta os usuários somente depois que seus desenvolvedores a leem no código do aplicativo ou do site pela chave. Eles precisam do Web SDK 3.94.1 ou posterior, do Android SDK 6.16.0 ou posterior, ou do iOS SDK 7.2.10 ou posterior. Em um aplicativo que ainda não tem flags, a página Feature flags mostra exemplos de código prontos para Web, Android e iOS. Entregue-os aos seus desenvolvedores junto com a chave da flag. Compartilhe com eles o guia do Web SDK, o guia do Android SDK ou o guia do iOS SDK.

Se o seu plano deixar de incluir feature flags, os dispositivos param de receber as flags e o seu aplicativo ou site usa os valores definidos no próprio código. A criação ou restauração de uma flag passa então a falhar com a mensagem Feature flags não estão disponíveis no seu plano, por exemplo em uma aba do Control Panel que foi aberta antes da mudança de plano.

Como uma flag decide o que cada usuário recebe

Toda flag tem uma lista de regras. Cada regra tem um segmento, uma porcentagem de usuários que recebem a flag ativada (Lançamento, %) e valores de propriedades opcionais. Para cada dispositivo, o Pushwoosh verifica as regras de cima para baixo:

1. Decide a primeira regra cujo segmento corresponde ao dispositivo. Uma regra sem segmento corresponde a todos os dispositivos.
2. O Lançamento, % da regra decide se este usuário recebe a flag ativada. Com 20%, dois em cada dez usuários a recebem.
3. Um usuário que recebe a flag ativada recebe os valores de propriedades definidos nessa regra. Um usuário que a recebe desativada recebe os valores de propriedades padrão.

Depois que um dispositivo corresponde a uma regra, as regras seguintes são ignoradas, mesmo quando essa regra desativa a flag para ele. Um dispositivo que não corresponde a nenhuma regra recebe a flag desativada.

Um usuário recebe o mesmo resultado em todas as visitas. Dispositivos conectados com o mesmo User ID recebem o mesmo resultado quando correspondem à mesma regra, porque o Pushwoosh verifica os segmentos para cada dispositivo. O Pushwoosh identifica um usuário pelo User ID ou, quando nenhum User ID está definido, pelo ID do dispositivo. Quando você aumenta a porcentagem, os usuários que já têm a flag a mantêm e novos usuários se juntam a eles.

Criar uma flag

1. Acesse Público → Feature flags.

2. Clique em Criar feature flag.

   

3. Insira a Chave, por exemplo new_checkout. A chave é qualquer nome que você escolher, mas seus desenvolvedores leem a flag no código exatamente por essa chave, incluindo maiúsculas e minúsculas. Combine-a com eles antes de salvar a flag.

4. Insira um Nome e, opcionalmente, uma Descrição para que sua equipe saiba o que a flag controla.

A chave segue estas regras:

• Letras latinas, dígitos, _, . e -, até 58 caracteres.
• Não é possível alterar a chave depois.
• Não é possível reutilizar uma chave que outra flag do aplicativo já tenha, mesmo arquivada, nem uma chave que difira dela apenas em maiúsculas e minúsculas, como New_Checkout e new_checkout.

Adicionar propriedades

Propriedades são valores que o aplicativo ou o site lê da flag, por exemplo o texto de um banner ou o número de itens em um bloco de recomendações. Pule esta etapa se a flag apenas liga e desliga um recurso.

1. Em Propriedades, clique em Adicionar propriedade.
2. Insira a Chave da propriedade, por exemplo button_color. Use letras latinas, dígitos e _, até 64 caracteres. A chave da propriedade é qualquer nome que você escolher, mas seus desenvolvedores leem o valor no código exatamente por essa chave, incluindo maiúsculas e minúsculas. Combine-a com eles antes de salvar a flag.
3. Escolha o tipo: Texto, Número, Booleano ou JSON. Não é possível alterar o tipo depois de salvar a flag.
4. Insira o Valor padrão. Os usuários que recebem a flag desativada recebem esse valor.

Uma flag pode ter até 50 propriedades.

Adicionar regras

1. Em Regras, clique em Adicionar regra.
2. Insira um Nome da regra, por exemplo Paying customers.
3. Em Segmento, escolha a quem a regra se aplica. Deixe vazio para aplicar a regra a todos os usuários.
4. Em Lançamento, %, insira a porcentagem do segmento que recebe a flag ativada, de 0 a 100 com até duas casas decimais.
5. Em Valores para os usuários em que esta regra liga a flag, altere as propriedades que devem ser diferentes dos padrões para esses usuários. As propriedades que você não alterar mantêm seus valores padrão.
6. Para adicionar outro público, repita as etapas. Use Subir e Descer para alterar a ordem, porque decide a primeira regra correspondente.

Uma flag pode ter até 10 regras.

Abaixo de Lançamento, %, cada regra mostra para aproximadamente quantos dispositivos ela ativa a flag, por exemplo ≈ 1.200 dispositivos. O Pushwoosh multiplica o tamanho do segmento da regra pela porcentagem. Para uma regra sem segmento, ele considera todos os dispositivos do aplicativo. Leia o número como o máximo que a regra pode alcançar, porque um dispositivo que corresponde a uma regra anterior para nela.

Segmentos que uma regra pode usar

Um segmento de regra pode conter apenas condições de tag, localização, aplicativo e lista, porque o Pushwoosh verifica a flag toda vez que um dispositivo a solicita. Segmentos com condições de evento, estáticas, externas, de última atualização ou de melhor horário de envio não aparecem no seletor de segmentos. Uma regra também não pode usar um segmento com uma condição de feature flag, porque uma flag não pode depender de outra. Salvar uma flag assim falha.

Por exemplo, para oferecer um novo checkout a todos os clientes pagantes e a 20% de todos os demais, crie duas regras:

Regra	Segmento	Lançamento, %	Valores para os usuários em que esta regra liga a flag
Paying customers	Purchased something	100	button_color = green, show_apple_pay = true
Everyone else	—	20	button_color = orange

Salvar a flag

Clique em Salvar. A flag é criada como Ativo, e os dispositivos a recebem na próxima vez que verificarem as flags.

Gerenciar flags

A lista de flags mostra o nome, a chave, o status, o número de regras e o horário da última atualização de cada flag. Para ver as flags arquivadas, ative Mostrar arquivados. Para abrir uma flag, clique no nome dela. O bloco Suporte no SDK no topo da lista e de cada flag mostra a parcela de dispositivos do aplicativo com um SDK mais antigo, quando esses dispositivos informam a versão do SDK. Esses dispositivos não recebem flags até que os usuários atualizem o aplicativo.

Uma flag tem um de três status:

Status	O que os usuários recebem	Ações
Ativo	A flag funciona de acordo com suas regras.	Reembaralhar, Desligar para todos, Arquivar
Desligado	A flag está desativada para todos os usuários, com os valores de propriedades padrão. As regras e propriedades são mantidas.	Ligar novamente, Arquivar
Arquivado	Os dispositivos não recebem mais a flag, então o código usa os valores que seus desenvolvedores definiram nele.	Restaurar

Alterar uma flag

1. Abra a flag.
2. Edite o nome, a descrição, as propriedades ou as regras.
3. Clique em Salvar.
4. Se você alterou as regras ou os valores de propriedades padrão, a caixa de diálogo Revise as alterações lista o que acontece com os dispositivos. Verifique-a e clique em Salvar.

A caixa de diálogo mostra uma linha por alteração:

• Lançamento de uma regra: aproximadamente quantos dispositivos a mais recebem a flag, ou quantos a perdem.
• Valores de uma regra: aproximadamente quantos dispositivos recebem os novos valores, e o valor antigo e o novo de cada propriedade.
• Regra nova ou removida, um segmento diferente ou uma nova ordem das regras: para onde os dispositivos vão. Por exemplo, os dispositivos de uma regra removida passam para a próxima regra que corresponde a eles.
• Valores padrão: os valores antigos e novos que os dispositivos com a flag desativada recebem.

Alterações apenas no nome ou na descrição são salvas sem a caixa de diálogo.

Para liberar um recurso gradualmente, aumente o Lançamento, % de uma regra passo a passo.

Se outra pessoa salvou a flag enquanto você a editava, o Control Panel não sobrescreve as alterações dela e pede que você recarregue a flag. Clique em Recarregar e faça suas alterações novamente.

Desativar uma flag para todos

Use Desligar para todos quando um recurso causar problemas e você precisar interrompê-lo para todos:

1. Abra a flag e clique em Desligar para todos.

   

2. Confirme. Cada dispositivo recebe a flag desativada com os valores de propriedades padrão na próxima vez que verificar as flags.

Enquanto seu site ou aplicativo estiver aberto, os dispositivos recebem a alteração em até uma hora. Veja como o Web SDK, o Android SDK e o iOS SDK verificam as flags.

Para reativar a flag com as regras como estavam, clique em Ligar novamente.

Escolher outra amostra de usuários

Reembaralhar coloca cada usuário em um novo grupo, de modo que a mesma porcentagem de usuários passa a ser formada por pessoas diferentes. Use quando quiser uma amostra nova, por exemplo para iniciar um novo teste.

1. Abra uma flag ativa e clique em Reembaralhar.
2. Confirme. Alguns usuários que têm a flag ativada a perdem e outros a recebem na próxima vez que seus dispositivos verificarem as flags, enquanto as porcentagens permanecem as mesmas.

Arquivar e restaurar uma flag

Arquive uma flag quando o recurso estiver totalmente liberado ou removido do código. Uma flag arquivada não conta para o limite de flags por aplicativo do seu plano, e sua chave continua reservada.

1. Abra a flag e clique em Arquivar.
2. Confirme.

Uma flag arquivada não pode ser editada. Para trazê-la de volta, ative Mostrar arquivados na lista, abra a flag e clique em Restaurar. Uma flag restaurada volta como Desligado, então não chega aos usuários sozinha. Clique em Ligar novamente quando estiver pronto.

Ver quem alterou uma flag

O histórico de alterações mostra cada versão salva de uma flag: o que mudou, quem mudou e quando. Qualquer pessoa que possa abrir a flag pode ver o histórico dela.

O histórico é registrado para alterações a partir de 13 de outubro de 2026. Uma flag sem alterações registradas mostra Ainda não há alterações. Para uma flag criada antes dessa data, a entrada mais antiga não mostra uma lista de alterações, porque não há uma versão anterior com a qual compará-la.

1. Abra a flag.
2. Clique em Histórico.

O painel Histórico de alterações lista as versões da flag, das mais recentes para as mais antigas. Cada entrada mostra:

• A ação, por exemplo Editado.
• Quem fez a alteração: o e-mail do usuário ou o token de API pelo qual a alteração chegou, por exemplo Token de API “Release pipeline”, ou Token de API para um token sem nome.
• A data e a hora.
• O número da versão, por exemplo v4.

Para carregar entradas anteriores, clique em Mostrar mais.

Ação	O que aconteceu
Criado	A flag foi criada.
Editado	Alguém salvou alterações na flag.
Implantação alterada	O lançamento de uma regra foi alterado pela API ou pelo servidor MCP. No Control Panel, uma alteração de lançamento é salva como Editado.
Desativado	Alguém clicou em Desligar para todos.
Reativado	Alguém clicou em Ligar novamente.
Arquivado	A flag foi arquivada.
Restaurado	A flag foi restaurada do arquivo.
Usuários redistribuídos	Alguém clicou em Reembaralhar.

Abaixo de cada entrada, o painel lista o que mudou, como valor antes e depois: Nome, Descrição, Status, Propriedades, Ordem das regras e cada regra adicionada, removida ou alterada. Para uma regra alterada, ele mostra apenas os campos que diferem: nome, Segmento, Implantação ou Valores. Uma regra sem segmento mostra Todos os usuários.

Segmentar usuários por flag

Uma condição de feature flag em um segmento encontra os dispositivos que receberam uma flag ativada, que a receberam desativada, que corresponderam a uma de suas regras ou que chegaram à parte do aplicativo que a flag controla. Use-a para enviar mensagens aos usuários que veem um novo recurso, por exemplo para pedir feedback, ou para criar uma jornada em torno deles.

1. Abra o construtor de segmentos, conforme descrito em Como criar segmentos.
2. Clique em Feature flag na lista de condições.
3. Em Selecione um feature flag…, escolha a flag. Flags arquivadas não aparecem na lista.
4. Escolha o estado:
   • está ativado: dispositivos que receberam a flag ativada.
   • está desativado: dispositivos que receberam a flag desativada.
   • está na regra: dispositivos que corresponderam ao segmento de uma regra, independentemente de o Lançamento, % da regra ter ativado a flag para eles. Escolha a regra em Selecione uma regra….
   • viu a funcionalidade (30 dias): dispositivos que enviaram pelo menos uma impressão da flag nos últimos 30 dias, ou seja, o aplicativo chamou logImpression para a chave dessa flag. Veja Encontrar usuários que chegaram a um recurso.

Feature flag aparece no construtor de segmentos apenas nos planos que incluem feature flags. Segmentos High Speed Delivery, que só podem conter condições de tag, não podem usá-la.

Quais dispositivos estão em cada estado

O estado de um dispositivo acompanha as flags que ele recebeu por último e o status atual da flag:

• Um dispositivo que nunca solicitou a flag, por exemplo porque o SDK dele não lê flags, não está em nenhum dos estados.
• Depois que você altera as regras ou o Lançamento, % de uma regra, um dispositivo passa para outro estado apenas quando solicita as flags novamente.
• Quando você desliga ou arquiva a flag, está ativado e está na regra ficam vazios em cerca de 10 segundos, sem esperar que os dispositivos solicitem as flags novamente. está desativado passa então a conter todos os dispositivos que já receberam a flag.

Encontrar usuários que chegaram a um recurso

Para encontrar usuários que viram o recurso ativado:

1. Adicione viu a funcionalidade (30 dias) para a flag.
2. Adicione está ativado para a mesma flag e una as duas condições com AND.

viu a funcionalidade (30 dias) corresponde aos usuários que chegaram à tela ou ao código que a flag controla, estivesse a flag ativada ou desativada para eles. Por isso você adiciona está ativado: ela mantém apenas os usuários que receberam a nova versão. O resultado é próximo, mas não exato. está ativado reflete a flag que um dispositivo recebeu por último, e a impressão dele pode vir de uma visita anterior em que a flag estava desativada.

O segmento fica vazio quando o aplicativo não registra impressões. Para registrá-las, consulte Log impressions no guia do Web SDK, do Android SDK ou do iOS SDK.

Desligar ou arquivar a flag não esvazia esse estado. Um dispositivo sai dele 30 dias após a última impressão.

Usar segmentos de flag em jornadas

Um segmento com uma condição de feature flag funciona em uma Entrada baseada em público e em uma Divisão por condição. Por exemplo, separe os usuários que receberam um novo checkout dos que não receberam e envie a cada grupo sua própria mensagem.

Limites

O Control Panel e a API aplicam estes limites ao salvar uma flag:

Limite	Valor
Regras por flag	10
Propriedades por flag	50
Tamanho das propriedades de uma flag (chaves, tipos e valores padrão)	10.000 bytes
Profundidade de aninhamento de um valor JSON	5 níveis
Flags por aplicativo	Definido pelo seu plano; flags arquivadas não contam
Dados que um dispositivo recebe para todas as flags do aplicativo	64 KB

Gerenciar flags pela API

Seus desenvolvedores podem criar e alterar flags a partir dos próprios sistemas com a Feature Flags API, e assistentes de IA conectados pelo servidor MCP da Pushwoosh podem gerenciar flags com as mesmas operações.