Feature flags dans le Web SDK

Pushwoosh.featureFlags fournit à votre site web 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 ce visiteur et quelles valeurs de propriétés s’appliquent.

Prérequis

Web SDK 3.94.1 ou version ultérieure, chargé depuis le CDN Pushwoosh comme décrit dans le guide du Web SDK 3.0, ou le package npm web-push-notifications 3.95.0 ou version ultérieure.
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

Lisez les flags une fois le SDK prêt. Transmettez toujours une valeur par défaut : elle s’applique tant que le SDK n’a pas de flags pour la page, ainsi que chaque fois que le flag n’existe pas, est archivé ou que le forfait n’inclut pas les 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);
});

Avec le package npm, utilisez l’instance Pushwoosh que vous avez créée :

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);
  // ...
});

Le SDK n’envoie aucune requête de flags sur une page tant que votre code n’a pas appelé pour la première fois get(), isEnabled(), refresh() ou addUpdateListener(). Les pages qui n’utilisent pas de flags ne génèrent donc aucun trafic supplémentaire.

Ce que renvoie un flag

get(key) renvoie un objet FeatureFlag, ou null lorsque le SDK n’a pas encore de flags pour la page ou que le flag ne figure pas dans la réponse. Un flag archivé ne figure pas dans la réponse. L’objet possède les champs suivants :

Champ	Type	Description
`key`	string	La clé du flag.
`enabled`	boolean	Indique si le flag est activé pour ce visiteur.
`ruleId`	string	La règle qui a déterminé le résultat, par exemple `r_1a2b3c4d`. `default` lorsqu’aucune règle ne correspond au visiteur, 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.
`getBool(property, defaultValue)`	La valeur d’une propriété Boolean.
`getJson(property, defaultValue)`	La valeur d’une propriété JSON, sous forme de valeur JSON analysée.
`getProperties()`	Une copie de toutes les valeurs de propriétés du flag.

isEnabled(key, defaultValue) est un raccourci pour get(key)?.enabled qui renvoie defaultValue lorsqu’il n’y a pas de flag.

Maintenir les flags à jour

Le SDK stocke la dernière réponse dans l’IndexedDB du navigateur 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 :

à la première utilisation sur une page, lorsque les flags stockés datent de plus de 15 minutes ou sont absents ;
toutes les heures tant que la page reste ouverte ;
après l’enregistrement de l’appareil, lorsque les flags ont été demandés avant l’enregistrement ;
juste après le changement du User ID. 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 :

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

Pour demander les flags vous-même, par exemple après une action susceptible de faire passer le visiteur 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 se résout immédiatement dans cet intervalle. La promesse est rejetée lorsque la requête échoue, et les flags stockés restent utilisés.

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

Si Pushwoosh ne parvient pas à déterminer à temps les segments du visiteur, il renvoie une réponse partielle. Le SDK ne l’utilise que sur la page actuelle, uniquement lorsqu’il n’a pas de flags stockés valides, et ne la stocke jamais. L’actualisation suivante apporte la réponse complète.

Lorsqu’un flag est coupé (kill) dans le Control Panel, les visiteurs 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 visiteur a réellement atteint le code contrôlé par un flag, afin que vous puissiez comparer les visiteurs qui ont bénéficié de la fonctionnalité avec ceux qui n’en ont pas bénéficié. Appelez logImpression(key) au moment où le visiteur voit la fonctionnalité ou son ancienne version, aussi bien dans la branche activée que dans la branche désactivée, car les visiteurs pour lesquels le flag est désactivé constituent votre groupe de comparaison :

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

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 sur une page, et ignore pendant 30 minutes les doublons provenant d’autres onglets du même navigateur. logImpression() n’est jamais rejeté et n’envoie rien lorsqu’il n’existe pas de flag pour la clé.

Les impressions permettent aussi aux marketeurs de créer un segment de visiteurs ayant atteint la fonctionnalité : l’état a vu la fonctionnalité (30 jours) de la condition de feature flag.

Référence des méthodes

Pushwoosh.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 et n’attend jamais le réseau.
`isEnabled(key, defaultValue)`	Indique si le flag est activé, ou renvoie `defaultValue` lorsqu’il n’y a pas de flag.
`refresh()`	Demande les flags, limité à une fois toutes les 5 minutes tant que les flags stockés sont valides. Renvoie une promesse.
`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. Renvoie une promesse.