Feature-Flags im Web SDK

Pushwoosh.featureFlags stellt Ihrer Website die Feature-Flags bereit, die für die Anwendung im Control Panel konfiguriert sind. Pushwoosh wertet die Flag-Regeln auf dem Server für das aktuelle Gerät und den aktuellen Benutzer aus, und das SDK liefert das Ergebnis: ob das Flag für diesen Besucher aktiviert ist und welche Eigenschaftswerte gelten.

Voraussetzungen

Web SDK 3.94.1 oder höher, geladen vom Pushwoosh-CDN wie im Web SDK 3.0-Leitfaden beschrieben, oder das npm-Paket web-push-notifications 3.95.0 oder höher.
Mindestens ein Flag, das unter Audience → Feature Flags erstellt wurde. Sie benötigen seinen Key sowie die Schlüssel und Typen seiner Eigenschaften. Verwenden Sie die Schlüssel genau so, wie sie dort angezeigt werden, einschließlich Groß- und Kleinschreibung. Beispielsweise findet get('New_Checkout') kein Flag mit dem Schlüssel new_checkout.

Ein Flag lesen

Lesen Sie Flags, nachdem das SDK bereit ist. Übergeben Sie immer einen Standardwert: Er gilt, bis das SDK Flags für die Seite hat, sowie immer dann, wenn das Flag nicht existiert, archiviert ist oder der Tarif keine Feature-Flags enthält.

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

Verwenden Sie beim npm-Paket die Pushwoosh-Instanz, die Sie erstellt haben:

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

Das SDK sendet auf einer Seite keine Flag-Anfragen, bis Ihr Code zum ersten Mal get(), isEnabled(), refresh() oder addUpdateListener() aufruft. Seiten, die keine Flags verwenden, erzeugen daher keinen zusätzlichen Traffic.

Was ein Flag zurückgibt

get(key) gibt ein FeatureFlag-Objekt zurück oder null, wenn das SDK noch keine Flags für die Seite hat oder das Flag nicht in der Antwort enthalten ist. Ein archiviertes Flag ist nicht in der Antwort enthalten. Das Objekt hat folgende Felder:

Feld	Typ	Beschreibung
`key`	string	Der Flag-Schlüssel.
`enabled`	boolean	Ob das Flag für diesen Besucher aktiviert ist.
`ruleId`	string	Die Regel, die das Ergebnis bestimmt hat, zum Beispiel `r_1a2b3c4d`. `default`, wenn keine Regel auf den Besucher zutraf, und eine leere Zeichenfolge, wenn das Flag per Kill-Switch abgeschaltet ist.

Lesen Sie Eigenschaftswerte mit dem Getter, der zum Eigenschaftstyp passt. Jeder Getter gibt Ihren Standardwert zurück, wenn die Eigenschaft fehlt oder einen Wert eines anderen Typs enthält. Wenn das Flag deaktiviert ist, enthalten die Eigenschaften die im Control Panel festgelegten Standardwerte.

Methode	Rückgabe
`getString(property, defaultValue)`	Der Wert einer String-Eigenschaft.
`getNumber(property, defaultValue)`	Der Wert einer Number-Eigenschaft.
`getBool(property, defaultValue)`	Der Wert einer Boolean-Eigenschaft.
`getJson(property, defaultValue)`	Der Wert einer JSON-Eigenschaft als geparster JSON-Wert.
`getProperties()`	Eine Kopie aller Eigenschaftswerte des Flags.

isEnabled(key, defaultValue) ist eine Kurzform für get(key)?.enabled und gibt defaultValue zurück, wenn kein Flag vorhanden ist.

Flags aktuell halten

Das SDK speichert die letzte Antwort bis zu 24 Stunden in der IndexedDB des Browsers. Die gespeicherten Flags sind nur für die User ID gültig, für die sie angefordert wurden. Das SDK aktualisiert sie:

bei der ersten Verwendung auf einer Seite, wenn die gespeicherten Flags älter als 15 Minuten sind oder fehlen;
stündlich, solange die Seite geöffnet bleibt;
nach der Registrierung des Geräts, wenn die Flags vor der Registrierung angefordert wurden;
direkt nach einer Änderung der User ID. Die gespeicherten Flags des vorherigen Benutzers werden verworfen, sodass ein neuer Benutzer sie nie sieht.

Um auf neue Werte zu reagieren, registrieren Sie einen Listener. Er wird nach einer Aktualisierung aufgerufen, die einen Flag-Wert geändert hat:

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

Um die Flags selbst anzufordern, zum Beispiel nach einer Aktion, die den Besucher in ein anderes Segment verschieben kann, rufen Sie refresh() auf. Solange die gespeicherten Flags gültig sind, sendet die Methode höchstens eine Anfrage pro 5 Minuten und wird innerhalb dieses Zeitfensters sofort aufgelöst. Das Promise wird abgelehnt, wenn die Anfrage fehlschlägt, und die gespeicherten Flags bleiben in Gebrauch.

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

Wenn Pushwoosh die Segmente des Besuchers nicht rechtzeitig zuordnen kann, liefert es eine Teilantwort. Das SDK verwendet sie nur auf der aktuellen Seite, nur wenn es keine gültigen gespeicherten Flags hat, und speichert sie nie. Die nächste Aktualisierung liefert die vollständige Antwort.

Wenn ein Flag im Control Panel per Kill-Switch abgeschaltet wird, erhalten Besucher es bei der nächsten Aktualisierung deaktiviert mit den Standard-Eigenschaftswerten. Wenn das SDK den Server nicht erreichen kann, verwendet es die gespeicherten Flags weiter, bis sie 24 Stunden alt sind, und danach Ihre Standardwerte.

Impressions protokollieren

Eine Impression teilt Pushwoosh mit, dass ein Besucher den Code, den ein Flag steuert, tatsächlich erreicht hat, sodass Sie Besucher, die die Funktion erhalten haben, mit denen vergleichen können, die sie nicht erhalten haben. Rufen Sie logImpression(key) in dem Moment auf, in dem der Besucher die Funktion oder ihre alte Version sieht, und zwar sowohl im aktivierten als auch im deaktivierten Zweig, denn Besucher mit deaktiviertem Flag sind Ihre Vergleichsgruppe:

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

Das SDK sendet das Event PW_FeatureFlagImpression mit diesen Attributen:

Attribut	Typ	Wert
`flag_key`	string	Der Flag-Schlüssel.
`rule_id`	string	Die Regel, die das Ergebnis bestimmt hat, wie in `ruleId`.
`enabled`	boolean	Ob das Flag aktiviert war.

Sie müssen das Event nicht im Voraus erstellen, denn Pushwoosh fügt PW_FeatureFlagImpression mit diesen Attributen unter Audience → Events hinzu, sobald die erste Impression eintrifft. Das SDK sendet pro Flag, Regel und Zustand eine Impression pro Seite und überspringt 30 Minuten lang Wiederholungen aus anderen Tabs desselben Browsers. logImpression() wird nie abgelehnt und sendet nichts, wenn es für den Schlüssel kein Flag gibt.

Mit Impressions können Marketer außerdem ein Segment der Besucher erstellen, die die Funktion erreicht haben: den Zustand hat die Funktion gesehen (30 Tage) der Feature-Flag-Bedingung.

Methodenreferenz

Pushwoosh.featureFlags hat diese Methoden:

Methode	Beschreibung
`get(key)`	Gibt das `FeatureFlag` für den Schlüssel zurück oder `null`. Liest nur die gespeicherten Flags und wartet nie auf das Netzwerk.
`isEnabled(key, defaultValue)`	Gibt zurück, ob das Flag aktiviert ist, oder `defaultValue`, wenn kein Flag vorhanden ist.
`refresh()`	Fordert die Flags an, gedrosselt auf einmal pro 5 Minuten, solange die gespeicherten Flags gültig sind. Gibt ein Promise zurück.
`addUpdateListener(listener)`	Ruft `listener` nach jeder Aktualisierung auf, die einen Flag-Wert geändert hat.
`removeUpdateListener(listener)`	Entfernt einen mit `addUpdateListener` hinzugefügten Listener.
`logImpression(key)`	Sendet ein `PW_FeatureFlagImpression`-Event für die aktuelle Regel und den aktuellen Zustand des Flags. Gibt ein Promise zurück.