Entwicklerhandbuch
Erste Schritte
Dieses Handbuch hilft bei der Integration des SDK und beim Starten von Experimenten in Flutter-Anwendungen. Dieses Tutorial erklärt die Einrichtung eines einfachen A/B-Tests, um die Anzahl der empfohlenen Produkte basierend auf verschiedenen Variationen zu ändern.Den Flutter-Client installieren
Um den Kameleoon Flutter-Client zu installieren, deklarieren Sie eine Abhängigkeit in Ihrerpubspec.yaml-Datei:
Den Kameleoon-Client initialisieren
Nachdem Sie das SDK in Ihre Anwendung installiert und ein serverseitiges Experiment in der Kameleoon-App eingerichtet haben, besteht der nächste Schritt darin, den Kameleoon-Client zu erstellen. EinKameleoonClient ist ein Singleton-Objekt (pro siteCode), das als Brücke zwischen Ihrer Anwendung und der Kameleoon-Plattform fungiert. Es enthält alle Methoden und Eigenschaften, die Sie zum Durchführen eines Experiments benötigen.
KameleoonClientFactory.create() den Client, aber er ist nicht sofort einsatzbereit, da der Kameleoon-Client die aktuelle Konfiguration der Feature Flags (zusammen mit ihrer Traffic-Verteilung) von einem Kameleoon-Remoteserver abrufen muss. Dieser Abruf erfordert Netzwerkzugriff, der nicht immer verfügbar ist. Bis der Kameleoon-Client vollständig bereit ist, sollten Sie nicht versuchen, andere Methoden des Kameleoon Android SDK auszuführen. Beachten Sie, dass die Konfiguration der Feature Flags, nachdem sie zum ersten Mal abgerufen wurde, periodisch aktualisiert wird, aber selbst wenn die Aktualisierung aus irgendeinem Grund fehlschlägt, funktioniert der Kameleoon-Client weiterhin mit der vorherigen Konfiguration.
Sie können die Methode isReadyAsync() verwenden, um zu prüfen, ob die Initialisierung des Kameleoon-Clients abgeschlossen ist.
Alternativ kann ein Hilfs-Callback die Logik der Feature-Flag-Auslösung und der Variationsimplementierung kapseln. Der beste Ansatz (isReadyAsync() oder Callback) hängt von den Vorlieben und dem genauen Anwendungsfall ab. Verwenden Sie isReadyAsync(), wenn erwartet wird, dass das SDK bald einsatzbereit sein wird. Beispielsweise ist isReadyAsync() angemessen, wenn ein Feature Flag in einem Dialog ausgeführt wird, auf den Benutzer in den ersten Sekunden oder Minuten der Navigation in der App wahrscheinlich nicht zugreifen. Ein Callback wird empfohlen, wenn eine hohe Wahrscheinlichkeit besteht, dass sich das SDK noch in der Initialisierung befindet. Beispielsweise sollte ein Feature Flag, das beim Start der Anwendung auf dem Bildschirm erscheint, einen Callback verwenden, der die Anwendung warten lässt, bis entweder das SDK bereit ist oder ein angegebener Timeout abgelaufen ist.
Es liegt in Ihrer Verantwortung als App-Entwickler, sicherzustellen, dass die Logik Ihres Anwendungscodes im Kontext des A/B-Testings mit Kameleoon korrekt ist. Eine gute Praxis ist es, immer anzunehmen, dass der Anwendungsbenutzer vom Feature Flag ausgeschlossen werden kann, wenn der Kameleoon-Client noch nicht bereit ist. Dieser Ausschluss ist einfach zu implementieren, da er der Implementierung der Standard- oder Referenzvariationslogik entspricht. Die Codebeispiele im nächsten Absatz zeigen Beispiele für diesen Ansatz.
Ein Feature Flag aktivieren
Eine Flag-Konfiguration abrufen
Um ein Feature Flag in Ihrem Code zu implementieren, müssen Sie zunächst ein Feature Flag in Ihrem Kameleoon-Konto erstellen. Um festzustellen, ob ein Feature Flag für einen bestimmten Benutzer aktiv ist, müssen Sie seine Konfiguration abrufen. Verwenden Sie die MethodegetFeatureVariationKey() oder isFeatureActive(), um die Konfiguration basierend auf dem featureKey abzurufen.
Verwenden Sie die Methode isFeatureActive(), wenn Sie die Konfiguration eines einfachen Feature Flags abrufen möchten, das nur einen EIN- oder AUS-Zustand hat, im Gegensatz zu komplexeren Feature Flags mit mehreren Variationen oder Targeting-Optionen.
Die Methode getFeatureVariationKey() ruft die Konfiguration eines Feature-Experiments mit mehreren Feature-Variationen ab. Sie können die Methode verwenden, um einen Variationsschlüssel für einen bestimmten Benutzer abzurufen, indem Sie den visitorCode und den featureKey als obligatorische Argumente angeben.
Feature Flags können zugehörige Variablen haben, die zur Anpassung ihres Verhaltens verwendet werden. Um diese Variablen abzurufen, verwenden Sie die Methode getFeatureVariationVariables() nach dem Aufruf von getFeatureVariationKey(), da Sie den variationKey für den Benutzer erhalten müssen.
Um zu prüfen, ob ein Feature Flag aktiv ist, müssen Sie nur eine Methode verwenden. Wählen Sie
isFeatureFlagActive, wenn Sie wissen möchten, ob ein Feature Flag ein- oder ausgeschaltet ist. Für komplexere Szenarien, wie das dynamische Ändern des Feature-Verhaltens, verwenden Sie getFeatureFlagVariables.Datenpunkte hinzufügen, um einen Benutzer zu targetieren oder Besuche in Berichten zu filtern/aufzuschlüsseln
Um einen Benutzer zu targetieren, stellen Sie sicher, dass Sie relevante Datenpunkte zu seinem Profil hinzugefügt haben, bevor Sie die Feature-Variation abrufen oder prüfen, ob das Flag aktiv ist. Verwenden Sie die MethodeaddData(), um diese Datenpunkte zum Profil des Benutzers hinzuzufügen.
Um Datenpunkte abzurufen, die auf anderen Geräten gesammelt wurden, oder um auf vergangene Benutzerdaten zuzugreifen (clientseitig gesammelt bei Verwendung von Kameleoon im Hybridmodus), verwenden Sie die Methode getRemoteVisitorData(). Diese Methode ruft Daten asynchron von den Servern ab. Rufen Sie getRemoteVisitorData() vor dem Abrufen der Variation oder dem Prüfen, ob das Feature Flag aktiv ist, auf, da diese Daten möglicherweise erforderlich sind, um einen Benutzer einer bestimmten Variation eines Feature Flags zuzuweisen.
Um mehr über verfügbare Targeting-Bedingungen zu erfahren, lesen Sie den ausführlichen Artikel zu diesem Thema.
Zusätzlich sind die Datenpunkte, die Sie dem Besucherprofil hinzufügen, bei der Analyse Ihrer Experimente verfügbar, sodass Sie Ihre Ergebnisse nach Faktoren wie Gerät und Browser filtern und aufschlüsseln können. Vergessen Sie nicht, die Methode flush() aufzurufen, um die gespeicherten Daten an die Kameleoon-Server zu senden.
Wenn Sie zusätzliche Datenpunkte über das hinaus verfolgen müssen, was automatisch erfasst wird, können Sie die Custom Data-Funktion von Kameleoon verwenden. Mit Custom Data können Sie spezifische Informationen erfassen und analysieren, die für Ihre Experimente relevant sind. Vergessen Sie nicht, die Methode flush() aufzurufen, um die gesammelten Daten zur Analyse an die Kameleoon-Server zu senden.
Flag-Exposition und Zielkonversionen verfolgen
Kameleoon verfolgt die Exposition von Besuchern gegenüber Flags automatisch, sobald Sie eine dieser Methoden aufrufen:getFeatureVariationKey()getFeatureVariable()isFeatureActive()
trackConversion() verwenden und die Parameter visitorCode und goalId angeben.
Verwendung eines benutzerdefinierten Bucketing-Schlüssels
Standardmäßig verwendet Kameleoon eine eindeutige, anonyme Besucher-ID (visitorCode), um Benutzer Feature-Flag-Variationen zuzuweisen. Diese ID wird typischerweise auf dem Gerät des Benutzers generiert und gespeichert (in einem Browser-Cookie für client- und serverseitige SDKs – im persistenten Speicher für mobile SDKs). In bestimmten Szenarien müssen Sie jedoch möglicherweise sicherstellen, dass alle Benutzer derselben Organisation dieselbe Variante eines Feature Flags sehen.
Die Option Custom Bucketing Key ermöglicht es Ihnen, dieses Standardverhalten zu überschreiben, indem Sie Ihre eigene benutzerdefinierte Kennung für das Bucketing angeben. Dieses Überschreiben stellt sicher, dass die Zuweisungslogik von Kameleoon Ihren angegebenen Schlüssel anstelle des standardmäßigen visitorCode verwendet.
Anwendungsfälle
Die Verwendung eines benutzerdefinierten Bucketing-Schlüssels ist unerlässlich, um Konsistenz und Genauigkeit in Ihren Feature-Flag-Zuweisungen aufrechtzuerhalten, insbesondere in diesen Situationen:- Experimente auf Konto- oder Organisationsebene: Für B2B-Produkte oder Szenarien, in denen Sie alle Benutzer derselben Organisation derselben Variation zuweisen möchten, können Sie eine Kennung wie eine
accountIdverwenden. Benutzerdefinierte Bucketing-Schlüssel sind entscheidend für A/B-Tests von Funktionen, die ein gesamtes Team oder Unternehmen betreffen.
Technische Details
Wenn Sie einen benutzerdefinierten Bucketing-Schlüssel für ein Feature Flag konfigurieren, geben Sie Kameleoon eine bestimmte Kennung aus den Daten Ihrer Anwendung:- Den benutzerdefinierten Schlüssel bereitstellen: Sie stellen Ihre benutzerdefinierte Kennung dem Kameleoon SDK über die Methode
addData()zur Verfügung. In dieser Methode übergeben Sie Ihren gewählten benutzerdefinierten Bucketing-Schlüssel alsCustomData-Objekt. Hier bezieht sichnewVisitorCodeauf die Kennung, die Sie für Ihr Bucketing verwenden möchten (z. B. die neueuserIdoderaccountId).
- Bucketing-Logik: Sobald ein benutzerdefinierter Bucketing-Schlüssel über die Methode
addData()bereitgestellt wird, verwenden alle Hash-Berechnungen zur Zuweisung von Benutzern zu Variationen diesennewVisitorCode(Ihren benutzerdefinierten Schlüssel) anstelle des standardmäßigenvisitorCode. Die Verwendung desnewVisitorCodebedeutet, dass die Bucketing-Entscheidung an Ihre benutzerdefinierte Kennung gebunden ist, was konsistente Zuweisungen in verschiedenen Kontexten gewährleistet, in denen diese Kennung vorhanden ist. - Datenverfolgung und Analyse: Es ist wichtig zu beachten, dass während der
newVisitorCode(Ihr benutzerdefinierter Schlüssel) für Bucketing-Entscheidungen verwendet wird, alle nachfolgenden Daten (z. B. Tracking-Ereignisse und Konversionen) gesendet und mit dem ursprünglichenvisitorCodeverknüpft werden. Diese Trennung stellt sicher, dass Ihre Analysen die einzelnen Benutzerreisen und Interaktionen im breiteren Kontext Ihres Experiments genau widerspiegeln, selbst wenn das Bucketing auf einer höheren Ebene (wie einem Konto) oder über mehrere Geräte/Sitzungen hinweg durchgeführt wird. Ihre ursprünglichen Besucherdaten bleiben für umfassende Berichte intakt.
Technische Anforderungen
Um einen benutzerdefinierten Bucketing-Schlüssel effektiv zu verwenden:- Der Schlüssel muss ein
Stringsein. - Er muss für die Entität eindeutig sein, die Sie bucketieren möchten (z. B. wenn Sie eine
userIdverwenden, sollte die ID jedes Benutzers eindeutig sein). - Der Schlüssel muss dem SDK genau in dem Moment verfügbar sein, in dem die Feature-Flag-Entscheidung für diesen Benutzer oder diese Anfrage ausgewertet wird.
Targeting-Bedingungen
Die Kameleoon SDKs unterstützen eine Vielzahl vordefinierter Targeting-Bedingungen, die Sie zum Targeting von Benutzern in Ihren Kampagnen verwenden können. Eine Liste der von diesem SDK unterstützten Bedingungen finden Sie unter Besuchsverlauf zum Targeting von Benutzern verwenden. Sie können auch Ihre eigenen externen Daten zum Targeting von Benutzern verwenden.Logging
Das SDK generiert Logs, um verschiedene interne Prozesse und Probleme widerzuspiegeln.Log-Level
Das SDK unterstützt die Konfiguration der Begrenzung des Loggings nach Log-Level.Benutzerdefinierte Log-Verarbeitung
Das SDK schreibt seine Logs standardmäßig in die Konsolenausgabe. Dieses Verhalten kann überschrieben werden.Die Begrenzung des Loggings nach Log-Level wird getrennt von der Log-Verarbeitungslogik durchgeführt.
Fehlerbehandlung
Die Behandlung von Fehlern gilt als bewährte Praxis, um Ihre Anwendung stabiler zu machen und technische Probleme zu vermeiden. Die meistenKameleoonClient-Methoden können einen KameleoonException-Fehler auslösen.
Da es schwierig sein kann, die SDK-Version auf der Android-Client-Seite zu patchen, wird empfohlen, jede SDK-Methode in eine try-Klausel einzuschließen, die die Fehlertypen KameleoonException und Throwable abfängt, um andere schwerwiegende Fehler zu verhindern.
Zum Beispiel:
Referenz
Dies ist die vollständige Referenzdokumentation des Flutter SDK.Initialisierung
Sobald Sie das SDK installiert haben, müssen Sie Kameleoon initialisieren. Alle Interaktionen Ihrer Anwendung mit dem SDK, wie das Auslösen eines Experiments, werden mit diesem Kameleoon-Client-Objekt durchgeführt.create()
Rufen Sie diese Methode vor allen anderen auf, um das SDK zu initialisieren. Diese Methode befindet sich inKameleoonClientFactory. Ihre App führt alle Interaktionen mit dem SDK unter Verwendung des resultierenden KameleoonClient-Objekts durch, das diese Methode erstellt.
Sie können das Verhalten des SDK anpassen (z. B. die Umgebung, die Anmeldedaten usw.), indem Sie ein Konfigurationsobjekt angeben. Andernfalls versucht das SDK, Ihre Konfigurationsdatei zu finden und verwendet sie stattdessen.
Argumente
Rückgabewert
Ausgelöste Ausnahmen
isReadyAsync()
Bei mobilen SDKs kann der Kameleoon-Client nicht sofort initialisiert werden, da er einen Serveraufruf durchführen muss, um die aktuelle Konfiguration für die aktiven Feature Flags abzurufen. Verwenden SieisReadyAsync(), um zu prüfen, ob das SDK bereit ist, indem Sie diese Methode aufrufen, bevor Sie ein Feature Flag auslösen.
Alternativ können Sie einen Callback verwenden (Einzelheiten finden Sie unter der Methode runWhenReady()).
Rückgabewert
runWhenReady()
Bei mobilen SDKs kann der Kameleoon-Client nicht sofort initialisiert werden, da er einen Serveraufruf durchführen muss, um die aktuelle Konfiguration für alle aktiven Feature Flags abzurufen. Verwenden Sie die MethoderunWhenReady() der KameleoonClient-Klasse, um einen Callback zu übergeben, der ausgeführt wird, sobald das SDK einsatzbereit ist. Sie können auch ein Timeout festlegen.
Der als erstes Argument an diese Methode übergebene Callback muss eine Instanz eines Typs Function(bool ready) sein. Wenn ready gleich true ist, ist der Kameleoon-Client bereit und sollte Code enthalten, der ein Feature Flag auslöst und Variationen implementiert. Andernfalls tritt das angegebene Timeout auf, bevor der Client initialisiert wird. Der Callback sollte Code enthalten, der die Referenzvariation implementiert, da der Benutzer aus dem Feature Flag ausgeschlossen wird, wenn ein Timeout auftritt.
Argumente
Feature Flags und Variationen
isFeatureActive()
- 📨 Sendet Tracking-Daten an Kameleoon
featureKey als erforderliches Argument, um zu prüfen, ob die angegebene Funktion für einen Besucher aktiv sein wird.
Wenn der Besucher noch nie mit diesem Feature Flag verknüpft wurde, gibt die Methode einen zufälligen booleschen Wert zurück (true, wenn dem Besucher diese Funktion angezeigt werden soll, andernfalls false). Wenn der Besucher bereits mit diesem Feature Flag registriert ist, gibt diese Methode den vorherigen Feature-Flag-Wert zurück.
Stellen Sie sicher, dass Sie eine ordnungsgemäße Fehlerbehandlung wie im Beispielcode gezeigt einrichten, um potenzielle Ausnahmen abzufangen.
Kameleoon verwendet Tracking, um Sitzungen und Besucher zu zählen, wenn Sie bestimmte Methoden wie
isFeatureActive(), getVariation() oder getVariations() aufrufen.Verwenden Sie den Standardwert true für den Parameter track, wenn Sie Besucher einer Variation aussetzen und sie zählen müssen. Setzen Sie den Parameter track nur auf false, wenn Sie diese Methoden aufrufen, bevor Sie Besucher aussetzen.Wenn Sie beispielsweise getVariations() aufrufen, um alle Variationen abzurufen, bevor Sie Besucher aussetzen, setzen Sie den Parameter track auf false. Diese Einstellung verhindert, dass Kameleoon eine Sitzung vorzeitig zählt. Sie können das Tracking dann später auslösen, wenn Sie den Besucher explizit aussetzen.Kameleoon sendet Tracking-Daten standardmäßig jede Sekunde. Sie können dieses Intervall mit der Konfigurationsoption für das Tracking-Intervall auf bis zu fünf Sekunden konfigurieren. Kameleoon gruppiert Tracking-Ereignisse in einer einzigen Sitzung, solange das Intervall zwischen den Ereignissen weniger als 30 Minuten beträgt. Wenn zwischen Tracking-Ereignissen mehr als 30 Minuten verstreichen, zählt Kameleoon die Ereignisse als separate Sitzungen. Ein Besuch erscheint 30 Minuten nach dem letzten aufgezeichneten Ereignis der Sitzung in Ihren Berichten.Argumente
Rückgabewert
Ausgelöste Ausnahmen
getVariation()
- 📨 Sendet Tracking-Daten an Kameleoon (abhängig vom Parameter
track)
Variation ab, die einem bestimmten Besucher für ein bestimmtes Feature Flag zugewiesen wurde.
Diese Methode benötigt einen visitorCode und einen featureKey als obligatorische Argumente. Das Argument track ist optional und standardmäßig auf true gesetzt.
Sie gibt die zugewiesene Variation für den Besucher zurück. Wenn der Besucher mit keinen Feature-Flag-Regeln verknüpft ist, gibt die Methode die Standard-Variation für das angegebene Feature Flag zurück.
Stellen Sie sicher, dass in Ihrem Code eine ordnungsgemäße Fehlerbehandlung implementiert ist, um potenzielle Ausnahmen zu verwalten.
Die Standardvariation bezieht sich auf die Variation, die einem Besucher zugewiesen wird, wenn er keinen vordefinierten Auslieferungsregeln für ein Feature Flag entspricht. Mit anderen Worten, es ist die Fallback-Variation, die auf alle Benutzer angewendet wird, die nicht durch spezifische Regeln targetiert werden. Sie wird als Variation im Abschnitt “Then, for everyone else…” in einer Verwaltungsoberfläche dargestellt.
Argumente
Rückgabewert
Ausgelöste Ausnahmen
getVariations()
- 📨 Sendet Tracking-Daten an Kameleoon (abhängig vom Parameter
track)
Variation-Objekten ab, die einem bestimmten Besucher über alle Feature Flags hinweg zugewiesen wurden.
Diese Methode iteriert über alle verfügbaren Feature Flags und gibt die zugewiesene Variation für jedes Flag zurück, das mit dem angegebenen Besucher verknüpft ist. Sie benötigt onlyActive und track als optionale Argumente.
- Wenn
onlyActiveauftruegesetzt ist, gibt die MethodegetVariations()Feature-Flag-Variationen zurück, sofern der Benutzer nicht mit deroff-Variation gebucketiert ist. - Der Parameter
tracksteuert, ob die Methode die Variationszuweisungen verfolgt oder nicht. Standardmäßig ist er auftruegesetzt. Wenn er auffalsegesetzt ist, wird das Tracking deaktiviert.
Variation als Werten. Wenn für ein Feature Flag keine Variation zugewiesen ist, gibt die Methode die Standard-Variation für dieses Flag zurück.
Eine ordnungsgemäße Fehlerbehandlung sollte implementiert werden, um potenzielle Ausnahmen zu verwalten.
Die Standardvariation bezieht sich auf die Variation, die einem Besucher zugewiesen wird, wenn er keinen vordefinierten Auslieferungsregeln für ein Feature Flag entspricht. Mit anderen Worten, es ist die Fallback-Variation, die auf alle Benutzer angewendet wird, die nicht durch spezifische Regeln targetiert werden. Sie wird als Variation im Abschnitt “Then, for everyone else…” in einer Verwaltungsoberfläche dargestellt.
Argumente
Rückgabewert
Ausgelöste Ausnahmen
getFeatureList()
Gibt eine Liste der derzeit für das SDK verfügbaren Feature-Flag-Schlüssel zurück.Rückgabewert
getDataFile()
Gibt die aktuelle SDK-Konfiguration alsDataFile-Objekt zurück.
Rückgabewert
Ausgelöste Fehler
setForcedVariation()
Mit der Methode können Sie einem Benutzer programmgesteuert eine bestimmteVariation zuweisen und dabei den Standardauswertungsprozess umgehen. Dies ist besonders wertvoll für kontrollierte Experimente, bei denen die übliche Auswertungslogik nicht erforderlich ist oder übersprungen werden muss. Es kann auch in Szenarien wie Debugging oder benutzerdefinierten Tests hilfreich sein.
Wenn eine erzwungene Variation festgelegt wird, überschreibt sie die Echtzeit-Auswertungslogik von Kameleoon. Prozesse wie Segmentierung, Targeting-Bedingungen und algorithmische Berechnungen werden übersprungen. Um Segmentierung und Targeting-Bedingungen während eines Experiments beizubehalten, setzen Sie stattdessen forceTargeting=false.
Eine erzwungene Variation wird genauso behandelt wie eine ausgewertete Variation. Sie wird in Analysen verfolgt und im Benutzerkontext wie jede andere ausgewertete Standardvariation gespeichert, was die Konsistenz in der Berichterstattung gewährleistet.
Die Methode kann unter bestimmten Bedingungen Ausnahmen auslösen (z. B. ungültige Parameter, Benutzerkontext oder interne Probleme). Eine ordnungsgemäße Ausnahmebehandlung ist unerlässlich, um sicherzustellen, dass Ihre Anwendung stabil und widerstandsfähig bleibt.
Argumente
Ausgelöste Fehler
In den meisten Fällen muss nur der grundlegende Fehler
KameleoonException behandelt werden, wie im Beispiel gezeigt. Wenn jedoch verschiedene Arten von Fehlern eine Reaktion erfordern, behandeln Sie jeden basierend auf spezifischen Anforderungen separat. Zusätzlich können für erhöhte Zuverlässigkeit allgemeine Sprachfehler durch Einbeziehung von Exception behandelt werden.evaluateAudiences()
- 📨 Sendet Tracking-Daten an Kameleoon
evaluateAudiences() sollte aufgerufen werden, nachdem alle relevanten Besucherdaten festgelegt oder aktualisiert wurden, und kurz bevor eine Feature-Variation abgerufen oder ein Feature Flag überprüft wird. Dieser Ansatz stellt sicher, dass der Besucher anhand der aktuellsten verfügbaren Daten bewertet wird, was eine genaue Audience-Zuordnung basierend auf allen Kriterien ermöglicht.
Nach dem Aufruf dieser Methode können Sie eine detaillierte Analyse der Segmentleistung im Audiences Explorer durchführen.
Ausgelöste Fehler
In den meisten Fällen muss nur der grundlegende Fehler
KameleoonException behandelt werden, wie im Beispiel gezeigt. Wenn jedoch verschiedene Arten von Fehlern eine Reaktion erfordern, behandeln Sie jeden basierend auf spezifischen Anforderungen separat. Zusätzlich können für erhöhte Zuverlässigkeit allgemeine Sprachfehler durch Einbeziehung von Exception behandelt werden.Ziele
trackConversion()
- 📨 Sendet Tracking-Daten an Kameleoon
goalId, um die Konversion für dieses bestimmte Ziel zu verfolgen. Darüber hinaus akzeptiert diese Methode auch die Argumente revenue, metadata und negative.
Die Methode trackConversion() gibt keinen Wert zurück. Diese Methode ist nicht-blockierend, da der Serveraufruf asynchron erfolgt.
Argumente
metadata-Werte sind über Rohdatenexporte und die Ergebnisseite zugänglich.Wenn der Parameter
metadata bereitgestellt wird, verwendet Kameleoon diese angegebenen Werte für die aktuelle Konversion anstelle dessen, was zuvor mit der Methode addData() gesammelt wurde. Wenn der Parameter weggelassen wird, verwendet Kameleoon die zuletzt verfolgten Werte für diese CustomData vor der Konversion und innerhalb desselben Besuchs.Kameleoon berücksichtigt nur die Metadatenwerte, die explizit als Parameter an die Methode trackConversion() übergeben werden.Im folgenden Beispiel verknüpft Kameleoon die Konversion nur mit dem als Parameter explizit angegebenen Custom-Data-Wert (hier: Index 5 mit dem Wert ‘Amex Credit Card’).Ereignisse
onUpdateConfiguration()
Diese Methode hieß zuvor
updateConfigurationHandler, die in SDK-Version 3.0.0 entfernt wurde.onUpdateConfiguration() können Sie das Ereignis behandeln, wenn die Konfiguration aktualisierte Daten enthält. Sie nimmt einen Eingabeparameter, handler. Der Handler, der aufgerufen wird, wenn die Konfiguration mithilfe eines Echtzeit-Konfigurationsereignisses aktualisiert wird.
Argumente
Besucherdaten
getVisitorCode()
Gibt den im SDK verwendeten eindeutigen Besuchercode zurück.Rückgabewert
addData()
Die MethodeaddData() fügt dem Speicher Targeting-Daten hinzu, damit andere Methoden die Daten verwenden können, um zu entscheiden, ob der aktuelle Besucher targetiert werden soll oder nicht.
Die Methode addData() gibt keinen Wert zurück und interagiert nicht selbst mit den Kameleoon-Backend-Servern. Stattdessen werden alle deklarierten Daten für die zukünftige Übertragung mit der Methode flush() gespeichert. Dieser Ansatz reduziert die Anzahl der durchgeführten Serveraufrufe, da die Daten typischerweise in einen einzigen Serveraufruf gruppiert werden, der durch flush() ausgelöst wird.
Die Methode trackConversion() sendet ebenfalls alle zuvor zugeordneten Daten, genau wie flush(). Dasselbe gilt für die Methoden getVariation() und getVariations(), wenn eine Experimentregel ausgelöst wird.
Argumente
Ausnahmen
flush()
- 📨 Sendet Tracking-Daten an Kameleoon
addData() zugeordnet sind, werden nicht sofort an den Server gesendet. Sie werden gespeichert und akkumuliert, bis sie automatisch von der Methode trackConversion() gesendet oder manuell durch Aufruf der Methode flush() gesendet werden, was die Kontrolle darüber gibt, wann genau die Daten an die Server gesendet werden. Wenn die Methode addData() beispielsweise ein Dutzend Mal aufgerufen wird, wäre das Senden von Daten an den Server nach jedem addData()-Aufruf Ressourcenverschwendung. Rufen Sie flush() einmal am Ende auf.
Die Methode flush() gibt keinen Wert zurück. Diese Methode ist nicht-blockierend, da der Serveraufruf asynchron erfolgt.
Ausgelöste Ausnahmen
getRemoteData()
Diese Methode hieß zuvor
retrieveDataFromRemoteSource, die in SDK-Version 3.0.0 entfernt wurde.siteCode und dem Argument key (oder dem aktiven visitorCode, wenn key weggelassen wird) abzurufen. Der visitorCode und der siteCode werden in KameleoonClientFactory.create() angegeben. Daten können schnell und bequem auf hoch skalierbaren Remoteservern mit der Kameleoon Data API gespeichert werden. Die Anwendung kann die Daten dann mit dieser Methode abrufen.
Beachten Sie, dass dieser Mechanismus asynchron ist, da ein Serveraufruf erforderlich ist.
Argumente
Rückgabewert
getRemoteVisitorData()
getRemoteVisitorData() ist eine asynchrone Methode zum Abrufen von Kameleoon-Besuchsdaten für den visitorCode von der Kameleoon Data API. Diese Methode fügt die Daten dem Speicher hinzu, damit andere Methoden sie bei Targeting-Entscheidungen verwenden können.
Mit dieser Methode abgerufene Daten spielen eine wichtige Rolle, wenn Sie:
- Daten verwenden möchten, die auf anderen Geräten gesammelt wurden.
- auf die Historie eines Benutzers zugreifen möchten, z. B. Custom Data, die während früherer Besuche gesammelt wurden.
Argumente
Rückgabewert
Ausgelöste Ausnahmen
Verwendung von Parametern in getRemoteVisitorData()
Die MethodegetRemoteVisitorData() bietet Flexibilität, indem Sie verschiedene Parameter beim Abrufen von Daten zu Besuchern definieren können. Ob Sie auf der Grundlage von Zielen, Experimenten oder Variationen targetieren, derselbe Ansatz gilt für alle Datentypen.
Angenommen, Sie möchten Daten zu Besuchern abrufen, die ein Ziel “Order transaction” abgeschlossen haben. Sie können innerhalb der Methode getRemoteVisitorData() Parameter angeben, um Ihr Targeting zu verfeinern. Wenn Sie beispielsweise nur Benutzer targetieren möchten, die das Ziel in ihren letzten fünf Besuchen konvertiert haben, können Sie den Parameter previousVisitAmount auf 5 und conversions auf true setzen.
Die in diesem Beispiel gezeigte Flexibilität ist nicht auf Zieldaten beschränkt. Sie können Parameter innerhalb der Methode getRemoteVisitorData() verwenden, um Daten zu einer Vielzahl von Besucherverhalten abzurufen.
Hier ist die Liste der verfügbaren
RemoteVisitorDataFilter-Optionen:getVisitorWarehouseAudience()
Ruft alle Audience-Daten ab, die mit dem Besucher in Ihrem Data Warehouse verknüpft sind. Der optionale ParameterwarehouseKey ist typischerweise Ihre interne Benutzer-ID. Der Parameter customDataIndex entspricht den Kameleoon Custom Data, die Kameleoon zum Targeting Ihrer Besucher verwendet. Weitere Details finden Sie in der Dokumentation zum Warehouse-Targeting. Die Methode gibt das Ergebnis als CustomData-Objekt zurück und bestätigt, dass die Daten dem Besucher hinzugefügt wurden und für Targeting-Zwecke verfügbar sind.
Da ein Serveraufruf erforderlich ist, ist dieser Mechanismus asynchron.
Argumente
Rückgabewert
Ausgelöste Ausnahmen
setLegalConsent()
Sie müssen diese Methode verwenden, um anzugeben, ob der Besucher die rechtliche Zustimmung zur Verwendung seiner persönlichen Daten gegeben hat. Wenn Sie den Parameterconsent auf false setzen, werden die Datentypen begrenzt, die Sie in Tracking-Anfragen einschließen können. Diese Methode hilft Ihnen, rechtliche und regulatorische Anforderungen einzuhalten und gleichzeitig die Besucherdaten verantwortungsvoll zu verwalten. Weitere Informationen zu personenbezogenen Daten finden Sie in den Richtlinien zur Einwilligungsverwaltung.
Argumente
Ausgelöste Ausnahmen
Verhalten beim Widerruf der Einwilligung
Dies gilt nur für das Flutter Web SDK.
setLegalConsent() mit consent=false aufrufen, löscht das SDK das kameleoonVisitorCode-Cookie nicht. Stattdessen verlängert es das Ablaufdatum des Cookies nicht mehr, sodass das Cookie bestehen bleibt, bis es auf natürliche Weise abläuft.
Wenn Ihre Compliance-Anforderungen die sofortige Entfernung der Cookie-Datei bei Opt-Out erfordern, müssen Sie sie manuell mit den nativen Cookie-Verwaltungsmethoden Ihres Frameworks löschen. Das SDK entfernt die Datei nicht automatisch.
Datentypen
In diesem Abschnitt sind die von Kameleoon unterstütztenData-Typen aufgeführt. Es werden mehrere Standarddatentypen sowie der Typ CustomData zum Definieren benutzerdefinierter Datentypen bereitgestellt.
Conversion
Der hier gespeicherte DatensatzConversion kann verwendet werden, um Experiment- und Personalisierungsberichte nach jedem damit verbundenen Ziel zu filtern.
CustomData
Dieser Datentyp ist für beide Arten von SDKs verfügbar: Mobile und Web.
CustomData ermöglicht es, jede Art von Daten einfach mit jedem Besucher zu verknüpfen. CustomData kann dann als Targeting-Bedingung in Segmenten oder als Filter/Aufschlüsselung in Experimentberichten verwendet werden.
Um mehr über Custom Data zu erfahren, lesen Sie bitte diesen Artikel.
- Jeder Besucher darf nur eine
CustomDatafür jeden eindeutigenindexhaben. Das Hinzufügen einer weiterenCustomDatamit demselbenindexersetzt die vorhandeneCustomData. - Der
indexder Custom Data finden Sie im Custom Data-Dashboard unter der Spalte „INDEX“. - Um zu verhindern, dass das SDK Daten mit dem ausgewählten Index aus Datenschutzgründen an Kameleoon-Server sendet, aktivieren Sie die Option Use this data only locally for targeting purposes beim Erstellen von Custom Data.
- Das Hinzufügen einer mit einem Namen erstellten
CustomData-Instanz, wenn die Konfiguration der SDK-Instanz nicht aktuell ist oder der Name nicht registriert ist, führt dazu, dass die Daten ignoriert werden.
Device
Dieser Datentyp ist für beide Arten von SDKs verfügbar: Mobile und Web.
Geolocation
Dieser Datentyp ist für beide Arten von SDKs verfügbar: Mobile und Web.
Geolocation enthält die Geolokalisierungsdetails des Besuchers.
Browser
Der Datentyp ist nur für das Web SDK verfügbar
Browser kann verwendet werden, um Experiment- und Personalisierungsberichte nach jedem damit verbundenen Wert zu filtern.
PageView
Dieser Datentyp ist nur für Web SDKs verfügbar.
Der Index (ID) des Referrers ist auf der Konfigurationsseite des Akquisitionskanals der Kameleoon-App verfügbar. Achtung: Dieser Index beginnt bei 0, daher hat der erste Akquisitionskanal, den Sie für eine bestimmte Website erstellen, die ID 0, nicht 1.
OperatingSystem
Dieser Datentyp ist nur für Web SDKs verfügbar.
OperatingSystem enthält Informationen über das Betriebssystem auf dem Gerät des Besuchers.
Cookie
Dieser Datentyp ist nur für Web SDKs verfügbar.
Cookie enthält Informationen über das auf dem Gerät des Besuchers gespeicherte Cookie.
Rückgabetypen
DataFile
DieDataFile enthält die SDK-Konfigurationsdetails.
Sie kann bei Bedarf um zusätzliche Informationen erweitert werden, wenn Kunden dies wünschen. Wenn Sie weitere Details benötigen, wenden Sie sich bitte an Ihren Customer Success Manager.
FeatureFlag
DasFeatureFlag stellt eine Reihe von Eigenschaften dar, die ein Feature Flag selbst definieren — zum Beispiel seine Variations, Rules, den Umgebungsstatus und andere zugehörige Details.
Es kann bei Bedarf um zusätzliche Informationen erweitert werden, wenn Kunden dies wünschen. Wenn Sie weitere Details benötigen, wenden Sie sich bitte an Ihren Customer Success Manager.
Rule
DieRule stellt eine Reihe von Eigenschaften dar, die eine Regel selbst definieren — zum Beispiel ihre Variations.
Sie kann bei Bedarf um zusätzliche Informationen erweitert werden, wenn Kunden dies wünschen. Wenn Sie weitere Details benötigen, wenden Sie sich bitte an Ihren Customer Success Manager.
Variation
Variation enthält Informationen über die dem Besucher zugewiesene Variation (oder die Standardvariation, falls keine spezifische Zuweisung vorhanden ist).
- Das
Variation-Objekt liefert Details zur zugewiesenen Variation und dem zugehörigen Experiment, während dasVariable-Objekt spezifische Details zu jeder Variable innerhalb einer Variation enthält. - Stellen Sie sicher, dass Ihr Code den Fall behandelt, in dem
idoderexperimentId-1sein kann, was eine Standardvariation anzeigt. - Die
variables-Map kann leer sein, wenn keine Variablen mit der Variation verknüpft sind.
Variable
Variable enthält Informationen über eine Variable, die mit der zugewiesenen Variation verknüpft ist.
Veraltete Methoden
isReady()
Bei mobilen SDKs kann der Kameleoon-Client nicht sofort initialisiert werden, da er einen Serveraufruf durchführen muss, um die aktuelle Konfiguration für die aktiven Feature Flags abzurufen. Verwenden SieisReady(), um zu prüfen, ob das SDK bereit ist, indem Sie diese Methode aufrufen, bevor Sie ein Feature Flag auslösen.
Alternativ können Sie einen Callback verwenden (Einzelheiten finden Sie unter der Methode runWhenReady()).
Rückgabewert
getFeatureVariationKey()
- 📨 Sendet Tracking-Daten an Kameleoon
Verwenden Sie stattdessen
getVariation().featureKey als erforderliches Argument, um den Variationsschlüssel für den angegebenen Benutzer abzurufen.
Wenn der Besucher noch nie mit diesem Feature Flag verknüpft wurde, gibt das SDK einen zufällig zugewiesenen Variationsschlüssel zurück (gemäß den Feature-Flag-Regeln). Wenn der Besucher bereits mit diesem Feature Flag registriert ist, gibt diese Methode den vorherigen Variationsschlüssel zurück. Wenn der Benutzer keiner der Regeln entspricht, wird der Standardwert zurückgegeben, der im Konto Ihres Kunden definiert ist.
Stellen Sie sicher, dass Sie eine ordnungsgemäße Fehlerbehandlung wie im Beispielcode gezeigt einrichten, um potenzielle Ausnahmen abzufangen.
Argumente
Rückgabewert
Ausgelöste Ausnahmen
getActiveFeatures()
- Verwenden Sie stattdessen
getVariations(). - Hieß zuvor
getFeatureListForVisitorCode, das in der SDK-Version4.0.0entfernt wurde.
getActiveFeatures ruft Informationen über die für den Besucher verfügbaren aktiven Feature Flags ab.
Rückgabewert
getFeatureVariable()
- 📨 Sendet Tracking-Daten an Kameleoon
- Verwenden Sie stattdessen
getVariation(). - Diese Methode hieß zuvor
obtainFeatureVariable, die in der SDK-Version3.0.0entfernt wurde.
featureKey und einen variableKey als erforderliche Argumente.
Wenn der Besucher noch nie mit dem featureKey verknüpft wurde, gibt das SDK einen zufällig zugewiesenen Variablenwert für den angegebenen Variationsschlüssel zurück (gemäß den Feature-Flag-Regeln). Wenn der Besucher bereits mit diesem Feature Flag registriert ist, gibt diese Methode den Variablenwert für die zuvor registrierte Variation zurück. Wenn der Benutzer keiner der Regeln entspricht, wird der Standardvariablenwert zurückgegeben.
Stellen Sie sicher, dass Sie eine ordnungsgemäße Fehlerbehandlung wie im Beispielcode gezeigt einrichten, um potenzielle Ausnahmen abzufangen.
Argumente
Rückgabewert
Ausgelöste Ausnahmen
getFeatureVariationVariables()
- Verwenden Sie stattdessen
getVariation(). - Diese Methode hieß zuvor
getFeatureAllVariables, die in der SDK-Version4.0.0entfernt wurde.
featureKey. Sie gibt die Daten als Typ Map<String, Object> zurück, wie in der Kameleoon-App definiert. Sie löst eine Ausnahme (FeatureNotFound) aus, wenn die angeforderte Funktion in der internen Konfiguration des SDK nicht gefunden wurde.