Feature flags no SDK para Android

Pushwoosh.getInstance().featureFlags fornece ao seu aplicativo Android 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 dispositivo e quais valores de propriedades se aplicam.

Pré-requisitos

Pushwoosh Android SDK 6.16.0 ou posterior, integrado conforme descrito no guia do SDK para Android. As feature flags fazem parte da biblioteca principal com.pushwoosh:pushwoosh, então você não precisa adicionar outra dependência. Até que o SDK seja inicializado, get retorna null.
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

Sempre passe um valor padrão. Ele se aplica até que o SDK tenha flags para o dispositivo e sempre que a flag não existir, estiver arquivada ou o plano não incluir feature flags.

import com.pushwoosh.Pushwoosh

val flags = Pushwoosh.getInstance().featureFlags

val checkout = flags.get("new_checkout")
if (checkout != null && checkout.isEnabled) {
    showNewCheckout(
        buttonColor = checkout.getString("button_color", "blue"),
        maxItems = checkout.getNumber("max_items", 3.0).toInt(),
    )
} else {
    showOldCheckout()
}

Para verificar apenas se a flag está ativada, use isEnabled:

val isNewCheckout = Pushwoosh.getInstance().featureFlags.isEnabled("new_checkout", false)

Em Java, chame Pushwoosh.getInstance().getFeatureFlags().

O que uma flag retorna

get(key) retorna um objeto FeatureFlag, ou null quando o SDK ainda não tem flags para o dispositivo ou a flag não está na resposta. Uma flag arquivada não está na resposta. get lê apenas as flags armazenadas e nunca espera pela rede. O objeto tem estes campos:

Campo	Tipo	Descrição
`key`	String	A chave da flag.
`isEnabled`	Boolean	Se a flag está ativada para este dispositivo.
`ruleId`	String	A regra que decidiu o resultado, por exemplo `r_1a2b3c4d`. `default` quando nenhuma regra correspondeu ao dispositivo, 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, como `Double`.
`getBool(property, defaultValue)`	O valor de uma propriedade Boolean.
`getJsonObject(property, defaultValue)`	O valor de uma propriedade JSON que contém um objeto, como `JSONObject`.
`getJsonArray(property, defaultValue)`	O valor de uma propriedade JSON que contém um array, como `JSONArray`.

isEnabled(key, defaultValue) retorna defaultValue quando get(key) retorna null.

Manter as flags atualizadas

O SDK armazena a última resposta no dispositivo 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:

Quando uma sessão começa, ou seja, quando o aplicativo vem para o primeiro plano pela primeira vez ou depois de pelo menos 30 minutos em segundo plano.
A cada hora enquanto o aplicativo está em primeiro plano.
Depois que o dispositivo é registrado pela primeira vez.
Logo após a mudança do User ID com setUserId. 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:

import com.pushwoosh.featureflags.FeatureFlagsUpdateListener

private val flagsListener = FeatureFlagsUpdateListener { render() }

override fun onStart() {
    super.onStart()
    Pushwoosh.getInstance().featureFlags.addUpdateListener(flagsListener)
}

override fun onStop() {
    Pushwoosh.getInstance().featureFlags.removeUpdateListener(flagsListener)
    super.onStop()
}

Para solicitar as flags você mesmo, por exemplo após uma ação que pode mover o usuário 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, dentro desse intervalo, responde com as flags armazenadas. O callback é executado na thread principal:

Pushwoosh.getInstance().featureFlags.refresh { result ->
    if (!result.isSuccess) {
        val status = result.exception?.httpStatus
        // the stored flags, or your defaults, stay in effect
    }
    render()
}

Em caso de falha, result.exception é uma FeatureFlagsException. O seu httpStatus é 0 quando a solicitação não obteve resposta HTTP, e 200 quando o servidor respondeu, mas a resposta não pôde ser usada.

Se o Pushwoosh não conseguir identificar os segmentos do dispositivo a tempo, ele retorna uma resposta parcial. O SDK não a armazena, e a próxima atualização traz a resposta completa.

Quando uma flag é desligada de emergência (kill) no Painel de controle, os dispositivos 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 usuário realmente chegou ao código que uma flag controla, para que você possa comparar os usuários que receberam o recurso com os que não receberam. Chame logImpression(key) no momento em que o usuário vê o recurso ou a sua versão antiga, tanto no ramo ativado quanto no desativado, porque os usuários com a flag desativada são o seu grupo de comparação:

val flags = Pushwoosh.getInstance().featureFlags
val isOn = flags.isEnabled("new_checkout", false)
flags.logImpression("new_checkout")
if (isOn) {
    showNewCheckout()
} else {
    showOldCheckout()
}

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 sessão, e não envia nada quando não há flag para a chave.

As impressões também permitem que as equipes de marketing criem um segmento de usuários que chegaram ao recurso: o estado viu a funcionalidade (30 dias) da condição de feature flag.

Referência de métodos

Pushwoosh.getInstance().featureFlags tem estes métodos:

Método	Descrição
`get(key)`	Retorna o `FeatureFlag` da chave, ou `null`. Lê apenas as flags armazenadas.
`isEnabled(key, defaultValue)`	Retorna se a flag está ativada, ou `defaultValue` quando não há flag.
`refresh(callback)`	Solicita as flags, limitado a uma vez a cada 5 minutos enquanto as flags armazenadas são válidas. O callback recebe um `Result` com uma `FeatureFlagsException` em caso de falha, e pode ser `null`.
`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.