Feature-Flags im Android SDK

Pushwoosh.getInstance().featureFlags stellt Ihrer Android-App 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 dieses Gerät aktiviert ist und welche Eigenschaftswerte gelten.

Voraussetzungen

Pushwoosh Android SDK 6.16.0 oder höher, integriert wie im Android SDK-Leitfaden beschrieben. Feature-Flags sind Teil der Hauptbibliothek com.pushwoosh:pushwoosh, sodass Sie keine weitere Abhängigkeit hinzufügen müssen. Solange das SDK nicht initialisiert ist, gibt get null zurück.
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

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

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

Um nur zu prüfen, ob das Flag aktiviert ist, verwenden Sie isEnabled:

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

Rufen Sie in Java Pushwoosh.getInstance().getFeatureFlags() auf.

Was ein Flag zurückgibt

get(key) gibt ein FeatureFlag-Objekt zurück oder null, wenn das SDK noch keine Flags für das Gerät hat oder das Flag nicht in der Antwort enthalten ist. Ein archiviertes Flag ist nicht in der Antwort enthalten. get liest nur die gespeicherten Flags und wartet nie auf das Netzwerk. Das Objekt hat folgende Felder:

Feld	Typ	Beschreibung
`key`	String	Der Flag-Schlüssel.
`isEnabled`	Boolean	Ob das Flag für dieses Gerät aktiviert ist.
`ruleId`	String	Die Regel, die das Ergebnis bestimmt hat, zum Beispiel `r_1a2b3c4d`. `default`, wenn keine Regel auf das Gerät 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 als `Double`.
`getBool(property, defaultValue)`	Der Wert einer Boolean-Eigenschaft.
`getJsonObject(property, defaultValue)`	Der Wert einer JSON-Eigenschaft, die ein Objekt enthält, als `JSONObject`.
`getJsonArray(property, defaultValue)`	Der Wert einer JSON-Eigenschaft, die ein Array enthält, als `JSONArray`.

isEnabled(key, defaultValue) gibt defaultValue zurück, wenn get(key) null zurückgibt.

Flags aktuell halten

Das SDK speichert die letzte Antwort bis zu 24 Stunden auf dem Gerät. Die gespeicherten Flags sind nur für die User ID gültig, für die sie angefordert wurden. Das SDK aktualisiert sie:

Wenn eine Sitzung beginnt, also wenn die App zum ersten Mal in den Vordergrund kommt oder nach mindestens 30 Minuten im Hintergrund.
Stündlich, solange die App im Vordergrund ist.
Nach der ersten Registrierung des Geräts.
Direkt nach einer Änderung der User ID mit setUserId. 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:

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

Um die Flags selbst anzufordern, zum Beispiel nach einer Aktion, die den Benutzer 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 antwortet innerhalb dieses Zeitfensters mit den gespeicherten Flags. Der Callback läuft im Hauptthread:

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

Bei einem Fehler ist result.exception eine FeatureFlagsException. Ihr httpStatus ist 0, wenn die Anfrage keine HTTP-Antwort erhalten hat, und 200, wenn der Server geantwortet hat, die Antwort aber nicht verwendet werden konnte.

Wenn Pushwoosh die Segmente des Geräts nicht rechtzeitig zuordnen kann, liefert es eine Teilantwort. Das SDK speichert sie nicht, und die nächste Aktualisierung liefert die vollständige Antwort.

Wenn ein Flag im Control Panel per Kill-Switch abgeschaltet wird, erhalten Geräte 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 Benutzer den Code, den ein Flag steuert, tatsächlich erreicht hat, sodass Sie Benutzer, 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 Benutzer die Funktion oder ihre alte Version sieht, und zwar sowohl im aktivierten als auch im deaktivierten Zweig, denn Benutzer mit deaktiviertem Flag sind Ihre Vergleichsgruppe:

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

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 Sitzung und sendet nichts, wenn es für den Schlüssel kein Flag gibt.

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

Methodenreferenz

Pushwoosh.getInstance().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.
`isEnabled(key, defaultValue)`	Gibt zurück, ob das Flag aktiviert ist, oder `defaultValue`, wenn kein Flag vorhanden ist.
`refresh(callback)`	Fordert die Flags an, gedrosselt auf einmal pro 5 Minuten, solange die gespeicherten Flags gültig sind. Der Callback erhält ein `Result` mit einer `FeatureFlagsException` bei einem Fehler und kann `null` sein.
`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.