Feature flags no Web SDK

Pushwoosh.featureFlags fornece ao seu site as feature flags configuradas para o aplicativo no Painel de controle. O Pushwoosh avalia as regras da flag no servidor para o dispositivo e o usuário atuais, e o SDK retorna o resultado: se a flag está ativada para este visitante e quais valores de propriedades se aplicam.

Recurso beta

As feature flags estão em beta e disponíveis apenas nos planos que as incluem. Em outros planos, o servidor não retorna nenhuma flag, então cada flag recorre ao valor padrão que você passa no código.

Pré-requisitos

• Web SDK 3.94.1 ou posterior, carregado a partir da CDN do Pushwoosh conforme descrito no guia do Web SDK 3.0, ou o pacote npm web-push-notifications 3.95.0 ou posterior.
• Pelo menos uma flag criada em Audience → Feature Flags. Você precisa da sua Key e das chaves e tipos das suas propriedades. Use as chaves exatamente como aparecem lá, incluindo maiúsculas e minúsculas. Por exemplo, get('New_Checkout') não encontra uma flag com a chave new_checkout.

Ler uma flag

Leia as flags depois que o SDK estiver pronto. Sempre passe um valor padrão: ele se aplica até que o SDK tenha flags para a página e sempre que a flag não existir, estiver arquivada ou o plano não incluir feature flags.

Pushwoosh.push(() => {
  const flags = Pushwoosh.featureFlags;

  const render = () => {
    const checkout = flags.get('new_checkout');
    if (checkout && checkout.enabled) {
      showNewCheckout({
        buttonColor: checkout.getString('button_color', 'blue'),
        maxItems: checkout.getNumber('max_items', 3),
      });
    } else {
      showOldCheckout();
    }
  };

  render();
  flags.addUpdateListener(render);
});

Com o pacote npm, use a instância de Pushwoosh que você criou:

import { Pushwoosh } from 'web-push-notifications';

const pushwoosh = new Pushwoosh();
pushwoosh.push(['init', { applicationCode: 'XXXXX-XXXXX' /* ... */ }]);

pushwoosh.push(() => {
  const isNewCheckout = pushwoosh.featureFlags.isEnabled('new_checkout', false);
  // ...
});

O SDK não faz solicitações de flags em uma página até que seu código chame pela primeira vez get(), isEnabled(), refresh() ou addUpdateListener(), portanto páginas que não usam flags não geram tráfego extra.

O que uma flag retorna

get(key) retorna um objeto FeatureFlag, ou null quando o SDK ainda não tem flags para a página ou a flag não está na resposta. Uma flag arquivada não está na resposta. O objeto tem estes campos:

Campo	Tipo	Descrição
key	string	A chave da flag.
enabled	boolean	Se a flag está ativada para este visitante.
ruleId	string	A regra que decidiu o resultado, por exemplo r_1a2b3c4d. default quando nenhuma regra correspondeu ao visitante, e uma string vazia quando a flag foi desligada de emergência (killed).

Leia os valores das propriedades com o getter que corresponde ao tipo da propriedade. Cada getter retorna o seu valor padrão quando a propriedade está ausente ou contém um valor de outro tipo. Quando a flag está desativada, as propriedades contêm os valores padrão definidos no Painel de controle.

Método	Retorna
getString(property, defaultValue)	O valor de uma propriedade String.
getNumber(property, defaultValue)	O valor de uma propriedade Number.
getBool(property, defaultValue)	O valor de uma propriedade Boolean.
getJson(property, defaultValue)	O valor de uma propriedade JSON, como um valor JSON já analisado.
getProperties()	Uma cópia de todos os valores de propriedades da flag.

isEnabled(key, defaultValue) é um atalho para get(key)?.enabled que retorna defaultValue quando não há flag.

Manter as flags atualizadas

O SDK armazena a última resposta no IndexedDB do navegador por até 24 horas. As flags armazenadas são válidas apenas para o User ID para o qual foram solicitadas. O SDK as atualiza:

• no primeiro uso em uma página, quando as flags armazenadas têm mais de 15 minutos ou não existem;
• a cada hora enquanto a página permanece aberta;
• depois que o dispositivo é registrado, quando as flags foram solicitadas antes do registro;
• logo após a mudança do User ID. As flags armazenadas do usuário anterior são descartadas, então um novo usuário nunca as vê.

Para reagir a novos valores, registre um listener. Ele é chamado após uma atualização que alterou o valor de alguma flag:

const onFlagsChanged = () => render();
Pushwoosh.featureFlags.addUpdateListener(onFlagsChanged);
// later
Pushwoosh.featureFlags.removeUpdateListener(onFlagsChanged);

Para solicitar as flags você mesmo, por exemplo após uma ação que pode mover o visitante para outro segmento, chame refresh(). Enquanto as flags armazenadas são válidas, ele envia no máximo uma solicitação a cada 5 minutos e é resolvido imediatamente dentro desse intervalo. A promise é rejeitada quando a solicitação falha, e as flags armazenadas continuam em uso.

try {
  await Pushwoosh.featureFlags.refresh();
} catch (error) {
  // the stored flags, or your defaults, stay in effect
}
render();

Se o Pushwoosh não conseguir identificar os segmentos do visitante a tempo, ele retorna uma resposta parcial. O SDK a usa apenas na página atual, apenas quando não tem flags armazenadas válidas, e nunca a armazena. A próxima atualização traz a resposta completa.

Quando uma flag é desligada de emergência (kill) no Painel de controle, os visitantes a recebem desativada, com os valores padrão das propriedades, na próxima atualização. Quando o SDK não consegue acessar o servidor, ele continua usando as flags armazenadas até que tenham 24 horas e, depois disso, os seus valores padrão.

Registrar impressões

Uma impressão informa ao Pushwoosh que um visitante realmente chegou ao código que uma flag controla, para que você possa comparar os visitantes que receberam o recurso com os que não receberam. Chame logImpression(key) no momento em que o visitante vê o recurso ou a sua versão antiga, tanto no ramo ativado quanto no desativado, porque os visitantes com a flag desativada são o seu grupo de comparação:

const checkout = Pushwoosh.featureFlags.get('new_checkout');
if (checkout) {
  Pushwoosh.featureFlags.logImpression('new_checkout');
}

O SDK envia o evento PW_FeatureFlagImpression com estes atributos:

Atributo	Tipo	Valor
flag_key	string	A chave da flag.
rule_id	string	A regra que decidiu o resultado, como em ruleId.
enabled	boolean	Se a flag estava ativada.

Você não precisa criar o evento com antecedência, porque o Pushwoosh adiciona PW_FeatureFlagImpression com esses atributos em Audience → Events quando a primeira impressão chega. O SDK envia uma impressão por flag, regra e estado em uma página, e ignora repetições de outras abas do mesmo navegador por 30 minutos. logImpression() nunca é rejeitado e não envia nada quando não há flag para a chave.

As impressões também permitem que profissionais de marketing criem um segmento de visitantes que chegaram à funcionalidade: o estado viu a funcionalidade (30 dias) da condição de feature flag.

Referência de métodos

Pushwoosh.featureFlags tem estes métodos:

Método	Descrição
get(key)	Retorna o FeatureFlag da chave, ou null. Lê apenas as flags armazenadas e nunca espera pela rede.
isEnabled(key, defaultValue)	Retorna se a flag está ativada, ou defaultValue quando não há flag.
refresh()	Solicita as flags, limitado a uma vez a cada 5 minutos enquanto as flags armazenadas são válidas. Retorna uma promise.
addUpdateListener(listener)	Chama listener após cada atualização que alterou o valor de uma flag.
removeUpdateListener(listener)	Remove um listener adicionado com addUpdateListener.
logImpression(key)	Envia um evento PW_FeatureFlagImpression para a regra e o estado atuais da flag. Retorna uma promise.