> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Flutter SDK
> Integrieren Sie das Kameleoon Flutter SDK, um Experimente auszuführen und Feature Flags auf allen vom Flutter-Framework unterstützten Plattformen zu aktivieren.
Mit dem Kameleoon Flutter SDK können Experimente ausgeführt und Feature Flags auf allen Plattformen aktiviert werden, die vom Flutter-Anwendungsframework unterstützt werden. Die Integration des SDK in Anwendungen ist einfach, und der Fußabdruck (in Bezug auf Arbeitsspeicher- und Netzwerknutzung) ist gering.
**Erste Schritte**: Hilfe zu den ersten Schritten finden Sie im [Entwicklerhandbuch](#entwicklerhandbuch).
**Changelog**: Aktuelle Version des Flutter SDK: 3.7.0 [Changelog](https://github.com/Kameleoon/client-flutter/blob/master/CHANGELOG.md).
**SDK-Methoden**: Die vollständige Referenzdokumentation der Flutter SDK-Methoden finden Sie im Abschnitt [Referenz](#referenz).
## 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 Ihrer `pubspec.yaml`-Datei:
```ruby theme={null}
kameleoon_client_flutter: ^3.0.0
```
Im **Release**-Modus wird die JS-Bibliothek automatisch geladen. Im **Debug**-Modus können jedoch Probleme (aufgrund des Dart Development Compilers) beim Importieren der JS-Bibliothek auftreten. Um potenzielle Probleme zu vermeiden, wird dringend empfohlen, die JS-Bibliothek explizit zu importieren.
Fügen Sie die folgende Skript-Zeile zum ``-Abschnitt Ihrer `index.html` hinzu:
```html theme={null}
```
#### 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.
Ein `KameleoonClient` 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.
```dart theme={null}
import 'package:kameleoon_client_flutter/kameleoon_client_flutter.dart';
class _HomePage extends State {
KameleoonClient kameleoonClient
@override
void initState() {
super.initState();
try {
// pass client configuration and visitorCode as arguments
final config = KameleoonClientConfig(
refreshIntervalMinutes: 15, // 60 minutes by default, optional
defaultTimeoutMilliseconds: 10000, // 10_000 milliseconds by default, optional
dataExpirationIntervalMinutes: 1440 * 365, // infinity by default, optional
trackingIntervalMilliseconds: 500, // 1000 milliseconds by default, optional
environment: "staging", // optional
isUniqueIdentifier: false, // false by default, optional
domain: "example.com", // web only option, optional
networkDomain: "company.com", // web only option, optional
defaultDataFile: "{...}" // optional
);
final visitorCode = "yourVisitorCode";
final kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode: visitorCode, config: config);
// or, if you want, visitor code will be generated automatically
final kameleoonClient = KameleoonClientFactory.create(siteCode, config: config);
} on SiteCodeIsEmpty catch (ex) {
// Exception indicates that the provided siteCode is empty
} on VisitorCodeInvalid catch (ex) {
// Exception indicates that the provided visitorCode is invalid
} on Exception catch (ex) {
// Any other error
}
}
}
```
Während der Ausführung initialisiert die Methode `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()`](#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()`](#isreadyasync) oder **Callback**) hängt von den Vorlieben und dem genauen Anwendungsfall ab. Verwenden Sie [`isReadyAsync()`](#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.
Sie sind jetzt bereit, das Feature-Management und Feature Flags zu implementieren. Weitere Details zu zusätzlichen Methoden finden Sie im Abschnitt [Referenz](#referenz).
#### 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](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-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 Methode [`getFeatureVariationKey()`](#getfeaturevariationkey) oder [`isFeatureActive()`](#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()`](#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 Methode [`addData()`](#adddata), 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()`](#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](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
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](#customdata) 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()`
Wenn ein Benutzer eine gewünschte Aktion abschließt (z. B. einen Kauf tätigt), zählt dies als Konversion. Um Konversionen zu verfolgen, müssen Sie die Methode [`trackConversion()`](#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 `accountId` verwenden. Benutzerdefinierte Bucketing-Schlüssel sind entscheidend für A/B-Tests von Funktionen, die ein gesamtes Team oder Unternehmen betreffen.
Durch die Implementierung eines benutzerdefinierten Bucketing-Schlüssels gewährleisten Sie eine höhere Konsistenz und Genauigkeit in Ihren Experimenten, was zu zuverlässigeren Ergebnissen und einer besseren Benutzererfahrung führt.
#### 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:
```dart theme={null}
try {
await kameleoonClient.addData(CustomData.withIndex(index, values: ["newVisitorCode"]))
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
* **Den benutzerdefinierten Schlüssel bereitstellen:** Sie stellen Ihre benutzerdefinierte Kennung dem Kameleoon SDK über die Methode [`addData()`](#adddata) zur Verfügung. In dieser Methode übergeben Sie Ihren gewählten benutzerdefinierten Bucketing-Schlüssel als [`CustomData`](#customdata)-Objekt. Hier bezieht sich `newVisitorCode` auf die Kennung, die Sie für Ihr Bucketing verwenden möchten (z. B. die neue `userId` oder `accountId`).
Damit der benutzerdefinierte Bucketing-Schlüssel korrekt funktioniert, muss er auch während des Erstellungs- oder Bearbeitungsvorgangs des Feature Flags für das Flag definiert und konfiguriert werden. Ohne diese entsprechende Konfiguration wird das Bucketing des SDK Ihren benutzerdefinierten Schlüssel nicht anwenden. Detaillierte Anweisungen zum Einrichten in Kameleoon finden Sie in diesem [Artikel](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag#Advanced_Flag_Settings).
* **Bucketing-Logik:** Sobald ein benutzerdefinierter Bucketing-Schlüssel über die Methode `addData()` bereitgestellt wird, verwenden alle Hash-Berechnungen zur Zuweisung von Benutzern zu Variationen diesen `newVisitorCode` (Ihren benutzerdefinierten Schlüssel) anstelle des standardmäßigen `visitorCode`. Die Verwendung des `newVisitorCode` bedeutet, 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ünglichen* `visitorCode` verknü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 `String` sein.
* Er muss für die Entität eindeutig sein, die Sie bucketieren möchten (z. B. wenn Sie eine `userId` verwenden, 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](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
Sie können auch Ihre eigenen [externen Daten zum Targeting von Benutzern](/developer-docs/apis/data-api-rest/tutorials/storing-and-retrieving-external-data-to-target-users) 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.
```dart theme={null}
// The `none` log level does not allow logging.
KameleoonLogger.setLogLevel(LogLevel.none);
// The `error` log level only allows logging issues that may affect the SDK's main behaviour.
KameleoonLogger.setLogLevel(LogLevel.error);
// The `warning` log level allows logging issues which may require additional attention.
// It extends the `error` log level.
// The `warning` log level is a default log level.
KameleoonLogger.setLogLevel(LogLevel.warning);
// The `info` log level allows logging general information on the SDK's internal processes.
// It extends the `warning` log level.
KameleoonLogger.setLogLevel(LogLevel.info);
// The `DEBUG` level logs additional details about the SDK’s internal processes and extends the `INFO` level
// with more granular. diagnostic output.
// This information is not intended for end-user interpretation but can be sent to support
// to assist with internal troubleshooting.
KameleoonLogger.setLogLevel(LogLevel.debug);
```
#### 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.
```dart theme={null}
import 'package:logging/logging.dart' as logging;
class CustomLogger extends Logger {
final logger = logging.Logger("CustomLogger");
// `log` method accepts logs from the SDK
@override
void log(LogLevel level, String message) {
// Custom log handling logic here. For example:
switch (level) {
case LogLevel.error:
logger.severe(message);
break;
case LogLevel.warning:
logger.warning(message);
break;
case LogLevel.info:
logger.info(message);
break;
case LogLevel.debug:
logger.fine(message);
break;
default:
break;
}
}
}
// Log level filtering is applied separately from log handling logic.
// The custom logger will only accept logs that meet or exceed the specified log level.
// Ensure the log level is set correctly.
KameleoonLogger.setLogLevel(LogLevel.debug); // Optional, defaults to `LogLevel.warning`.
KameleoonLogger.setLogger(CustomLogger());
```
### Fehlerbehandlung
Die Behandlung von Fehlern gilt als bewährte Praxis, um Ihre Anwendung stabiler zu machen und technische Probleme zu vermeiden. Die meisten `KameleoonClient`-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:
```dart theme={null}
try {
// Calling a method of the SDK
} on KameleoonException {
// Handling expected exceptions
} on Exception {
// Any other error
}
```
## Referenz
Dies ist die vollständige Referenzdokumentation des Flutter SDK.
### Initialisierung
Sobald Sie das [SDK installiert](#den-flutter-client-installieren) 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 in `KameleoonClientFactory`. 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](#additional-configuration) angeben. Andernfalls versucht das SDK, Ihre Konfigurationsdatei zu finden und verwendet sie stattdessen.
```dart theme={null}
import 'package:kameleoon_client_flutter/kameleoon_client_flutter.dart'
final siteCode = "a8st4f59bj";
try {
// pass client configuration and visitorCode as arguments
final config = KameleoonClientConfig(
refreshIntervalMinutes: 15, // 60 minutes by default, optional
defaultTimeoutMilliseconds: 10000, // 10_000 milliseconds by default, optional
dataExpirationIntervalMinutes: 1440 * 365, // infinity by default, optional
trackingIntervalMilliseconds: 500, // 1000 milliseconds by default, optional
environment: "staging", // optional
isUniqueIdentifier: false, // false by default, optional
domain: "example.com" // web only option, optional
networkDomain: "company.com", // web only option, optional
defaultDataFile: "{...}" // optional
);
final visitorCode = "yourVisitorCode";
final kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode: visitorCode, config: config);
} on SiteCodeIsEmpty catch (ex) {
// Exception indicates that the provided siteCode is empty
} on VisitorCodeInvalid catch (ex) {
// Exception indicates that the provided visitorCode is invalid
} on Exception catch (ex) {
// Any other error
}
try {
// generate visitorCode automatically and use default Kameleoon client config
final kameleoonClient = KameleoonClientFactory.create(siteCode);
} on SiteCodeIsEmpty catch (ex) {
// Exception indicates that the provided siteCode is empty
} on Exception catch (ex) {
// Any other error
}
```
##### Argumente
| Name | Type | Description | Default |
| ------------------------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| siteCode (*required*) | `String` | Ein [eindeutiger Schlüssel](/user-manual/faq#how-do-i-find-my-sitecode), der das mit dem SDK verwendete Kameleoon-Projekt identifiziert. | |
| visitorCode (*optional*) | `String` | Eine optionale Besucherkennung. Falls verfügbar, verwenden Sie Ihre interne **Benutzer-ID**; andernfalls generiert das SDK automatisch eine. | `nil` |
| config (*optional*) | `KameleoonClientConfig` | Wenn die SDK-Konfiguration nicht bereitgestellt wird, verwendet das SDK automatisch die Standardeinstellungen. | `nil` |
##### Rückgabewert
| Type | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `KameleoonClient` | Eine Instanz der `KameleoonClient`-Klasse, die Ihre App dann zur Verwaltung Ihrer Experimente und Feature Flags verwenden kann. |
##### Ausgelöste Ausnahmen
| Type | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Ausnahme, die anzeigt, dass der bereitgestellte Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
| `SiteCodeIsEmpty` | Ausnahme, die anzeigt, dass der angegebene Site-Code eine leere Zeichenkette ist, was ein ungültiger Wert ist. |
#### 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 Sie `isReadyAsync()`, 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()`](#runwhenready)).
```dart theme={null}
final ready = kameleoonClient.isReadyAsync();
```
##### Rückgabewert
| Name | Type | Description |
| ----- | ---- | -------------------------------------------------------------------------------------------------------- |
| ready | bool | Boolescher Wert, der den Status des SDK darstellt (korrekt initialisiert oder noch nicht einsatzbereit). |
#### 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 Methode [`runWhenReady()`](#runwhenready) 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.
```dart theme={null}
kameleoonClient.runWhenReady((ready) async {
final defaultProductsNumber = 5;
if (ready) {
late int recommendedProductsNumber;
try {
recommendedProductsNumber = await kameleoonClient.getFeatureVariable("feature_key", "product_number");
} on Exception {
recommendedProductsNumber = defaultProductsNumber;
}
} else {
recommendedProductsNumber = defaultProductsNumber;
}
setState(() {
_recommendedProductsNumber = recommendedProductsNumber;
});
}, 2000);
```
##### Argumente
| Name | Type | Description |
| --------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| callback (*required*) | `Function(bool)` | Callback-Objekt mit dem `ready`-Flag. |
| timeout (*optional)* | `Duration` | Timeout (in Millisekunden). Wenn nicht angegeben, wird der Standardwert von `defaultTimeoutMilliseconds` (aus `KameleoonClientConfig`) Millisekunden verwendet. |
### Feature Flags und Variationen
#### isFeatureActive()
* 📨 *Sendet Tracking-Daten an Kameleoon*
Um einen Feature-Toggle zu aktivieren, rufen Sie diese Methode auf. Diese Methode akzeptiert einen `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.
```dart theme={null}
String featureKey = "new_checkout";
bool hasNewCheckout = false;
try {
hasNewCheckout = await kameleoonClient.isFeatureActive(featureKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error has occurred; feature flag isn't found in current configuration.
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error
}
if (hasNewCheckout) {
// Implement new checkout code here
}
```
Die Methode `isFeatureActive()` wertet die ausgelieferte Variante aus, nicht den Master-Flag-Status. Wenn Sie Regeln ausschließen, verwendet die Methode den Standardzustand **Then, for everyone else serve**. Wenn Sie **Off** für diesen Standardzustand auswählen, gibt die Methode immer `false` zurück, selbst wenn das Master-Feature-Flag **On** ist.
##### Argumente
| Name | Type | Description |
| ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| featureKey | `String` | Eindeutiger Schlüssel der Funktion, die Sie einem Benutzer aussetzen möchten. Dieses Feld ist erforderlich. |
| track | `bool` | Ein optionaler Parameter zum Aktivieren oder Deaktivieren des Trackings der Feature-Auswertung (`true` standardmäßig). |
##### Rückgabewert
| Type | Description |
| -------------- | ---------------------------------------------------------- |
| `Future` | Wert der Funktion, der für einen Besucher registriert ist. |
##### Ausgelöste Ausnahmen
| Type | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SDKNotReady | Ausnahme, die anzeigt, dass das SDK seine Initialisierung nicht abgeschlossen hat. |
| FeatureNotFound | Ausnahme, die anzeigt, dass die angeforderte Feature-ID in der internen Konfiguration des SDK nicht gefunden wurde. Diese Ausnahme bedeutet normalerweise, dass das Feature Flag auf der Kameleoon-Seite nicht aktiviert wurde (aber der Code, der die Funktion implementiert, bereits in der Anwendung bereitgestellt wird). |
| PlatformException | Ausnahme, die anzeigt, dass die native Plugin-Integration nicht korrekt funktioniert. |
#### getVariation()
* 📨 *Sendet Tracking-Daten an Kameleoon (abhängig vom Parameter `track`)*
Ruft die [`Variation`](#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.
```dart theme={null}
final String featureKey = "featureKey";
Variation? variation;
try {
variation = await client.getVariation(featureKey);
// disabling tracking
variation = await client.getVariation(featureKey, track: false);
} on SDKNotReady {
// Exception indicating that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The feature key is not in the configuration file that has been fetched by the SDK.
} on FeatureEnvironmentDisabled {
// The feature flag is disabled for the environment.
}
String? title = variation?.variables['title']?.value;
switch (variation?.key) {
case "on":
// Main variation key is selected for visitorCode
break;
case "alternative_variation":
// Alternative variation key
break;
default:
// Default variation key
break;
}
```
##### Argumente
| Name | Type | Description | Default |
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------- | ------- |
| visitorCode (*required*) | `String` | Eindeutige Kennung des Besuchers. | |
| featureKey (*required*) | `String` | Schlüssel der Funktion, die Sie einem Besucher aussetzen möchten. | |
| track (*optional*) | `bool` | Ein optionaler Parameter zum Aktivieren oder Deaktivieren des Trackings der Feature-Auswertung. | `true` |
##### Rückgabewert
| Type | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| `Future` | Eine zugewiesene [`Variation`](#variation) für einen bestimmten Besucher für ein bestimmtes Feature Flag. |
##### Ausgelöste Ausnahmen
| Type | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Ausnahme, die anzeigt, dass der bereitgestellte Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
| `FeatureNotFound` | Ausnahme, die anzeigt, dass der angeforderte Feature-Schlüssel in der internen Konfiguration des SDK nicht gefunden wurde. Dies bedeutet normalerweise, dass das Feature Flag in der Kameleoon-App nicht aktiviert ist (aber der Code, der die Funktion implementiert, bereits in der Anwendung bereitgestellt wird). |
| `FeatureEnvironmentDisabled` | Ausnahme, die anzeigt, dass das Feature Flag für die aktuelle Umgebung des Besuchers deaktiviert ist (z. B. Produktion, Staging oder Entwicklung). |
#### getVariations()
* 📨 *Sendet Tracking-Daten an Kameleoon (abhängig vom Parameter `track`)*
Ruft eine Map von [`Variation`](#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 `onlyActive` auf `true` gesetzt ist, gibt die Methode `getVariations()` Feature-Flag-Variationen zurück, sofern der Benutzer nicht mit der `off`-Variation gebucketiert ist.
* Der Parameter `track` steuert, ob die Methode die Variationszuweisungen verfolgt oder nicht. Standardmäßig ist er auf `true` gesetzt. Wenn er auf `false` gesetzt ist, wird das Tracking deaktiviert.
Die zurückgegebene Map besteht aus Feature-Flag-Schlüsseln als Schlüsseln und ihren entsprechenden `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.
```dart theme={null}
try {
Map variations = await kameleoonClient.getVariations();
// only active variations
Map variations = await kameleoonClient.getVariations(onlyActive: true);
// disable tracking
Map variations = await kameleoonClient.getVariations(onlyActive: false, track: false);
} on SDKNotReady {
// Exception indicating that the SDK has not completed its initialization yet.
}
```
##### Argumente
| Name | Type | Description | Default |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| onlyActive (*optional*) | `bool` | Ein optionaler Parameter, der angibt, ob Variationen für aktive (`true`) oder alle (`false`) Feature Flags zurückgegeben werden sollen. | `false` |
| track (*optional*) | `bool` | Ein optionaler Parameter zum Aktivieren oder Deaktivieren des Trackings der Feature-Auswertung. | `true` |
##### Rückgabewert
| Type | Description |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Future>` | Map, die die zugewiesenen [`Variation`](#variation)-Objekte der Feature Flags unter Verwendung der Schlüssel der entsprechenden Funktionen enthält. |
##### Ausgelöste Ausnahmen
| Type | Description |
| ------------- | --------------------------------------------------------------- |
| `SDKNotReady` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
#### getFeatureList()
Gibt eine Liste der derzeit für das SDK verfügbaren Feature-Flag-Schlüssel zurück.
```dart theme={null}
try {
final allFeatureFlagKeys = await kameleoonClient.getFeatureList();
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
##### Rückgabewert
| Type | Description |
| ---------------------- | -------------------------------- |
| `Future>` | Liste der Feature-Flag-Schlüssel |
#### getDataFile()
Um alle Feature Flags auszuwerten, verwenden Sie [`getVariations()`](#getvariations). Diese Methode ist effizienter, als `DataFile` aufzurufen und mit [`getVariation()`](#getvariation) durch die Flags zu iterieren.
Gibt die aktuelle SDK-Konfiguration als [`DataFile`](#datafile)-Objekt zurück.
```dart theme={null}
try {
final dataFile = await kameleoonClient.getDataFile();
final dateModified = dataFile.dateModified;
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
##### Rückgabewert
| Type | Description |
| ---------- | ----------------------------------------------------- |
| `DataFile` | Die [`DataFile`](#datafile) mit der SDK-Konfiguration |
##### Ausgelöste Fehler
| Type | Description |
| ------------- | --------------------------------------------------------------- |
| `SDKNotReady` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
#### setForcedVariation()
Mit der Methode können Sie einem Benutzer programmgesteuert eine bestimmte [`Variation`](#variation) 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.
```dart theme={null}
final experimentId = 9516;
try {
// Forcing the variation "on" for the experiment 9516 for the visitor
await kameleoonClient.setForcedVariation(experimentId, "on")
// Forcing the variation "on" while preserving segmentation and targeting conditions during the experiment
await kameleoonClient.setForcedVariation(experimentId, "on", forceTargeting: false)
// Resetting the forced variation for the experiment 9516 for the visitor
await kameleoonClient.setForcedVariation(experimentId, null);
} on KameleoonException {
// Handling the exception
}
```
##### Argumente
| Name | Type | Description | Default |
| --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| experimentId (*required*) | `int` | **Experiment Id**, die während des Auswertungsprozesses targetiert und ausgewählt wird. | |
| variationKey (*required*) | `String` | **Variation Key**, der einer `Variation` entspricht, die als Rückgabewert für das Experiment erzwungen werden soll. Wenn der Wert `null` ist, wird die erzwungene Variation zurückgesetzt. | |
| forceTargeting (*optional*) | `bool` | Gibt an, ob das Targeting für das Experiment erzwungen und übersprungen (`true`) oder wie im Standardauswertungsprozess angewendet (`false`) werden soll. | `true` |
##### Ausgelöste Fehler
| Type | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SDKNotReady` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `FeatureExperimentNotFound` | Ausnahme, die anzeigt, dass die angeforderte Experiment-ID in der internen Konfiguration des SDK nicht gefunden wurde. Dies ist normalerweise normal und bedeutet, dass das der Regel entsprechende Experiment auf der Kameleoon-Seite noch nicht aktiviert wurde. |
| `FeatureVariationNotFound` | Ausnahme, die anzeigt, dass der angeforderte Variationsschlüssel (-ID) in der internen Konfiguration des SDK nicht gefunden wurde. Dies ist normalerweise normal und bedeutet, dass das der Variation entsprechende Experiment auf der Kameleoon-Seite noch nicht aktiviert wurde. |
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*
Diese Methode wertet Besucher anhand aller verfügbaren Audiences Explorer-Segmente aus und verfolgt diejenigen, die übereinstimmen.
`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.
```dart theme={null}
try {
await kameleoonClient.evaluateAudiences();
} on KameleoonException {
// Handling the exception
}
```
##### Ausgelöste Fehler
| Type | Description |
| ------------- | --------------------------------------------------------------- |
| `SDKNotReady` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
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*
Verwenden Sie diese Methode, um Konversionen zu verfolgen. Diese Methode erfordert eine `goalId`, um die Konversion für dieses bestimmte [Ziel](/user-manual//assets/goals/create-a-goal) 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.
```dart theme={null}
kameleoonClient.trackConversion(goalId); // default revenue
kameleoonClient.trackConversion(goalId, 10); // provided revenue == 10
// Add metadata
kameleoonClient.trackConversionWithOptParams(goalId, metadata: [CustomData.withIndex(1, values: ["true"])]);
kameleoonClient.trackConversionWithOptParams(goalId, revenue: 10, metadata: [CustomData.withIndex(1, values: ["true"])]);
```
##### Argumente
| Name | Type | Description | Default |
| --------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| goalId (*required*) | `int` | ID des Ziels. | |
| revenue (*optional*) | `double` | Umsatz der Konversion. | `0` |
| negative (*optional*) | `bool` | Definiert, ob der Umsatz positiv oder negativ ist. | `false` |
| metadata (*optional*) | `List` | Metadaten der Konversion. [Müssen vorher in der Kameleoon-App definiert werden](/de/user-manual/assets/goals/create-a-goal#metadaten). | `[]` |
metadata-Werte sind über [Rohdatenexporte](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export) und [die Ergebnisseite](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata) 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()`](#adddata) gesammelt wurde. Wenn der Parameter weggelassen wird, verwendet Kameleoon die zuletzt verfolgten Werte für diese [`CustomData`](#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').
```dart theme={null}
kameleoonClient.addData([
CustomData.withIndex(5, values: ["Credit Card"]),
CustomData.withIndex(9, values: ["Express Delivery"])
]);
kameleoonClient.trackConversionWithOptParams(1000, metadata: [CustomData.withIndex(5, values: ["Amex Credit Card"])]);
```
### Ereignisse
#### onUpdateConfiguration()
Diese Methode hieß zuvor `updateConfigurationHandler`, die in SDK-Version `3.0.0` entfernt wurde.
Mit der Methode `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.
```dart theme={null}
kameleoonClient.onUpdateConfiguration((timestamp) {
// timestamp value contains the value of Unix time (number of seconds elapsed since January 1, 1970) when configuration was updated.
});
```
##### Argumente
| Name | Type | Description |
| ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| handler | `Function(int)?` | Der Handler, der aufgerufen wird, wenn die Konfiguration mithilfe eines Echtzeit-Konfigurationsereignisses aktualisiert wird. |
### Besucherdaten
#### getVisitorCode()
Gibt den im SDK verwendeten eindeutigen Besuchercode zurück.
```dart theme={null}
final visitorCode = await kameleoonClient.getVisitorCode();
```
##### Rückgabewert
| Type | Description |
| ---------------- | ------------------------------------------------------------------------------- |
| `Future` | Zeichenkette, die einen eindeutigen, im SDK verwendeten Besuchercode darstellt. |
#### addData()
Die Methode `addData()` fügt dem Speicher [Targeting-Daten](#datentypen) 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()`](#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()`](#trackconversion) sendet ebenfalls alle zuvor zugeordneten Daten, genau wie `flush()`. Dasselbe gilt für die Methoden [`getVariation()`](#getvariation) und [`getVariations()`](#getvariations), wenn eine Experimentregel ausgelöst wird.
Jeder Besucher kann nur eine Instanz zugeordneter Daten für die meisten Datentypen haben. [`CustomData`](#customdata) ist jedoch eine Ausnahme. Besucher können eine Instanz von zugeordneten `CustomData` pro Index haben.
```dart theme={null}
try {
await kameleoonClient.addData([
Device(Devices.phone),
CustomData.withIndex(1, values: ["some custom value"]),
Conversion(32, 10f, false),
]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
##### Argumente
| Name | Type | Description | Default value |
| ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| track (*optional*) | `bool` | Gibt an, ob die hinzugefügten Daten für das Tracking geeignet sind. Wenn auf `false` gesetzt, werden die Daten lokal gespeichert und nur für die Targeting-Auswertung verwendet; sie werden nicht an die Kameleoon Data API gesendet. | `true` |
| data (*required*) | `List` | Sammlung von Kameleoon-Datentypen. | |
##### Ausnahmen
| Type | Description |
| ------------------- | ------------------------------------------------------------------------------------- |
| `PlatformException` | Ausnahme, die anzeigt, dass die native Plugin-Integration nicht korrekt funktioniert. |
#### flush()
* 📨 *Sendet Tracking-Daten an Kameleoon*
Daten, die dem aktuellen Benutzer über die Methode `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.
```dart theme={null}
kameleoonClient.flush(); // Interval tracking (most performant tracking method)
kameleoonClient.flush(instant: true); // Instant tracking
```
##### Ausgelöste Ausnahmen
| Type | Description |
| ----------------- | ------------------------------------------------------------------------------------- |
| PlatformException | Ausnahme, die anzeigt, dass die native Plugin-Integration nicht korrekt funktioniert. |
#### getRemoteData()
Diese Methode hieß zuvor `retrieveDataFromRemoteSource`, die in SDK-Version `3.0.0` entfernt wurde.
Verwenden Sie diese Methode, um Daten von einem Kameleoon-Remoteserver basierend auf dem aktiven `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.
```dart theme={null}
try {
final data = await kameleoonClient.getRemoteData("test");
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
```
##### Argumente
| Name | Type | Description |
| ---- | ------ | ------------------------------------------------------------------------------------------------ |
| key | String | Der Schlüssel, dem die Daten zugeordnet sind, die Sie abrufen möchten. Dieses Feld ist optional. |
##### Rückgabewert
| Type | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| `Future` | Future mit dem Abrufen von Daten für einen bestimmten `key` (oder `visitorCode`, wenn `key` weggelassen wird). |
| Type | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| PlatformException | Ausnahme, die anzeigt, dass die native Plugin-Integration nicht korrekt funktioniert. |
| Exception | Ausnahme, die anzeigt, dass die Anfrage abgelaufen ist oder einen anderen Grund für das Fehlschlagen hat. |
#### 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.
Lesen Sie [diesen Artikel](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) für ein besseres Verständnis möglicher Anwendungsfälle.
Standardmäßig ruft `getRemoteVisitorData()` automatisch die zuletzt gespeicherten Custom Data mit `scope=Visitor` ab und fügt sie dem Besucher hinzu, ohne `addData()` aufrufen zu müssen. Dies ist besonders nützlich für die [Synchronisierung von Custom Data zwischen mehreren Geräten](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices).
```dart theme={null}
// Visitor data will be fetched and automatically added for `visitorCode`.
try {
final visitorData = await kameleoonClient.getRemoteVisitorData();
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
// If you only want to fetch data and add it yourself manually, set addData == `false`.
try {
final visitorData = await kameleoonClient.getRemoteVisitorData(addData: false);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
// If you want to fetch custom list of data types
final filter = RemoteVisitorDataFilter.withValues(
previousVisitAmount: 25,
currentVisit: true,
conversions: true,
);
try {
final visitorData = await kameleoonClient.getRemoteVisitorData(filter: filter, addData: false);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
```
##### Argumente
| Name | Type | Description |
| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filter | `RemoteVisitorDataFilter` | Filter, der auswählt, welche Daten aus dem Besuchsverlauf abgerufen werden sollen. Standardmäßig ruft `getRemoteVisitorData` `CustomData` aus dem aktuellen und dem letzten vorherigen Besuch ab (`RemoteVisitorDataFilter()`). Alle anderen Filterparameter sind standardmäßig auf `false` gesetzt. Dieses Feld ist optional. |
| addData | boolean | Ein boolescher Wert, der angibt, ob die Methode die abgerufenen Daten für einen Besucher automatisch hinzufügen soll. Wenn nicht angegeben, ist der Standardwert **true**. Dieses Feld ist optional. |
##### Rückgabewert
| Type | Description |
| -------------------- | -------------------------------------------------------------- |
| `Future>` | Ein Array, das die abgerufenen Daten für den Besucher enthält. |
##### Ausgelöste Ausnahmen
| Type | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| PlatformException | Ausnahme, die anzeigt, dass die native Plugin-Integration nicht korrekt funktioniert. |
| Exception | Ausnahme, die anzeigt, dass die Anfrage abgelaufen ist oder einen anderen Grund für das Fehlschlagen hat. |
##### Verwendung von Parametern in getRemoteVisitorData()
Die Methode `getRemoteVisitorData()` 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:
| Name | Type | Description | Default |
| ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| previousVisitAmount (*optional*) | `int` | Anzahl der vorherigen Besuche, aus denen Daten abgerufen werden sollen. Zahl zwischen `1` und `25` | `1` |
| currentVisit (*optional*) | `boolean` | Wenn true, werden die Daten des aktuellen Besuchs abgerufen. | `true` |
| customData (*optional*) | `boolean` | Wenn true, werden Custom Data abgerufen. | `true` |
| geolocation (*optional*) | `boolean` | Wenn true, werden Geolokalisierungsdaten abgerufen. | `false` |
| conversions (*optional*) | `boolean` | Wenn true, werden Konversionsdaten abgerufen. | `false` |
| experiments (*optional*) | `boolean` | Wenn true, werden Experimentdaten abgerufen. | `false` |
| pageViews (*optional*, *web only*) | `boolean` | Wenn true, werden Seitendaten abgerufen. | `false` |
| device (*optional*, *web only*) | `boolean` | Wenn true, werden Gerätedaten abgerufen. | `false` |
| browser (*optional*, *web only*) | `boolean` | Wenn true, werden Browserdaten abgerufen. | `false` |
| operatingSystem (*optional*, *web only*) | `boolean` | Wenn true, werden Betriebssystemdaten abgerufen. | `false` |
| kcs (*optional*) | `boolean` | Wenn true, wird der Kameleoon Conversion Score (KCS) abgerufen. Erfordert das [AI Predictive Targeting-Add-on](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) | `false` |
| visitorCode (*optional*) | `boolean` | Wenn true, ruft Kameleoon den `visitorCode` aus dem letzten Besuch ab und verwendet ihn für den aktuellen Besuch. Dies ist notwendig, wenn Sie sicherstellen möchten, dass der Besucher, identifiziert durch seinen `visitorCode`, bei allen Besuchen immer dieselbe Variation für [Cross-Device-Experimentierung](/developer-docs/cross-device-experimentation) erhält. | `true` |
| cbs (*optional*) | `boolean` | Wenn true, werden Contextual-Bandit-Score-Daten abgerufen. | `false` |
#### getVisitorWarehouseAudience()
Ruft alle Audience-Daten ab, die mit dem Besucher in Ihrem Data Warehouse verknüpft sind. Der optionale Parameter `warehouseKey` 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](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-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.
```dart theme={null}
try {
final customData = await kameleoonClient.getVisitorWarehouseAudience(customDataIndex);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
// If you need to specify warehouse key
try {
final customData = await kameleoonClient.getVisitorWarehouseAudience(customDataIndex, "warehouseKey");
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
```
##### Argumente
| Name | Type | Description |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| visitorCode | string | Eine eindeutige Besucher-Identifikationszeichenkette, die 255 Zeichen nicht überschreiten darf. |
| customDataIndex | int | Eine Ganzzahl, die den Index der Custom Data darstellt, die Sie zum Targeting Ihrer BigQuery-Audiences verwenden möchten. |
| warehouseKey | string | Ein eindeutiger Schlüssel zur Identifizierung der Warehouse-Daten (in der Regel Ihre interne Benutzer-ID). Dieses Feld ist optional. |
##### Rückgabewert
| Type | Description |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `Future` | Eine `CustomData`-Instanz, die bestätigt, dass die Daten dem Besucher hinzugefügt wurden. |
##### Ausgelöste Ausnahmen
| Type | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| PlatformException | Ausnahme, die anzeigt, dass die native Plugin-Integration nicht korrekt funktioniert. |
| Exception | Ausnahme, die anzeigt, dass die Anfrage abgelaufen ist oder einen anderen Grund für das Fehlschlagen hat. |
#### 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 Parameter `consent` 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](/user-manual/project-management/consent-management-policy).
```dart theme={null}
try {
final customData = await kameleoonClient.setLegalConsent(true);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
```
##### Argumente
| Name | Type | Description |
| ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| consent | boolean | Ein boolescher Wert, der den rechtlichen Einwilligungsstatus darstellt. `true` gibt an, dass der Besucher die rechtliche Einwilligung gegeben hat, `false` gibt an, dass der Besucher nie eine rechtliche Einwilligung gegeben oder diese widerrufen hat. Dieses Feld ist erforderlich. |
##### Ausgelöste Ausnahmen
| Type | Description |
| ----------------- | ------------------------------------------------------------------------------------- |
| PlatformException | Ausnahme, die anzeigt, dass die native Plugin-Integration nicht korrekt funktioniert. |
##### Verhalten beim Widerruf der Einwilligung
Dies gilt nur für das Flutter Web SDK.
Wenn Sie `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ützten `Data`-Typen aufgeführt. Es werden mehrere Standarddatentypen sowie der Typ `CustomData` zum Definieren benutzerdefinierter Datentypen bereitgestellt.
#### Conversion
Der hier gespeicherte Datensatz `Conversion` kann verwendet werden, um Experiment- und Personalisierungsberichte nach jedem damit verbundenen Ziel zu filtern.
* Jeder Besucher kann mehrere `Conversion`-Objekte haben.
* Sie finden die `goalId` in der Kameleoon-App.
| Name | Type | Description | Default |
| --------------------- | ------------------ | -------------------------------------------------- | ------- |
| goalId (*required*) | `int` | ID des Ziels. | |
| revenue (*optional*) | `double` | Umsatz der Konversion | `0` |
| negative (*optional*) | `bool` | Definiert, ob der Umsatz positiv oder negativ ist. | `false` |
| metadata (*optional*) | `List` | Metadaten der Konversion. | `[]` |
```dart theme={null}
try {
final conversion = Conversion(32, 10);
final conversionMetadata = Conversion(32, 10, false, [CustomData.withIndex(1, values: ["true"])]);
final conversionOptParams = Conversion.withOptParams(32, metadata: [CustomData.withIndex(1, values: ["true"])]);
await kameleoonClient.addData([conversion, conversionMetadata, conversionOptParams]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### 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](/user-manual/assets/segments/create-a-segment/) oder als Filter/Aufschlüsselung in Experimentberichten verwendet werden.
Um mehr über Custom Data zu erfahren, lesen Sie bitte diesen [Artikel](/developer-docs/custom-data).
| Name | Type | Description | |
| ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| index/name (*required*) | `int`/`String` | Index oder Name der Custom Data. **Entweder `index` oder `name` muss angegeben werden**, um die Daten zu identifizieren. | |
| overwrite (*optional*) | `bool` | Flag zur expliziten Steuerung, wie die Werte gespeichert werden und wie sie in Berichten erscheinen. [Mehr erfahren](/developer-docs/custom-data#default-logic-when-overwrite-parameter-is-false-or-omitted) | `true` |
| values (*optional*) | `List` | Werte der zu speichernden Custom Data. | |
* Jeder Besucher darf nur eine `CustomData` für jeden eindeutigen `index` haben. Das Hinzufügen einer weiteren `CustomData` mit demselben `index` ersetzt die vorhandene `CustomData`.
* Der `index` der Custom Data finden Sie im [Custom Data-Dashboard](/user-manual/assets/custom-data/manage-custom-data) 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.
```dart theme={null}
try {
await kameleoonClient.addData([CustomData.withIndex(1, values: ["some custom value"])]);
// With several values
await kameleoonClient.addData(CustomData.withIndex(1, values: ["value 1", "value 2"]))
// To set the 'overwrite' flag to false
await kameleoonClient.addData(CustomData.withIndex(1, overwrite: false, values: ["first value", "second value"]))
// To use a name instead of the index
await kameleoonClient.addData(CustomData.withName("my-custom-data", values: ["value"]))
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### Device
Dieser Datentyp ist für beide Arten von SDKs verfügbar: Mobile und Web.
Informationen über das Gerät des Benutzers speichern.
| Name | Type | Description |
| ------ | ------- | ----------------------------------------------------------------------------- |
| device | Devices | Liste der Geräte: `phone`, `table`, `desktop`. Dieses Feld ist obligatorisch. |
```dart theme={null}
try {
await kameleoonClient.addData([Device(Devices.phone)]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### Geolocation
Dieser Datentyp ist für beide Arten von SDKs verfügbar: Mobile und Web.
`Geolocation` enthält die Geolokalisierungsdetails des Besuchers.
| Name | Type | Description |
| ----------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| country (*required*) | `String` | Das Land des Besuchers. |
| region (*optional*) | `String?` | Die Region des Besuchers. |
| city (*optional*) | `String?` | Die Stadt des Besuchers. |
| postalCode (*optional*) | `String?` | Die Postleitzahl des Besuchers. |
| latitude (*optional*) | `double?` | Die Breitengradkoordinate, die den Standort des Besuchers darstellt. Die Koordinatenzahl stellt Dezimalgrade dar. |
| longitude (*optional*) | `double?` | Die Längengradkoordinate, die den Standort des Besuchers darstellt. Die Koordinatenzahl stellt Dezimalgrade dar. |
* Jeder Besucher kann nur eine `Geolocation` haben. Das Hinzufügen einer zweiten `Geolocation` überschreibt die erste.
```dart theme={null}
try {
await kameleoonClient.addData([Geolocation("France", region: "Île-de-France", city: "Paris")]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### Browser
Der Datentyp ist nur für das Web SDK verfügbar
Der hier gespeicherte Datensatz `Browser` kann verwendet werden, um Experiment- und Personalisierungsberichte nach jedem damit verbundenen Wert zu filtern.
| Name | Type | Description |
| -------------------- | ---------- | -------------------------------------------------------------------------------------------- |
| browser (*required*) | `Browsers` | Liste der Browser: `chrome`, `internetExplorer`, `firefox`, `safari`, `opera`, `other`. |
| version (*optional*) | `double?` | Version des Browsers, Gleitkommazahl, die die Haupt- und Nebenversion des Browsers darstellt |
```dart theme={null}
try {
await kameleoonClient.addData([Browser(Browsers.chrome)]);
await kameleoonClient.addData([Browser(Browsers.chrome, 10.0)]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### PageView
Dieser Datentyp ist nur für Web SDKs verfügbar.
| Name | Type | Description |
| --------- | ----------- | ------------------------------------------------------------ |
| url | String | URL der aufgerufenen Seite. Dieses Feld ist obligatorisch. |
| title | String | Titel der aufgerufenen Seite. Dieses Feld ist obligatorisch. |
| referrers | `List` | Referrer der aufgerufenen Seiten. Dieses Feld ist optional. |
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](/user-manual/assets/advanced-targeting-tools/create-an-acquisition-channel), den Sie für eine bestimmte Website erstellen, die ID 0, nicht 1.
```dart theme={null}
try {
await kameleoonClient.addData([PageView("https://url.com", "title", [3])]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### OperatingSystem
Dieser Datentyp ist nur für Web SDKs verfügbar.
`OperatingSystem` enthält Informationen über das Betriebssystem auf dem Gerät des Besuchers.
Jeder Besucher kann nur ein `OperatingSystem` haben. Das Hinzufügen eines zweiten `OperatingSystem` überschreibt das erste.
| Name | Type | Description |
| ---- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| type | `OperatingSystems` | Liste der Betriebssysteme: `windows`, `mac`, `ios`, `linux`, `android`, `windowsPhone` . Dieses Feld ist erforderlich. |
```dart theme={null}
try {
await kameleoonClient.addData([OperatingSystem(OperatingSystem.linux)]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### 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.
| Name | Type | Description |
| ------- | --------------------- | ---------------------------------------------------------------------------------------------------- |
| cookies | `Map` | Eine String-Objekt-Map, die aus Cookie-Schlüsseln und -Werten besteht. Dieses Feld ist erforderlich. |
Jeder Besucher kann nur ein `Cookie` haben. Das Hinzufügen eines zweiten `Cookie` überschreibt das erste.
```dart theme={null}
try {
await kameleoonClient.addData([Cookie({
"my_key1": "my_value1",
"my_key2": "my_value2"
})]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
### Rückgabetypen
#### DataFile
Die `DataFile` 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.
| Name | Type | Description |
| ------------ | -------------------------- | -------------------------------------------------------------------------------------------- |
| featureFlags | `Map` | Eine Map von [`FeatureFlag`](#featureflag)-Objekten, indiziert nach Feature-Flag-Schlüsseln. |
| dateModified | `int` | Der Zeitstempel (in Millisekunden), der angibt, wann die `DataFile` zuletzt geändert wurde. |
```dart theme={null}
// Retrieves the map of feature flags from the DataFile.
// The map is keyed by feature flag identifiers, with each value being a FeatureFlag object.
final featureFlags = dataFile.featureFlags;
// Retrieves the last modification timestamp of the DataFile.
// The value is an int representing milliseconds since the Unix epoch.
final dateModified = dataFile.dateModified;
```
#### FeatureFlag
Das `FeatureFlag` stellt eine Reihe von Eigenschaften dar, die ein Feature Flag selbst definieren — zum Beispiel seine [`Variations`](#variation), [`Rules`](#rule), 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.
| Name | Type | Description |
| ------------------- | ------------------------ | ----------------------------------------------------------------------- |
| environmentEnabled | `bool` | Gibt an, ob das Feature Flag in der aktuellen Umgebung aktiviert ist. |
| defaultVariationKey | `String` | Der Schlüssel der dem Feature Flag zugeordneten Standardvariation. |
| variations | `Map` | Eine Map von `Variation`-Objekten, indiziert nach Variationsschlüsseln. |
| rules | `List` | Eine Liste von `Rule`-Objekten |
```dart theme={null}
// Check whether the feature flag is enabled in the current environment
final isEnvironmentEnabled = featureFlag.environmentEnabled
// Retrieve the key of the default variation
final defaultVariationKey = featureFlag.defaultVariationKey
// Retrieve the default variation object
final defaultVariation = featureFlag.defaultVariation
// Retrieve all variations of the feature flag as a map (key = variation key, value = Variation object)
final variations = featureFlag.variations
// Retrieve all targeting rules associated with the feature flag
final rules = featureFlag.rules
```
#### Rule
Die `Rule` stellt eine Reihe von Eigenschaften dar, die eine Regel selbst definieren — zum Beispiel ihre [`Variations`](#variation).
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.
| Name | Type | Description |
| ---------- | ------------------------ | ----------------------------------------------------------------------- |
| variations | `Map` | Eine Map von `Variation`-Objekten, indiziert nach Variationsschlüsseln. |
```dart theme={null}
// Retrieve all variations of the rule as a map (key = variation key, value = Variation object)
final variations = rule.variations
```
#### Variation
`Variation` enthält Informationen über die dem Besucher zugewiesene Variation (oder die Standardvariation, falls keine spezifische Zuweisung vorhanden ist).
| Name | Type | Description |
| ------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | `String` | Der Name der Variation. |
| key | `String` | Der eindeutige Schlüssel, der die Variation identifiziert. |
| id | `int?` | Die ID der zugewiesenen Variation (oder `-1`, wenn es sich um die Standardvariation handelt). |
| experimentId | `int?` | Die ID des mit der Variation verknüpften Experiments (oder `-1`, wenn Standard). |
| variables | `Map` | Eine Map mit den Variablen der zugewiesenen Variation, indiziert nach Variablennamen. Dies kann eine leere Sammlung sein, wenn keine Variablen zugeordnet sind. |
* Das `Variation`-Objekt liefert Details zur zugewiesenen Variation und dem zugehörigen Experiment, während das [`Variable`](#variable)-Objekt spezifische Details zu jeder Variable innerhalb einer Variation enthält.
* Stellen Sie sicher, dass Ihr Code den Fall behandelt, in dem `id` oder `experimentId` `-1` sein kann, was eine Standardvariation anzeigt.
* Die `variables`-Map kann leer sein, wenn keine Variablen mit der Variation verknüpft sind.
```dart theme={null}
// Retrieving the variation name
var variationName = variation.name
// Retrieving the variation key
var variationKey = variation.key;
// Retrieving the variation id
var variationId = variation.id;
// Retrieving the experiment id
var experimentId = variation.experimentId;
// Retrieving the variables map
var variables = variation.variables;
```
#### Variable
`Variable` enthält Informationen über eine Variable, die mit der zugewiesenen Variation verknüpft ist.
| Name | Type | Description |
| ----- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | `String` | Der eindeutige Schlüssel, der die Variable identifiziert. |
| type | `String` | Der Typ der Variable. Mögliche Werte: **BOOLEAN**, **NUMBER**, **STRING**, **JSON**. |
| value | `dynamic` | Der Wert der Variable, der von folgenden Typen sein kann: **bool**, **int**, **double**, **String**, **Map\** (json-Objekt), **\[dynamic]** (json-Array). |
```swift theme={null}
// Retrieving the variables map
var variables = variation.variables;
// Variable type can be retrieved for further processing
var type = variables["isDiscount"]?.type ?? "";
// Retrieving the variable value by key
var isDiscount = variables["isDiscount"]?.value as bool? ?? false;
// Variable value can be of different types
var title = variables["title"]?.value as String? ?? "";
```
### Veraltete Methoden
Diese Methoden sind veraltet und werden in der SDK-Version `4.0.0` entfernt.
#### isReady()
Verwenden Sie stattdessen [`isReadyAsync()`](#isreadyasync). Auf iOS und Android kann [`isReady()`](#isready) falsche (`false`) Ergebnisse zurückgeben, selbst wenn das SDK bereits mit [`defaultDataFile`](#initialize-the-kameleoon-client) initialisiert wurde.
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 Sie `isReady()`, 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()`](#runwhenready)).
```dart theme={null}
final ready = kameleoonClient.isReady();
```
##### Rückgabewert
| Name | Type | Description |
| ----- | ---- | -------------------------------------------------------------------------------------------------------- |
| ready | bool | Boolescher Wert, der den Status des SDK darstellt (korrekt initialisiert oder noch nicht einsatzbereit). |
#### getFeatureVariationKey()
* 📨 *Sendet Tracking-Daten an Kameleoon*
Verwenden Sie stattdessen [`getVariation()`](#getvariation).
Verwenden Sie diese Methode, um den Feature-Variationsschlüssel für einen Besucher zu erhalten. Diese Methode benötigt `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.
```dart theme={null}
String featureKey = "new_checkout";
String variationKey = "";
try {
variationKey = await kameleoonClient.getFeatureVariationKey(featureKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error has occurred; feature flag isn't found in current configuration.
} on FeatureEnvironmentDisabled {
// The feature flag is disabled for the environment.
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error.
}
switch(variationKey) {
case 'on':
// Main variation key is selected for visitorCode
break;
case 'alternative_variation':
// Alternative variation key
break;
default:
// Default variation key
break;
}
```
##### Argumente
| Name | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------------------------------------ |
| featureKey | String | Schlüssel der Funktion, die Sie einem Benutzer aussetzen möchten. Dieses Feld ist obligatorisch. |
##### Rückgabewert
| Type | Description |
| ---------------- | ----------------------------------------------------------------------- |
| `Future` | Variationsschlüssel des für einen Besucher registrierten Feature Flags. |
##### Ausgelöste Ausnahmen
| Type | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SDKNotReady | Ausnahme, die anzeigt, dass das SDK seine Initialisierung nicht abgeschlossen hat. |
| FeatureNotFound | Ausnahme, die anzeigt, dass die angeforderte Feature-ID in der internen Konfiguration des SDK nicht gefunden wurde. Diese Ausnahme bedeutet normalerweise, dass das Feature Flag auf der Kameleoon-Seite nicht aktiviert wurde (aber der Code, der die Funktion implementiert, bereits in der Anwendung bereitgestellt wird). |
| PlatformException | Ausnahme, die anzeigt, dass die native Plugin-Integration nicht korrekt funktioniert. |
#### getActiveFeatures()
* Verwenden Sie stattdessen [`getVariations()`](#getvariations).
* Hieß zuvor `getFeatureListForVisitorCode`, das in der SDK-Version `4.0.0` entfernt wurde.
Die Methode `getActiveFeatures` ruft Informationen über die für den Besucher verfügbaren aktiven Feature Flags ab.
```dart theme={null}
try {
final activeFeatures = await kameleoonClient.getActiveFeatures();
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
##### Rückgabewert
| Type | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `Future>` | Map, die die zugewiesenen Variationen der aktiven Funktionen unter Verwendung der Schlüssel der entsprechenden aktiven Funktionen enthält. |
#### getFeatureVariable()
* 📨 *Sendet Tracking-Daten an Kameleoon*
- Verwenden Sie stattdessen [`getVariation()`](#getvariation).
- Diese Methode hieß zuvor `obtainFeatureVariable`, die in der SDK-Version `3.0.0` entfernt wurde.
Diese Methode erhält einen Variablenwert des Variationsschlüssels für einen bestimmten Benutzer. Sie benötigt einen `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.
```dart theme={null}
String featureKey = "feature_key";
String variableKey = "product_number";
int recommendedProductsNumber = 5;
try {
recommendedProductsNumber = await kameleoonClient.getFeatureVariable(featureKey, variableKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error has occurred; feature flag isn't found in current configuration.
} on FeatureEnvironmentDisabled {
// The feature flag is disabled for the environment.
} on FeatureVariableNotFound {
// Requested variable not defined in Kameleoon.
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error.
}
setState(() {
_recommendedProductsNumber = recommendedProductsNumber;
});
```
##### Argumente
| Name | Type | Description |
| ----------- | ------ | ------------------------------------------------------------------------------------------------ |
| featureKey | String | Schlüssel der Funktion, die Sie einem Benutzer aussetzen möchten. Dieses Feld ist obligatorisch. |
| variableKey | String | Name der Variable, für die Sie einen Wert erhalten möchten. Dieses Feld ist obligatorisch. |
##### Rückgabewert
| Type | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Future` | Wert der Variable der Variation, die für einen Besucher für dieses Feature Flag registriert ist. Mögliche Typen: `bool`, `int`, `double`, `String`, `List`, `Map` |
##### Ausgelöste Ausnahmen
| Type | Description |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SDKNotReady | Ausnahme, die anzeigt, dass das SDK seine Initialisierung nicht abgeschlossen hat. |
| FeatureNotFound | Ausnahme, die anzeigt, dass die angeforderte Feature-ID in der internen Konfiguration des SDK nicht gefunden wurde. Diese Ausnahme bedeutet normalerweise, dass das Feature Flag auf der Kameleoon-Seite nicht aktiviert wurde (aber der Code, der die Funktion implementiert, bereits in der Anwendung bereitgestellt wird). |
| FeatureEnvironmentDisabled | Ausnahme, die anzeigt, dass das Feature Flag für die aktuelle Umgebung des Besuchers deaktiviert ist (z. B. Produktion, Staging oder Entwicklung). |
| FeatureVariableNotFound | Ausnahme, die anzeigt, dass die angegebene Variable nicht gefunden wurde. Überprüfen Sie, ob der Variablenschlüssel in der Kameleoon-App mit dem Schlüssel in Ihrem Code übereinstimmt. |
| PlatformException | Ausnahme, die anzeigt, dass die native Plugin-Integration nicht korrekt funktioniert. |
#### getFeatureVariationVariables()
* Verwenden Sie stattdessen [`getVariation()`](#getvariation).
* Diese Methode hieß zuvor `getFeatureAllVariables`, die in der SDK-Version `4.0.0` entfernt wurde.
Um alle Variablen einer Funktion abzurufen, rufen Sie diese Methode auf. Sie können Ihre Feature-Variablen in der Kameleoon-App ändern.
Diese Methode benötigt einen Eingabeparameter: `featureKey`. Sie gibt die Daten als Typ `Map` 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.
```dart theme={null}
final featureKey = "featureKey";
final variationKey = "variationKey";
try {
final allVariables = await client.getFeatureVariationVariables(featureKey, variationKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error has occurred; feature flag isn't found in current configuration.
} on FeatureEnvironmentDisabled {
// The feature flag is disabled for the environment.
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error.
}
```
##### Argumente
| Name | Type | Description |
| ------------ | ------ | ----------------------------------------------------------------------------------------------- |
| featureKey | String | Identifikationsschlüssel der Funktion, die Sie erhalten möchten. Dieses Feld ist obligatorisch. |
| variationKey | String | Der Schlüssel der Variation, die Sie erhalten möchten. Dieses Feld ist obligatorisch. |
##### Rückgabewert
| Type | Description |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Future>` | Mit diesem Feature Flag verknüpfte Daten. Die Werte können int, double, bool, String, List oder Map sein (abhängig vom auf der Weboberfläche definierten Typ). |
##### Ausgelöste Ausnahmen
| Type | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FeatureNotFound | Ausnahme, die anzeigt, dass die angeforderte Funktion in der internen Konfiguration des SDK nicht gefunden wurde. Diese Ausnahme ist normalerweise normal und bedeutet, dass das Feature Flag auf der Kameleoon-Seite nicht aktiviert wurde. |
| FeatureEnvironmentDisabled | Ausnahme, die anzeigt, dass das Feature Flag für die aktuelle Umgebung des Besuchers deaktiviert ist (z. B. Produktion, Staging oder Entwicklung). |
| FeatureVariationNotFound | Ausnahme, die anzeigt, dass die angeforderte Variations-ID in der internen Konfiguration des SDK nicht gefunden wurde. Diese Ausnahme ist normalerweise normal und bedeutet, dass das der Variation entsprechende Experiment auf der Kameleoon-Seite nicht aktiviert wurde. |
| PlatformException | Ausnahme, die anzeigt, dass die native Plugin-Integration nicht korrekt funktioniert. |