Feature flags dans le SDK Android

Pushwoosh.getInstance().featureFlags fournit à votre application Android les feature flags configurés pour l’application dans le Control Panel. Pushwoosh évalue les règles du flag sur le serveur pour l’appareil et l’utilisateur actuels, et le SDK renvoie le résultat : si le flag est activé pour cet appareil et quelles valeurs de propriétés s’appliquent.

Prérequis

Pushwoosh Android SDK 6.16.0 ou version ultérieure, intégré comme décrit dans le guide du SDK Android. Les feature flags font partie de la bibliothèque principale com.pushwoosh:pushwoosh : vous n’avez donc pas besoin d’ajouter une autre dépendance. Tant que le SDK n’est pas initialisé, get renvoie null.
Au moins un flag créé dans Audience → Feature Flags. Vous avez besoin de sa Key ainsi que des clés et des types de ses propriétés. Utilisez les clés exactement telles qu’elles y apparaissent, casse comprise. Par exemple, get("New_Checkout") ne trouve pas un flag dont la clé est new_checkout.

Lire un flag

Transmettez toujours une valeur par défaut. Elle s’applique tant que le SDK n’a pas de flags pour l’appareil, ainsi que chaque fois que le flag n’existe pas, est archivé ou que le forfait n’inclut pas les 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()
}

Pour vérifier uniquement si le flag est activé, utilisez isEnabled :

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

En Java, appelez Pushwoosh.getInstance().getFeatureFlags().

Ce que renvoie un flag

get(key) renvoie un objet FeatureFlag, ou null lorsque le SDK n’a pas encore de flags pour l’appareil ou que le flag ne figure pas dans la réponse. Un flag archivé ne figure pas dans la réponse. get lit uniquement les flags stockés et n’attend jamais le réseau. L’objet possède les champs suivants :

Champ	Type	Description
`key`	String	La clé du flag.
`isEnabled`	Boolean	Indique si le flag est activé pour cet appareil.
`ruleId`	String	La règle qui a déterminé le résultat, par exemple `r_1a2b3c4d`. `default` lorsqu’aucune règle ne correspond à l’appareil, et une chaîne vide lorsque le flag est coupé (killed).

Lisez les valeurs des propriétés avec le getter correspondant au type de la propriété. Chaque getter renvoie votre valeur par défaut lorsque la propriété est absente ou contient une valeur d’un autre type. Lorsque le flag est désactivé, les propriétés contiennent les valeurs par défaut définies dans le Control Panel.

Méthode	Renvoie
`getString(property, defaultValue)`	La valeur d’une propriété String.
`getNumber(property, defaultValue)`	La valeur d’une propriété Number, sous forme de `Double`.
`getBool(property, defaultValue)`	La valeur d’une propriété Boolean.
`getJsonObject(property, defaultValue)`	La valeur d’une propriété JSON qui contient un objet, sous forme de `JSONObject`.
`getJsonArray(property, defaultValue)`	La valeur d’une propriété JSON qui contient un tableau, sous forme de `JSONArray`.

isEnabled(key, defaultValue) renvoie defaultValue lorsque get(key) renvoie null.

Maintenir les flags à jour

Le SDK stocke la dernière réponse sur l’appareil pendant 24 heures au maximum. Les flags stockés ne sont valides que pour le User ID pour lequel ils ont été demandés. Le SDK les actualise :

Au début d’une session, c’est-à-dire lorsque l’application passe au premier plan pour la première fois ou après au moins 30 minutes en arrière-plan.
Toutes les heures tant que l’application est au premier plan.
Après le premier enregistrement de l’appareil.
Juste après le changement du User ID avec setUserId. Les flags stockés de l’utilisateur précédent sont supprimés, de sorte qu’un nouvel utilisateur ne les voit jamais.

Pour réagir aux nouvelles valeurs, enregistrez un listener. Il est appelé après une actualisation qui a modifié la valeur d’un 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()
}

Pour demander les flags vous-même, par exemple après une action susceptible de faire passer l’utilisateur dans un autre segment, appelez refresh. Tant que les flags stockés sont valides, il envoie au plus une requête toutes les 5 minutes et, dans cet intervalle, répond à partir des flags stockés. Le callback s’exécute sur le 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()
}

En cas d’échec, result.exception est une FeatureFlagsException. Son httpStatus vaut 0 lorsque la requête n’a reçu aucune réponse HTTP, et 200 lorsque le serveur a répondu mais que la réponse n’a pas pu être utilisée.

Si Pushwoosh ne parvient pas à déterminer à temps les segments de l’appareil, il renvoie une réponse partielle. Le SDK ne la stocke pas, et l’actualisation suivante apporte la réponse complète.

Lorsqu’un flag est coupé (kill) dans le Control Panel, les appareils le reçoivent désactivé, avec les valeurs de propriétés par défaut, lors de l’actualisation suivante. Lorsque le SDK ne peut pas joindre le serveur, il continue d’utiliser les flags stockés jusqu’à ce qu’ils aient 24 heures, puis vos valeurs par défaut.

Enregistrer les impressions

Une impression indique à Pushwoosh qu’un utilisateur a réellement atteint le code contrôlé par un flag, afin que vous puissiez comparer les utilisateurs qui ont bénéficié de la fonctionnalité avec ceux qui n’en ont pas bénéficié. Appelez logImpression(key) au moment où l’utilisateur voit la fonctionnalité ou son ancienne version, aussi bien dans la branche activée que dans la branche désactivée, car les utilisateurs pour lesquels le flag est désactivé constituent votre groupe de comparaison :

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

Le SDK envoie l’événement PW_FeatureFlagImpression avec les attributs suivants :

Attribut	Type	Valeur
`flag_key`	string	La clé du flag.
`rule_id`	string	La règle qui a déterminé le résultat, comme dans `ruleId`.
`enabled`	boolean	Indique si le flag était activé.

Vous n’avez pas besoin de créer l’événement à l’avance : Pushwoosh ajoute PW_FeatureFlagImpression avec ces attributs dans Audience → Events à l’arrivée de la première impression. Le SDK envoie une impression par flag, règle et état au cours d’une session, et n’envoie rien lorsqu’il n’existe pas de flag pour la clé.

Les impressions permettent aussi aux équipes marketing de créer un segment des utilisateurs qui ont atteint la fonctionnalité : l’état a vu la fonctionnalité (30 jours) de la condition de feature flag.

Référence des méthodes

Pushwoosh.getInstance().featureFlags possède les méthodes suivantes :

Méthode	Description
`get(key)`	Renvoie le `FeatureFlag` de la clé, ou `null`. Lit uniquement les flags stockés.
`isEnabled(key, defaultValue)`	Indique si le flag est activé, ou renvoie `defaultValue` lorsqu’il n’y a pas de flag.
`refresh(callback)`	Demande les flags, limité à une fois toutes les 5 minutes tant que les flags stockés sont valides. Le callback reçoit un `Result` contenant une `FeatureFlagsException` en cas d’échec, et peut être `null`.
`addUpdateListener(listener)`	Appelle `listener` après chaque actualisation qui a modifié la valeur d’un flag.
`removeUpdateListener(listener)`	Supprime un listener ajouté avec `addUpdateListener`.
`logImpression(key)`	Envoie un événement `PW_FeatureFlagImpression` pour la règle et l’état actuels du flag.