> ## 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.
# Rust SDK
> Integrieren Sie das Kameleoon Rust SDK, um Experimente auszuführen und Feature Flags in Rust-Diensten und Web-Backends zu aktivieren.
Mit dem Kameleoon Rust SDK können Sie Experimente ausführen und Feature Flags in Ihren Rust-Diensten und Web-Backends aktivieren.
**Erste Schritte**: Hilfe für den Einstieg finden Sie im [Entwicklerhandbuch](#entwicklerhandbuch).
**Changelog**: Aktuelle Version des Rust SDK: 0.9.3 [Changelog](https://github.com/Kameleoon/client-rust/blob/master/CHANGELOG.md).
**SDK-Methoden**: Die vollständige Referenzdokumentation des Rust SDK finden Sie im Abschnitt [Referenz](#referenz).
## Entwicklerhandbuch
Dieses Handbuch soll Ihnen helfen, das Rust SDK schnell zu integrieren und mit der Auswertung von Feature Flags in Ihrer Rust-Anwendung zu beginnen.
### Erste Schritte
#### Den Rust-Client installieren
Wenn Sie im aktuellen Arbeitsbereich arbeiten, fügen Sie das SDK als Pfadabhängigkeit zusammen mit `tokio` hinzu, da mehrere SDK-Methoden asynchron sind:
```toml title="Cargo.toml" theme={null}
[dependencies]
kameleoon-client = "0.9.3"
```
#### Zusätzliche Konfiguration
Erstellen Sie eine Konfigurationsdatei `client-rust.json`, um Anmeldedaten bereitzustellen und das Verhalten des SDK anzupassen. Sie können auch [unsere Beispielkonfigurationsdatei herunterladen](/assets/developer-docs/sdks/web-sdks/client-configs/client-config.json).
Wir empfehlen, diese Datei im Standardpfad `/etc/kameleoon/client-rust.json` zu speichern. Sie können sie jedoch auch an einer beliebigen Stelle im Classpath als `client-rust.json` speichern.
Das Rust SDK kann entweder mit einer JSON-Datei konfiguriert werden, die von `create_with_path()` verwendet wird, oder durch Erstellen einer `KameleoonClientConfig`-Instanz mit `create_with_config()` direkt im Code.
Die folgende Tabelle zeigt die verfügbaren Eigenschaften, die Sie festlegen können:
| Schlüssel (Code / Konfigurationsdatei) | Beschreibung | Standardwert |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `client_id` / `clientId` (*erforderlich*) | Erforderlich für die Authentifizierung beim Kameleoon-Dienst. Um Ihre `client_id` zu finden, lesen Sie die Dokumentation zu den [API-Zugangsdaten](/user-manual/account-and-team-management/users-and-teams/api-credentials). | |
| `client_secret` / `clientSecret` (*erforderlich*) | Erforderlich für die Authentifizierung beim Kameleoon-Dienst. Um Ihr `client_secret` zu finden, lesen Sie die Dokumentation zu den [API-Zugangsdaten](/user-manual/account-and-team-management/users-and-teams/api-credentials). | |
| `session_duration` / `sessionDurationMinutes` (*optional*) | Zeitintervall in Minuten, während dessen das SDK einen Besucher und seine zugehörigen Daten im Speicher behält. | `30` Minuten |
| `refresh_interval` / `refreshIntervalMinutes` (*optional*) | Intervall in Minuten, das verwendet wird, um die Konfiguration aktiver Experimente und Feature Flags zu aktualisieren. | `60` Minuten |
| `default_timeout` / `defaultTimeoutMillis` (*optional*) | Standard-Timeout in Millisekunden für SDK-Netzwerkanfragen. | `10000` Millisekunden |
| `tracking_interval` / `trackingIntervalMillis` (*optional*) | Intervall in Millisekunden, das zum Bündeln von Tracking-Anfragen verwendet wird. Werte werden auf den Bereich `[1000, 5000]` beschränkt. | `1000` Millisekunden |
| `environment` / `environment` (*optional*) | Umgebung, aus der die Feature-Flag-Konfiguration verwendet werden soll. Der Wert kann `production`, `staging` oder `development` sein. | `production` |
| `top_level_domain` / `topLevelDomain` (*optional*) | Die aktuelle Top-Level-Domain Ihrer Website. Verwenden Sie das Format `example.com` ohne Protokoll oder Subdomains. | `None` |
| `proxy_host` / `proxyHost` (*optional*) | Proxy-Host für ausgehende SDK-Aufrufe. Unterstützte Formate: `https://my.prox`, `https://my.prox:4545`, `socks5://192.168.1.1:9000`. | `None` |
| `network_domain` / `networkDomain` (*optional*) | Benutzerdefinierte Domain, die von SDKs für ausgehende Anfragen verwendet wird, häufig für Proxying. Muss eine gültige Domain sein (z. B. example.com oder sub.example.com). Ungültige Formate verwenden standardmäßig den Wert von Kameleoon. | `None` |
#### Den Kameleoon-Client initialisieren
Nachdem Sie das SDK installiert und Ihre Anmeldedaten konfiguriert haben, erstellen Sie einen `KameleoonClient` mithilfe der `KameleoonClientFactory`.
```rust theme={null}
use std::time::Duration;
use kameleoon_client::config::KameleoonClientConfigBuilder;
use kameleoon_client::factory::KameleoonClientFactory;
async fn create_client() -> Result {
let site_code = "a8st4f59bj";
let client = KameleoonClientFactory::create_with_path(site_code, "/etc/kameleoon/client-rust.json")?;
client.initialize().await?;
Ok(client)
}
```
```rust theme={null}
use std::time::Duration;
use kameleoon_client::config::KameleoonClientConfigBuilder;
use kameleoon_client::factory::KameleoonClientFactory;
async fn create_client() -> Result {
let site_code = "a8st4f59bj";
let config = KameleoonClientConfigBuilder::default()
.client_id("".to_owned()) // mandatory
.client_secret("".to_owned()) // mandatory
.refresh_interval(Duration::from_mins(60)) // optional (60 minutes by default)
.session_duration(Duration::from_mins(30)) // optional (30 minutes by default)
.default_timeout(Duration::from_millis(10_000)) // optional (10000 ms by default)
.tracking_interval(Duration::from_millis(1_000)) // optional (10000 ms by default)
.environment("development".to_owned()) // optional
.top_level_domain(".example.com") // mandatory if you use hybrid mode (engine or web experiments)
.proxy_host("http://192.168.0.25:8080".to_owned()) // optional
.network_domain("example.com".to_owned()) // optional
.build()
.unwrap();
let client = KameleoonClientFactory::create_with_config(site_code, config)?;
client.initialize().await?;
Ok(client)
}
```
Ein `KameleoonClient` ist das Hauptobjekt, das zum Auswerten von Feature Flags, zum Hinzufügen von Besucherdaten und zum Senden von Tracking-Anfragen verwendet wird.
* Es wird empfohlen, `KameleoonClient` als Singleton-Objekt zu verwenden, da es als Brücke zwischen Ihrer Anwendung und der Kameleoon-Plattform dient. Es stellt alle erforderlichen Methoden und Eigenschaften zur effizienten Ausführung von Experimenten bereit.
* Das Rust SDK initialisiert sich asynchron. Sie sollten [`initialize()`](#initialize) aufrufen, bevor Sie sich im Produktionscode auf die Feature-Auswertung verlassen.
#### Einen Feature Flag aktivieren
##### Einem Benutzer eine eindeutige ID zuweisen
Um einem Benutzer eine eindeutige ID zuzuweisen, können Sie die Methode [`get_visitor_code()`](#get_visitor_code) verwenden. Wenn ein **Besuchercode** nicht existiert (aus dem Cookie der Request-Header), generiert die Methode eine zufällige eindeutige ID oder verwendet einen `default_visitor_code`, den Sie selbst generiert haben. Die ID wird dann in einem Cookie der Response-Header gesetzt.
Wenn Sie Kameleoon im [Hybridmodus](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) verwenden, stellt der Aufruf der Methode `get_visitor_code()` sicher, dass die eindeutige ID (**Besuchercode**) zwischen der Anwendungsdatei `engine.js` (zuvor `kameleoon.js` genannt) und dem SDK geteilt wird.
##### Eine Flag-Konfiguration abrufen
Um einen Feature Flag in Ihrem Code zu implementieren, müssen Sie den Feature Flag zunächst in Ihrem Kameleoon-Konto erstellen.
Um den Status oder die Variation eines Feature Flags für einen bestimmten Benutzer zu ermitteln, sollten Sie die Methode [`get_variation()`](#get_variation) oder [`is_feature_active()`](#is_feature_active) verwenden, um die Konfiguration basierend auf dem `feature_key` abzurufen.
Die Methode `get_variation()` verarbeitet sowohl einfache Feature Flags mit ON/OFF-Zuständen als auch komplexere Flags mit mehreren Variationen. Die Methode ruft die entsprechende Variation für den Benutzer ab, indem sie die Feature-Regeln überprüft, die Variation zuweist und sie basierend auf dem `feature_key` und dem `visitor_code` zurückgibt.
Die Methode `is_feature_active()` kann verwendet werden, wenn Sie die Konfiguration eines einfachen Feature Flags abrufen möchten, der nur einen ON- oder OFF-Zustand hat, im Gegensatz zu komplexeren Feature Flags mit mehreren Variationen oder Targeting-Optionen.
Wenn Ihr Feature Flag zugehörige Variablen hat (wie spezifische Verhaltensweisen, die mit jeder Variation verbunden sind), ermöglicht Ihnen `get_variation()` auch den Zugriff auf das [`Variation`](#variation)-Objekt, das Details zur zugewiesenen Variation und ihrem zugehörigen Experiment bereitstellt. Diese Methode prüft, ob der Benutzer angesprochen wird, findet die dem Besucher zugewiesene Variation und speichert sie. Wenn `track=true`, sendet das SDK das Expositions-Event bei der nächsten Tracking-Anfrage an das angegebene Experiment, das automatisch basierend auf dem [`tracking_interval`](#zusätzliche-konfiguration) des SDK ausgelöst wird. Standardmäßig ist dieses Intervall auf 1000 Millisekunden (1 Sekunde) eingestellt.
Mit der Methode `get_variation()` können Sie steuern, ob Tracking durchgeführt wird. Wenn `track=false`, werden vom SDK keine Expositions-Events gesendet. Dies ist nützlich, wenn Sie es vorziehen, Daten nicht über das SDK zu verfolgen und sich stattdessen auf clientseitiges Tracking zu verlassen, das z. B. von der Kameleoon-Engine verwaltet wird. Darüber hinaus ist die Einstellung `track=false` hilfreich bei der Verwendung der Methode `get_variations()`, bei der Sie möglicherweise nur die Variationen für alle Flags benötigen, ohne Tracking-Events auszulösen. Wenn Sie mehr darüber erfahren möchten, wie Tracking funktioniert, lesen Sie [diesen Artikel](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics).
##### Datenpunkte hinzufügen, um einen Benutzer anzusprechen oder Besuche in Berichten zu filtern / aufzuschlüsseln
Um einen Benutzer anzusprechen, stellen Sie sicher, dass Sie relevante Datenpunkte zu seinem Profil hinzugefügt haben, bevor Sie die Feature-Variation abrufen oder prüfen, ob der Flag aktiv ist. Verwenden Sie die Methode [`add_data()`](#add_data), 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 [`get_remote_visitor_data()`](#get_remote_visitor_data). Diese Methode ruft Daten asynchron von den Servern ab. Es ist wichtig, `get_remote_visitor_data()` *vor* dem Abrufen der Variation oder der Überprüfung, ob der Feature Flag aktiv ist, aufzurufen, da diese Daten erforderlich sein können, um einen Benutzer einer bestimmten Variation zuzuweisen.
Um mehr über die verfügbaren Targeting-Bedingungen zu erfahren, lesen Sie den [ausführlichen Artikel zu diesem Thema](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
Darüber hinaus sind die Datenpunkte, die Sie zum 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. Der Kameleoon-Hybridmodus sammelt automatisch eine Vielzahl von Datenpunkten auf der Clientseite, was die Aufschlüsselung Ihrer Ergebnisse anhand dieser vorgesammelten Datenpunkte erleichtert. Die vollständige Liste finden Sie [hier](/de/user-manual/experiment-analytics/analyze-results/results-page/results-page-settings#zielgruppe-aufschlüsseln).
Wenn Sie zusätzliche Datenpunkte über das hinaus erfassen müssen, was automatisch gesammelt 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()`](#flush) aufzurufen, um die gesammelten Daten zur Analyse an die Kameleoon-Server zu senden.
Um die Genauigkeit Ihrer Ergebnisse sicherzustellen, wird empfohlen, Bots mithilfe des Datentyps [`UserAgent`](#useragent) herauszufiltern.
##### Ziel-Conversions verfolgen
Wenn ein Benutzer eine gewünschte Aktion (z. B. einen Kauf) ausführt, wird dies als Conversion erfasst. Um Conversions zu verfolgen, verwenden Sie die Methode [`track_conversion()`](#track_conversion) und geben Sie die erforderlichen Parameter `visitor_code` und `goal_id` an.
Die Anfrage zur Conversion-Verfolgung wird zusammen mit der nächsten geplanten Tracking-Anfrage gesendet, die das SDK in regelmäßigen Intervallen (definiert durch [`tracking_interval`](#zusätzliche-konfiguration)) sendet. Wenn Sie die Anfrage sofort senden möchten, verwenden Sie die Methode [`flush_instant()`](#flush).
##### Events an Analyselösungen senden
Um Conversions zu verfolgen und Expositions-Events an Ihre Kundenanalyselösung zu senden, müssen Sie Kameleoon zunächst im [Hybridmodus](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/) implementieren. Verwenden Sie dann die Methode [`get_engine_tracking_code()`](#get_engine_tracking_code).
Die Methode `get_engine_tracking_code()` ruft den eindeutigen Tracking-Code ab, der zum Senden von Expositions-Events an Ihre Analyselösung erforderlich ist. Mit dieser Methode können Sie Events aufzeichnen und an die gewünschte Analyseplattform senden.
### Verwendung eines benutzerdefinierten Bucketing-Schlüssels
Standardmäßig verwendet Kameleoon eine eindeutige, anonyme Besucher-ID (`visitor_code`), um Benutzer Feature-Flag-Variationen zuzuweisen. Diese ID wird in der Regel auf dem Gerät des Benutzers generiert und gespeichert (in einem Browser-Cookie für clientseitige 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.
Mit der Option **Benutzerdefinierter Bucketing-Schlüssel** können Sie dieses Standardverhalten außer Kraft setzen, indem Sie Ihren eigenen benutzerdefinierten Bezeichner für das Bucketing bereitstellen. Dieses Überschreiben stellt sicher, dass die Zuweisungslogik von Kameleoon Ihren angegebenen Schlüssel anstelle des Standard-`visitor_code` verwendet.
#### Anwendungsfälle
Die Verwendung eines benutzerdefinierten Bucketing-Schlüssels ist unerlässlich, um die Konsistenz und Genauigkeit Ihrer 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 einen Bezeichner wie eine `account_id` verwenden. Benutzerdefinierte Bucketing-Schlüssel sind entscheidend für A/B-Test-Funktionen, die ein ganzes 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 einem besseren Benutzererlebnis führt.
#### Technische Details
Wenn Sie einen benutzerdefinierten Bucketing-Schlüssel für einen Feature Flag konfigurieren, stellen Sie Kameleoon einen bestimmten Bezeichner aus den Daten Ihrer Anwendung zur Verfügung:
```rust theme={null}
use kameleoon_client::data::CustomData;
client.add_data(visitor_code, [CustomData::new(42, vec!["new_visitor_code".to_owned()])])?;
```
* **Bereitstellung des benutzerdefinierten Schlüssels:** Sie stellen Ihren benutzerdefinierten Bezeichner dem Kameleoon SDK mithilfe der Methode [`add_data()`](#add_data) zur Verfügung. In dieser Methode übergeben Sie Ihren gewählten benutzerdefinierten Bucketing-Schlüssel als [`CustomData`](#customdata)-Objekt. Hier bezieht sich `new_visitor_code` auf den Bezeichner, den Sie für Ihr Bucketing verwenden möchten (zum Beispiel die neue `user_id` oder `account_id`).
Damit der benutzerdefinierte Bucketing-Schlüssel ordnungsgemäß funktioniert, muss er auch während des Erstellungs- oder Bearbeitungsprozesses des Feature Flags definiert und konfiguriert werden. Ohne diese entsprechende Konfiguration wendet das Bucketing des SDK Ihren benutzerdefinierten Schlüssel nicht an. Detaillierte Anweisungen zur Einrichtung 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 `add_data()` bereitgestellt wird, verwenden alle Hash-Berechnungen zur Zuweisung von Benutzern zu Variationen diesen `new_visitor_code` (Ihren benutzerdefinierten Schlüssel) anstelle des Standard-`visitor_code`. Die Verwendung des `new_visitor_code` bedeutet, dass die Bucketing-Entscheidung an Ihren benutzerdefinierten Bezeichner gebunden ist, was konsistente Zuweisungen über verschiedene Kontexte hinweg gewährleistet, in denen dieser Bezeichner vorhanden ist.
* **Datentracking und Analytik:** Es ist wichtig zu beachten, dass, obwohl der `new_visitor_code` (Ihr benutzerdefinierter Schlüssel) für Bucketing-Entscheidungen verwendet wird, **alle nachfolgenden Daten (z. B. Tracking-Events und Conversions) gesendet und mit dem *ursprünglichen* `visitor_code` verknüpft werden.** Diese Trennung stellt sicher, dass Ihre Analytik die individuellen Benutzerreisen und Interaktionen innerhalb des breiteren Kontexts Ihres Experiments genau widerspiegelt, auch 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 umfassendes Reporting intakt.
#### Technische Anforderungen
Um einen benutzerdefinierten Bucketing-Schlüssel effektiv zu verwenden:
* Der Schlüssel muss ein `&str` sein.
* Er muss für die Entität, die Sie bucketieren möchten, eindeutig sein (zum Beispiel sollte bei Verwendung einer `user_id` die ID jedes Benutzers eindeutig sein).
* Der Schlüssel muss dem SDK genau in dem Moment zur Verfügung stehen, 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, mit denen Sie Benutzer in Ihren Kampagnen ansprechen können. Eine Liste der von diesem SDK unterstützten Bedingungen finden Sie unter [Besuchsverlauf zur Ansprache von Benutzern verwenden](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
Sie können auch Ihre eigenen [externen Daten zur Ansprache von Benutzern](/developer-docs/apis/data-api-rest/tutorials/storing-and-retrieving-external-data-to-target-users) verwenden.
### Cross-Device-Experimentierung
Um Besucher zu unterstützen, die von mehreren Geräten aus auf eine App zugreifen, ermöglicht Kameleoon die Synchronisierung zuvor gesammelter Besucherdaten über jedes Gerät des Besuchers hinweg und die Abgleichung seines Besuchsverlaufs über Geräte hinweg durch Cross-Device-Experimentierung. Fallstudien und detaillierte Informationen darüber, wie Kameleoon Daten geräteübergreifend verarbeitet, finden Sie im [Artikel zur Cross-Device-Experimentierung](/developer-docs/cross-device-experimentation).
#### Synchronisierung von Custom Data über Geräte hinweg
Obwohl die Synchronisierung von Custom-Mapping verwendet wird, um Besucherdaten geräteübergreifend abzugleichen, ist sie nicht immer erforderlich. Im Folgenden sind zwei Szenarien aufgeführt, in denen eine Custom-Mapping-Synchronisierung nicht erforderlich ist:
**Gleiche Benutzer-ID auf allen Geräten**
Wenn dieselbe Benutzer-ID auf allen Geräten konsistent verwendet wird, erfolgt die Synchronisierung automatisch ohne Custom-Mapping-Synchronisierung. Es genügt, die Methode `get_remote_visitor_data()` aufzurufen, wenn Sie die zwischen mehreren Geräten gesammelten Daten synchronisieren möchten.
**Multi-Server-Instanzen mit konsistenten IDs**
In komplexen Setups mit mehreren Servern (z. B. verteilten Serverinstanzen), bei denen dieselbe Benutzer-ID serverübergreifend verfügbar ist, ist die Synchronisierung zwischen Servern (mit `get_remote_visitor_data()`) ohne zusätzliche Custom-Mapping-Synchronisierung ausreichend.
Kunden, die zusätzliche Daten benötigen, können sich für weitere Informationen auf die Beschreibung der Methode [`get_remote_visitor_data()`](#get_remote_visitor_data) beziehen. Im folgenden Code wird davon ausgegangen, dass derselbe eindeutige Bezeichner (in diesem Fall der `visitor_code`, der auch als `userId` bezeichnet werden kann) zwischen den beiden Geräten konsistent für eine genaue Datenabfrage verwendet wird.
Wenn Sie gesammelte Daten in Echtzeit synchronisieren möchten, müssen Sie den Bereich **Visitor** für Ihre Custom Data wählen.
```rust title="Device A" theme={null}
// In this example, a Custom data with index `90` was set to "Visitor" scope in Kameleoon.
use kameleoon_client::data::CustomData;
const VISITOR_SCOPE_CUSTOM_DATA_INDEX: u32 = 90;
client.add_data(visitor_code, [CustomData::new(VISITOR_SCOPE_CUSTOM_DATA_INDEX, vec!["your data".to_owned()])])?;
client.flush_instant(visitor_code).await?;
```
```rust title="Device B" theme={null}
// Before working with the data, call the `get_remote_visitor_data` method.
client.get_remote_visitor_data(visitor_code, None).await?;
// After calling the method, the SDK on Device B will have access to CustomData of Visitor scope defined on Device A.
// So, "your data" will be available for targeting and tracking the visitor.
```
#### Verwendung von Custom Data für die Sitzungszusammenführung
[Cross-Device-Experimentierung](/developer-docs/cross-device-experimentation) ermöglicht es, den Verlauf eines Besuchers über jedes seiner Geräte hinweg zu kombinieren (Verlaufsabgleich). Der Verlaufsabgleich ermöglicht das Zusammenführen verschiedener Besuchersitzungen zu einer einzigen. Um den Besuchsverlauf abzugleichen, verwenden Sie [`CustomData`](#customdata), um einen eindeutigen Bezeichner für den Besucher bereitzustellen. Weitere Informationen finden Sie in der [dedizierten Dokumentation](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation).
Nachdem der geräteübergreifende Abgleich aktiviert wurde, ruft der Aufruf von [`get_remote_visitor_data()`](#get_remote_visitor_data) mit dem Parameter `userId` alle bekannten Daten für einen bestimmten Benutzer ab.
Sitzungen mit demselben Bezeichner sehen in einem Experiment immer dieselbe Variation. In der Besucheransicht der Ergebnisseiten Ihres Experiments werden diese Sitzungen als einzelner Besucher angezeigt.
Die SDK-Konfiguration stellt sicher, dass zugehörige Sitzungen immer dieselbe Variation des Experiments sehen. Es gibt jedoch einige Einschränkungen hinsichtlich der geräteübergreifenden Variationszuweisung. Diese Einschränkungen werden [hier](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights) beschrieben.
Folgen Sie der Anleitung [Aktivieren der geräteübergreifenden Verlaufsabgleichung](#cross-device-experimentierung), um Ihre Custom Data auf der Kameleoon-Plattform einzurichten.
Anschließend können Sie das SDK normal verwenden. Die folgenden Methoden können im Kontext der Sitzungszusammenführung hilfreich sein:
* `get_remote_visitor_data()` mit hinzugefügtem `UniqueIdentifier(true)` – um Daten für alle verknüpften Besucher abzurufen.
* [`track_conversion()`](#track_conversion) oder [`flush()`](#flush) mit hinzugefügten `UniqueIdentifier(true)`-Daten – um einige Daten für einen bestimmten Besucher zu verfolgen, der einem anderen Besucher zugeordnet ist.
Da die Custom Data, die Sie als Bezeichner verwenden, auf den **Visitor-Bereich** gesetzt sein muss, müssen Sie die [geräteübergreifende Synchronisierung von Custom Data](/developer-docs/cross-device-experimentation) verwenden, um den Bezeichner mit der Methode [`get_remote_visitor_data()`](#get_remote_visitor_data) auf jedem Gerät abzurufen.
Hier ist ein Beispiel für die Verwendung von Custom Data zur Sitzungszusammenführung.
```rust theme={null}
// In this example, 91 represents the Custom Data's index configured as a unique identifier in Kameleoon.
use kameleoon_client::data::{CustomData, UniqueIdentifier};
const MAPPING_INDEX: u32 = 91;
const FEATURE_KEY: &str = "ff123";
let anonymous_visitor_code = "anonymous-visitor";
let user_id = "authenticated-user";
// 1. Before the visitor is authenticated
// Retrieve the variation for an unauthenticated visitor.
// Assume anonymousVisitorCode is the randomly generated ID for that visitor.
let anonymous_variation = client.get_variation(anonymous_visitor_code, FEATURE_KEY)?;
// 2. After the visitor is authenticated
// Assume `userId` is the visitor code of the authenticated visitor.
client.add_data(anonymous_visitor_code, [CustomData::new(MAPPING_INDEX, vec![user_id.to_owned()])])?;
client.flush_instant(anonymous_visitor_code).await?;
// Indicate that `userId` is a unique identifier.
client.add_data(user_id, [UniqueIdentifier::new(true)])?;
// 3. After the visitor was authorized
// Retrieve the variation for the `userId`, which will match the anonymous visitor code's variation.
let user_variation = client.get_variation(user_id, FEATURE_KEY)?;
let is_same_variation = user_variation.key == anonymous_variation.key; // True
// `userId` and `anonymousVisitorCode` are now linked and can be tracked as a single visitor.
client.track_conversion(user_id, 123)?;
// Additionally, the linked visitors share all fetched previously tracked remote data.
client.get_remote_visitor_data(user_id, None).await?;
```
In diesem Beispiel hat die Anwendung eine Anmeldeseite. Da die Benutzer-ID zum Zeitpunkt der Anmeldung unbekannt ist, wird ein anonymer Besucherbezeichner verwendet, der von der Methode [`get_visitor_code()`](#get_visitor_code) generiert wurde. Nachdem sich der Benutzer angemeldet hat, wird der anonyme Besucher der Benutzer-ID zugeordnet und als eindeutiger Bezeichner für den Besucher verwendet.
### Protokollierung
Das SDK generiert Protokolle, um verschiedene interne Prozesse und Probleme widerzuspiegeln.
#### Protokollebenen
Das SDK unterstützt die Konfiguration der Begrenzung der Protokollierung nach einer Protokollebene.
```rust theme={null}
use kameleoon_client::logging::{KameleoonLogger, LogLevel};
// The `None` log level does not allow logging.
KameleoonLogger::set_log_level(LogLevel::None);
// The `Error` log level only allows logging issues that may affect the SDK's primary behaviour.
KameleoonLogger::set_log_level(LogLevel::Error);
// The `Warning` log level allows logging issues which may require an attention.
// It extends the `ERROR` log level.
// The `WARNING` log level is a default log level.
KameleoonLogger::set_log_level(LogLevel::Warning);
// The `Info` log level allows logging general information on the SDK's internal processes.
// It extends the `WARNING` log level.
KameleoonLogger::set_log_level(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 our support team
// to assist with internal troubleshooting.
KameleoonLogger::set_log_level(LogLevel::Debug);
```
#### Benutzerdefinierte Protokollverarbeitung
Das SDK schreibt seine Protokolle standardmäßig in die Konsolenausgabe. Dieses Verhalten kann überschrieben werden.
Die Begrenzung der Protokollierung nach einer Protokollebene erfolgt unabhängig von der Logik der Protokollverarbeitung.
```rust theme={null}
use kameleoon_client::logging::{KameleoonLogger, LogLevel, Logger};
use log::{error, warn, info, debug};
pub struct CustomLogger;
impl Logger for CustomLogger {
// `log` method accepts logs from the SDK
fn log(&self, log_level: LogLevel, message: &str) {
// Custom log handling logic here. For example:
match log_level {
LogLevel::Error => error!("{}", message),
LogLevel::Warning => warn!("{}", message),
LogLevel::Info => info!("{}", message),
LogLevel::Debug => debug!("{}", message),
}
}
}
// 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::set_log_level(LogLevel::Debug); // Optional; defaults to `LogLevel.WARNING`.
KameleoonLogger::set_logger(Box::new(CustomLogger));
```
## Referenz
Dies ist die vollständige Referenzdokumentation für das Rust SDK.
### Initialisierung
#### create()
Um das SDK zu verwenden, erstellen Sie einen `KameleoonClient` aus einer `KameleoonClientConfig`-Instanz mit `KameleoonClientFactory::create_with_config()`/`KameleoonClientFactory::create_with_file()`.
```rust theme={null}
use std::time::Duration;
use kameleoon_client::config::KameleoonClientConfigBuilder;
use kameleoon_client::factory::KameleoonClientFactory;
let config = KameleoonClientConfigBuilder::default()
.client_id("".to_owned()) // mandatory
.client_secret("".to_owned()) // mandatory
.refresh_interval(Duration::from_mins(60)) // optional (60 minutes by default)
.session_duration(Duration::from_mins(30)) // optional (30 minutes by default)
.default_timeout(Duration::from_millis(10_000)) // optional (10000 ms by default)
.tracking_interval(Duration::from_millis(1_000)) // optional (10000 ms by default)
.environment("development".to_owned()) // optional
.top_level_domain(".example.com") // mandatory if you use hybrid mode (engine or web experiments)
.proxy_host("http://192.168.0.25:8080".to_owned()) // optional
.network_domain("example.com".to_owned()) // optional
.build()
.unwrap();
let client = KameleoonClientFactory::create_with_config(site_code, config)?;
```
##### Argumente
| Name | Typ | Beschreibung |
| ---------------------------- | ----------------------- | ----------------------------------------------------------------- |
| `site_code` (*erforderlich*) | `&str` | Eindeutiger Schlüssel des vom SDK verwendeten Kameleoon-Projekts. |
| `config` (*erforderlich*) | `KameleoonClientConfig` | SDK-Konfigurationsobjekt. |
```rust theme={null}
use kameleoon_client::factory::KameleoonClientFactory;
let client = KameleoonClientFactory::create_with_file("a8st4f59bj", "/etc/kameleoon/client-rust.json")?;
```
##### Argumente
| Name | Typ | Beschreibung |
| ------------------------------ | ------ | ----------------------------------------------------------------- |
| `site_code` (*erforderlich*) | `&str` | Eindeutiger Schlüssel des vom SDK verwendeten Kameleoon-Projekts. |
| `config_path` (*erforderlich*) | `&str` | Pfad zur JSON-Konfigurationsdatei. |
##### Rückgabewert
| Typ | Beschreibung |
| ----------------------------------------- | ----------------------------------------------------------------------- |
| `Result` | Eine Client-Instanz bei Erfolg, andernfalls ein Initialisierungsfehler. |
##### Fehler
| Typ | Beschreibung |
| ------------------------------------- | ---------------------------------- |
| `ErrorCode::ConfigCredentialsInvalid` | Die SDK-Anmeldedaten fehlen. |
| `ErrorCode::SiteCodeIsEmpty` | Der angegebene Site-Code ist leer. |
#### initialize()
Wartet auf die Initialisierung des Kameleoon-Clients, entweder unter Verwendung des konfigurierten [`default_timeout`](#zusätzliche-konfiguration) oder eines bereitgestellten `timeout`. Diese Methode stellt sicher, dass der Client vollständig initialisiert ist, bevor weitere Operationen durchgeführt werden.
```rust theme={null}
use std::time::Duration;
// Initializes the client using the configured default timeout
client.initialize().await?;
// Initializes the client with a custom timeout of 5 seconds
client.initialize_with_timeout(Duration::from_secs(5)).await?;
```
##### Argumente
| Name | Typ | Beschreibung |
| ---------------------- | ---------- | ------------------------------------------- |
| `timeout` (*optional*) | `Duration` | Maximale Wartezeit für die Initialisierung. |
##### Rückgabewert
| Typ | Beschreibung |
| ---------------------------- | ------------------------------------------------------------------------------------------------ |
| `Result<(), KameleoonError>` | Gibt an, ob die Initialisierung erfolgreich abgeschlossen wurde oder ein Fehler aufgetreten ist. |
##### Fehler
| Typ | Beschreibung |
| --------------------------- | --------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
#### is\_ready()
Überprüft, ob der Client initialisiert wurde.
```rust theme={null}
if client.is_ready() {
// The client is ready
}
```
##### Rückgabewert
| Typ | Beschreibung |
| ------ | --------------------------------------------------------------- |
| `bool` | `true`, wenn der Client einsatzbereit ist; andernfalls `false`. |
#### forget()
Entfernt den zwischengespeicherten SDK-Client, der mit dem angegebenen `site_code` verknüpft ist.
```rust theme={null}
use kameleoon_client::factory::KameleoonClientFactory;
// Removes the cached client for the given site code
KameleoonClientFactory::forget("a8st4f59bj")?;
// Removes the cached client for the given site code and environment
KameleoonClientFactory::forget_with_environment("a8st4f59bj", "production")?;
```
##### Argumente
| Name | Typ | Beschreibung |
| ---------------------------- | ------ | --------------------------------------------------------------------------- |
| `site_code` (*erforderlich*) | `&str` | Eindeutige Kennung des Kameleoon-Projekts. |
| `environment` (*optional*) | `&str` | Umgebungsschlüssel, der mit dem zwischengespeicherten Client verknüpft ist. |
##### Rückgabewert
| Typ | Beschreibung |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| `Result<(), KameleoonError>` | Gibt an, ob der zwischengespeicherte Client erfolgreich entfernt wurde oder ein Fehler aufgetreten ist. |
### Feature Flags und Variationen
#### is\_feature\_active()
* 📨 *Sendet Tracking-Daten an Kameleoon (abhängig von der Option `track`)*
Bestimmt, ob ein Feature Flag für einen bestimmten Benutzer aktiv ist.
Wenn der Besucher noch nicht für diesen Feature Flag ausgewertet wurde, wertet das SDK die Targeting-Regeln aus und gibt das Ergebnis zurück. Wenn der Besucher bereits eine gespeicherte Auswertung für das Feature hat, verwendet das SDK das vorhandene Ergebnis wieder, um die Konsistenz zu gewährleisten.
Kameleoon verwendet Tracking, um Sitzungen und Besucher zu zählen, wenn Sie bestimmte Methoden aufrufen, wie z. B. `is_feature_active()`, `get_variation()` oder `get_variations()`.
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 `get_variations()` 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 standardmäßig jede Sekunde Tracking-Daten. Sie können dieses Intervall über die Konfigurationsoption für das Tracking-Intervall auf bis zu fünf Sekunden konfigurieren. Kameleoon gruppiert Tracking-Events zu einer einzigen Sitzung, solange das Intervall zwischen den Events weniger als 30 Minuten beträgt. Wenn zwischen den Tracking-Events mehr als 30 Minuten vergehen, zählt Kameleoon die Events als separate Sitzungen. Ein Besuch erscheint in Ihren Berichten 30 Minuten nach dem letzten aufgezeichneten Event in der Sitzung.
Die Methode `is_feature_active()` wertet die ausgelieferte Variante aus, nicht den Master-Flag-Status. Wenn Sie Regeln ausschließen, verwendet die Methode den Standardstatus **Then, for everyone else serve**. Wenn Sie für diesen Standardstatus **Off** auswählen, gibt die Methode immer `false` zurück, auch wenn der Master-Feature-Flag auf **On** steht.
```rust theme={null}
use kameleoon_client::client::IsFeatureActiveOpts;
let feature_key = "new_checkout";
// Evaluates the feature flag and sends tracking data (default behavior)
let active = client.is_feature_active(visitor_code, feature_key)?;
// Evaluates the feature flag without sending tracking data
let active_without_tracking = client.is_feature_active_with_opts(
visitor_code,
feature_key,
IsFeatureActiveOpts::new().track(false),
)?;
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------- | ------ | --------------------------------------------------------------------- | -------- |
| `visitor_code` (*erforderlich*) | `&str` | Eindeutige Kennung des Benutzers. | |
| `feature_key` (*erforderlich*) | `&str` | Schlüssel des Features, das für den Benutzer ausgewertet werden soll. | |
| `track` (*optional*) | `bool` | Aktiviert oder deaktiviert das Tracking der Feature-Auswertung. | `true` |
##### Rückgabewert
| Typ | Beschreibung |
| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `Result` | Gibt an, ob der Feature Flag für den angegebenen `visitor_code` aktiv ist, oder gibt einen Fehler zurück. |
##### Fehler
| Typ | Beschreibung |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `ErrorCode::FeatureNotFound` | Ausnahme, die angibt, dass der angeforderte Feature-Schlüssel in der internen Konfiguration des SDK nicht gefunden wurde. Dies bedeutet in der Regel, dass der Feature Flag in der Kameleoon-App nicht aktiviert ist (aber der Code, der das Feature implementiert, bereits in der Anwendung bereitgestellt ist). |
| `ErrorCode::VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
#### get\_variation()
* 📨 *Sendet Tracking-Daten an Kameleoon (abhängig vom Parameter `track`)*
Ruft die einem bestimmten Besucher für einen bestimmten Feature Flag zugewiesene [`Variation`](#variation) ab.
Diese Methode nimmt `visitor_code` und `feature_key` als obligatorische Argumente entgegen. Das Argument `track` ist optional und standardmäßig `true`.
Sie gibt die dem Besucher zugewiesene `Variation` zurück. Wenn der Besucher mit keinen Feature-Flag-Regeln verknüpft ist, gibt die Methode die Standard-`Variation` für den angegebenen 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 keiner vordefinierten Delivery-Regel für einen Feature Flag entspricht. Mit anderen Worten, es ist die Fallback-Variation, die auf alle Benutzer angewendet wird, die nicht durch spezifische Regeln angesprochen werden. Sie wird als Variation im Abschnitt „Then, for everyone else..." in einer Management-Oberfläche dargestellt.
```rust theme={null}
use kameleoon_client::client::GetVariationOpts;
let feature_key = "new_checkout";
// Retrieves the variation assigned to the visitor (with tracking enabled by default)
let variation = client.get_variation(visitor_code, feature_key)?;
// Retrieves the variation without sending tracking data
let variation_without_tracking = client.get_variation_with_opts(
visitor_code,
feature_key,
GetVariationOpts::new().track(false),
)?;
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------ | ------ | ----------------------------------------------------------------------------------------------- | -------- |
| visitor\_code (*erforderlich*) | `&str` | Eindeutige Kennung des Besuchers. | |
| feature\_key (*erforderlich*) | `&str` | Schlüssel des Features, das Sie einem Besucher zugänglich machen möchten. | |
| track (*optional*) | `bool` | Ein optionaler Parameter zum Aktivieren oder Deaktivieren des Trackings der Feature-Auswertung. | `true` |
##### Rückgabewert
| Typ | Beschreibung |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `Result` | Eine einem bestimmten Besucher für einen bestimmten Feature Flag zugewiesene [`Variation`](#variation) bei Erfolg, andernfalls ein Fehler. |
##### Fehler
| Typ | Beschreibung |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `ErrorCode::VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
| `ErrorCode::FeatureNotFound` | Ausnahme, die angibt, dass der angeforderte Feature-Schlüssel in der internen Konfiguration des SDK nicht gefunden wurde. Dies bedeutet in der Regel, dass der Feature Flag in der Kameleoon-App nicht aktiviert ist (aber der Code, der das Feature implementiert, bereits in der Anwendung bereitgestellt ist). |
| `ErrorCode::FeatureEnvironmentDisabled` | Ausnahme, die angibt, dass der Feature Flag für die aktuelle Umgebung des Besuchers (z. B. production, staging oder development) deaktiviert ist. |
| `ErrorCode::FeatureEvaluationBlocked` | Ausnahme, die angibt, dass die Feature-Auswertung blockiert ist. Der Grund wird in der Fehlermeldung beschrieben. Dies tritt normalerweise aufgrund von DSGVO-Beschränkungen auf, wenn der Besucher keine rechtliche Einwilligung erteilt hat. |
#### get\_variations()
* 📨 *Sendet Tracking-Daten an Kameleoon (abhängig vom Parameter `track`)*
Ruft eine Map von [`Variation`](#variation)-Objekten ab, die einem bestimmten Besucher für alle Feature Flags zugewiesen sind.
Diese Methode iteriert über alle verfügbaren Feature Flags und gibt die zugewiesene `Variation` für jeden mit dem angegebenen Besucher verknüpften Flag zurück. Sie nimmt `visitor_code` als obligatorisches Argument entgegen, während `only_active` und `track` optional sind.
* Wenn `only_active` auf `true` gesetzt ist, gibt die Methode `get_variations()` Feature-Flag-Variationen zurück, sofern der Benutzer nicht mit der `off`-Variation gebucketet 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üssel und ihren entsprechenden `Variation`s als Werten. Wenn für einen Feature Flag keine Variation zugewiesen ist, gibt die Methode die Standard-`Variation` für diesen Flag zurück.
Es sollte eine ordnungsgemäße Fehlerbehandlung implementiert werden, um potenzielle Ausnahmen zu verwalten.
Die Standardvariation bezieht sich auf die Variation, die einem Besucher zugewiesen wird, wenn er keiner vordefinierten Delivery-Regel für einen Feature Flag entspricht. Mit anderen Worten, es ist die Fallback-Variation, die auf alle Benutzer angewendet wird, die nicht durch spezifische Regeln angesprochen werden. Sie wird als Variation im Abschnitt „Then, for everyone else..." in einer Management-Oberfläche dargestellt.
```rust theme={null}
use kameleoon_client::client::GetVariationsOpts;
// Retrieves all variations assigned to the visitor (with default options)
let variations = client.get_variations(visitor_code)?;
// Retrieves only active variations for the visitor
let only_active_variations = client.get_variations_with_opts(
visitor_code,
GetVariationsOpts::new().only_active(true),
)?;
// Retrieves variations without sending tracking data
let variations_without_tracking = client.get_variations_with_opts(
visitor_code,
GetVariationsOpts::new().track(false),
)?;
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| visitor\_code (*erforderlich*) | `&str` | Eindeutige Kennung des Besuchers. | |
| only\_active (*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
| Typ | Beschreibung |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Result, KameleoonError>` | Map, die die zugewiesenen [`Variation`](#variation)-Objekte der Feature Flags unter Verwendung der Schlüssel der entsprechenden Features enthält, bei Erfolg, andernfalls ein Fehler. |
##### Fehler
| Typ | Beschreibung |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `ErrorCode::VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
#### set\_forced\_variation()
Die Methode ermöglicht es Ihnen, einem Benutzer programmgesteuert eine bestimmte [`Variation`](#variation) zuzuweisen und den Standardauswertungsprozess zu 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 Segmentierungs- und Targeting-Bedingungen während eines Experiments beizubehalten, setzen Sie stattdessen `force_targeting=false`.
**Simulierte** Variationen haben in der Ausführungsreihenfolge immer Vorrang. Wenn eine **simulierte** Variationsberechnung ausgelöst wird, wird sie zuerst vollständig verarbeitet und abgeschlossen.
Eine erzwungene Variation wird genauso behandelt wie eine ausgewertete Variation. Sie wird in der Analytik verfolgt und im Benutzerkontext wie jede ausgewertete Standardvariation gespeichert, um die Konsistenz im Reporting zu gewährleisten.
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.
Es ist wichtig, **erzwungene** Variationen von **[simulierten](#get_visitor_code)** Variationen zu unterscheiden:
* **Erzwungene Variationen**: Sind spezifisch für ein einzelnes Experiment.
* **Simulierte Variationen**: Beeinflussen das Gesamtergebnis des **Feature Flags**.
```rust theme={null}
use kameleoon_client::client::SetForcedVariationOpts;
let experiment_id = 202387;
// Forces the visitor into "variation_2" for the given experiment
client.set_forced_variation(visitor_code, experiment_id, Some("variation_2"))?;
// Removes any previously forced variation for the visitor in this experiment
client.set_forced_variation(visitor_code, experiment_id, None)?;
// Forces the visitor into "variation_2" with custom options
// In this case, targeting rules are respected (force_targeting = false)
client.set_forced_variation_with_opts(
visitor_code,
experiment_id,
Some("variation_2"),
SetForcedVariationOpts::new().force_targeting(false),
)?;
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| visitor\_code (*erforderlich*) | `&str` | Eindeutige Kennung des Besuchers. | |
| experiment\_id (*erforderlich*) | `u32` | **Experiment-ID**, die während des Auswertungsprozesses angesprochen und ausgewählt wird. | |
| variation\_key (*erforderlich*) | `Option<&str>` | **Variationsschlüssel**, der einer `Variation` entspricht, die als zurückgegebener Wert für das Experiment erzwungen werden soll. Wenn der Wert `None` ist, wird die erzwungene Variation zurückgesetzt. | |
| force\_targeting (*optional*) | `bool` | Gibt an, ob das Targeting für das Experiment erzwungen und übersprungen werden soll (`true`) oder wie im Standardauswertungsprozess angewendet werden soll (`false`). | `true` |
##### Rückgabewert
| Typ | Beschreibung |
| ---------------------------- | -------------------------------------------------------------------------------------------------- |
| `Result<(), KameleoonError>` | Gibt an, ob die erzwungene Variation erfolgreich festgelegt wurde oder ein Fehler aufgetreten ist. |
##### Fehler
| Typ | Beschreibung |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `ErrorCode::VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
| `ErrorCode::FeatureExperimentNotFound` | Ausnahme, die angibt, 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 Seite von Kameleoon noch nicht aktiviert wurde. |
| `ErrorCode::FeatureVariationNotFound` | Ausnahme, die angibt, 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 Seite von Kameleoon noch nicht aktiviert wurde. |
#### evaluate\_audiences()
* 📨 *Sendet Tracking-Daten an Kameleoon*
Diese Methode wertet Besucher anhand aller verfügbaren Audiences-Explorer-Segmente aus und verfolgt diejenigen, die übereinstimmen.
`evaluate_audiences()` sollte **nach dem Festlegen oder Aktualisieren aller relevanten Besucherdaten** und **kurz vor** dem Abrufen einer Feature-Variation oder dem Überprüfen eines Feature Flags aufgerufen werden. Dieser Ansatz stellt sicher, dass der Besucher anhand der aktuellsten verfügbaren Daten ausgewertet wird, was eine genaue Audience-Zuweisung basierend auf allen Kriterien ermöglicht.
Nach dem Aufruf dieser Methode können Sie eine detaillierte Analyse der Segmentleistung in Audiences Explorer durchführen.
```rust theme={null}
client.evaluate_audiences(visitor_code)?;
```
##### Argumente
| Name | Typ | Beschreibung |
| ------------------------------ | ------ | --------------------------------- |
| visitor\_code (*erforderlich*) | `&str` | Eindeutige Kennung des Besuchers. |
##### Rückgabewert
| Typ | Beschreibung |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| `Result<(), KameleoonError>` | Gibt an, ob die Audience-Auswertung erfolgreich war oder ein Fehler aufgetreten ist. |
##### Fehler
| Typ | Beschreibung |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
#### get\_datafile()
Um alle Feature Flags auszuwerten, verwenden Sie [`get_variations()`](#get_variations). Diese Methode ist effizienter als das Aufrufen von `DataFile` und das Iterieren durch Flags mit [`get_variation()`](#get_variation).
Gibt die aktuelle SDK-Konfiguration als [`DataFile`](#datafile)-Objekt zurück.
```rust theme={null}
let datafile = client.get_datafile()?;
```
##### Rückgabewert
| Typ | Beschreibung |
| --------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `Result, KameleoonError>` | Das [`DataFile`](#datafile), das die SDK-Konfiguration enthält, bei Erfolg, andernfalls ein Fehler. |
##### Fehler
| Typ | Beschreibung |
| --------------------------- | --------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
### Besucherdaten
#### get\_visitor\_code()
Verwenden Sie `get_visitor_code()`, um den aktuellen Kameleoon-`visitor_code` des Besuchers zu erhalten. Die Methode funktioniert mit jedem Cookie-Speicher, der das `CookieAccessor`-Trait implementiert.
Die Implementierungslogik ist wie folgt:
1. Das SDK prüft, ob über den bereitgestellten Accessor bereits ein `kameleoonVisitorCode`-Cookie verfügbar ist.
2. Wenn das Cookie nicht vorhanden ist, verwendet das SDK `default_visitor_code`, wenn Sie einen bereitstellen.
3. Andernfalls generiert das SDK einen neuen Besuchercode und speichert ihn über den Accessor.
Weitere Informationen finden Sie unter [Hybrid-Experimentierung](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/).
Wenn Sie Ihren eigenen `visitor_code` bereitstellen, muss dessen Eindeutigkeit von Ihrer Seite garantiert werden. Beachten Sie auch, dass die Länge des `visitor_code` auf `255` Zeichen begrenzt ist.
Mit der Methode `get_visitor_code()` können Sie **simulierte** Variationen für einen Besucher festlegen. Wenn Cookies (aus einer **Anfrage** oder einem **Dokument**) den Schlüssel `kameleoonSimulationFFData` enthalten, wird der Standardauswertungsprozess umgangen. Stattdessen gibt die Methode direkt eine [`Variation`](#variation) basierend auf den bereitgestellten Daten zurück.
Sie können Simulationen auf zwei Arten anwenden:
* **Automatisch (empfohlen):** Bei Verwendung von Kameleoon Web Experimentation oder dem SDK im [Hybridmodus](/developer-docs/feature-experimentation/get-started/hybrid-experimentation#linking-feature-experiments-with-front-end-tracking-code) wird das Cookie automatisch erstellt, wenn die Anzeige einer Variante mithilfe des [Simulationspanels](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode) simuliert wird.
* **Manuell:** Setzen Sie das Cookie `kameleoonSimulationFFData` manuell.
Es ist wichtig, **simulierte** Variationen von **[erzwungenen](#set_forced_variation)** Variationen zu unterscheiden:
* **Simulierte Variationen**: Beeinflussen das Gesamtergebnis des **Feature Flags**.
* **Erzwungene Variationen**: Sind spezifisch für ein einzelnes Experiment.
⚙️ **Manuelle Einrichtung**
Bitte stellen Sie sicher, dass das Cookie `kameleoonSimulationFFData` diesem Format folgt:
* `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}`: Simuliert die Variation mit `varId` des Experiments `expId` für den angegebenen `featureKey`.
* `kameleoonSimulationFFData={"featureKey":{"expId":0}}`: Simuliert die Standardvariation (definiert im Abschnitt **Then, for everyone else in Production, serve**) für den angegebenen `featureKey`.
⚠️ Um eine ordnungsgemäße Funktionalität zu gewährleisten, muss der Cookie-Wert mit einer Methode wie [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) als URI-Komponente codiert werden.
```rust theme={null}
use std::collections::HashMap;
use kameleoon_client::cookies::CookieAccessor;
// A simple in-memory cookie store, useful for testing or non-HTTP environments
struct MemoryCookies {
values: HashMap,
}
impl CookieAccessor for MemoryCookies {
// Store the cookie value by key (max_age and top_level_domain are unused here)
fn set<'a>(&mut self, key: &str, value: &str, _max_age: u32, _top_level_domain: Option<&'a str>) {
self.values.insert(key.to_owned(), value.to_owned());
}
// Retrieve a cookie value by key
fn get(&self, key: &str) -> Option<&str> {
self.values.get(key).map(String::as_str)
}
}
// Generate or retrieve a visitor code using auto-generated value
let visitor_code = client.get_visitor_code(&mut cookies, None)?;
// Generate or retrieve a visitor code using a predefined user ID
let visitor_code = client.get_visitor_code(&mut cookies, Some("user_id"))?;
```
```rust theme={null}
use axum::{ extract::State, http::StatusCode, response::{IntoResponse, Response} };
use axum_extra::extract::cookie::{Cookie, CookieJar};
use kameleoon_client::client::KameleoonClient;
use kameleoon_client::cookies::CookieAccessor;
use time::Duration;
// Wrapper around Axum's CookieJar to implement the CookieAccessor trait
struct AxumCookies(CookieJar);
impl CookieAccessor for AxumCookies {
// Build and add a cookie with path, max_age, and optional domain, then insert into the jar
fn set<'a>(&mut self, key: &str, value: &str, max_age: u32, top_level_domain: Option<&'a str>) {
let mut builder =
Cookie::build((key.to_owned(), value.to_owned())).path("/").max_age(Duration::seconds(i64::from(max_age)));
if let Some(domain) = top_level_domain {
builder = builder.domain(domain.to_owned());
}
self.0 = std::mem::take(&mut self.0).add(builder.build());
}
// Retrieve a cookie value by key from the jar
fn get(&self, key: &str) -> Option<&str> {
self.0.get(key).map(|cookie| cookie.value())
}
}
async fn get_visitor_code(
State(client): State,
jar: CookieJar,
) -> Result<(StatusCode, CookieJar, String), Response> {
let mut cookies = AxumCookies(jar);
// Retrieve or generate a visitor code; map any SDK error to a 500 response
let visitor_code = client
.get_visitor_code(&mut cookies, None)
.map_err(|error| (StatusCode::INTERNAL_SERVER_ERROR, error.to_string()).into_response())?;
// Return the status, updated cookie jar, and visitor code in the response
Ok((StatusCode::OK, cookies.0, visitor_code))
}
```
```rust theme={null}
use actix_web::{ HttpRequest, HttpResponse, cookie::Cookie, http::{StatusCode, header}, web};
use kameleoon_client::client::KameleoonClient;
use kameleoon_client::cookies::CookieAccessor;
use kameleoon_client::error::KameleoonError;
use time::Duration;
// Holds both request cookies (read-only) and response cookies (to be set on the client)
struct ActixCookies<'a> {
request: Ref<'a, Vec>>,
response: Vec>,
}
impl CookieAccessor for ActixCookies<'_> {
// Build a cookie with path, max_age, and optional domain;
// update it if it already exists in the response, otherwise append it
fn set<'a>(&mut self, key: &str, value: &str, max_age: u32, top_level_domain: Option<&'a str>) {
let mut builder =
Cookie::build(key.to_owned(), value.to_owned()).path("/").max_age(Duration::seconds(i64::from(max_age)));
if let Some(domain) = top_level_domain {
builder = builder.domain(domain.to_owned());
}
let next_cookie = builder.finish();
match self.response.iter_mut().find(|cookie| cookie.name() == key) {
Some(cookie) => *cookie = next_cookie,
None => self.response.push(next_cookie),
}
}
// Check response cookies first, then fall back to request cookies
fn get(&self, key: &str) -> Option<&str> {
self.response
.iter()
.find(|cookie| cookie.name() == key)
.map(|cookie| cookie.value())
.or_else(|| self.request.iter().find(|cookie| cookie.name() == key).map(|cookie| cookie.value()))
}
}
fn get_visitor_code(client: web::Data, request: HttpRequest) -> Result {
// Parse cookies from the incoming request
let request_cookies = request.cookies().map_err(|error| error.to_string())?;
let mut cookies = ActixCookies {
request: request_cookies,
response: Vec::new(),
};
// Retrieve or generate a visitor code using the SDK
let visitor_code = client.get_visitor_code(&mut cookies, None)?;
// Attach any new/updated cookies to the response headers
let mut response = HttpResponse::build(StatusCode::OK);
for cookie in cookies.response {
response.append_header((header::SET_COOKIE, cookie.encoded().to_string()));
}
Ok(response.body(visitor_code))
}
```
##### Argumente
| Name | Typ | Beschreibung |
| ----------------------------------- | -------------------------- | --------------------------------------------------------------------------- |
| `cookies` (*erforderlich*) | `&mut impl CookieAccessor` | Veränderbarer Cookie-Accessor zum Lesen und Speichern des Besucher-Cookies. |
| `default_visitor_code` (*optional*) | `Option<&str>` | Zu verwendender Besuchercode, wenn kein Cookie vorhanden ist. |
##### Rückgabewert
| Typ | Beschreibung |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `Result` | Zeichenkette, die einen im SDK verwendeten eindeutigen Besuchercode darstellt, bei Erfolg, andernfalls ein Fehler. |
#### add\_data()
Die Methode `add_data()` fügt dem Speicher [Targeting-Daten](#datentypen) hinzu, damit andere Methoden die Daten verwenden können, um zu entscheiden, ob der aktuelle Besucher angesprochen werden soll oder nicht.
Die Methode `add_data()` gibt keinen Wert zurück und interagiert nicht selbstständig 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 Serveraufrufe, da die Daten in der Regel zu einem einzigen Serveraufruf zusammengefasst werden, der durch `flush()` ausgelöst wird.
Die Methode [`track_conversion()`](#track_conversion) sendet ebenfalls alle zuvor verknüpften Daten, genau wie `flush()`. Dasselbe gilt für die Methoden [`get_variation()`](#get_variation) und [`get_variations()`](#get_variations), wenn eine Experimentierungsregel ausgelöst wird.
Jeder Besucher kann für die meisten Datentypen nur eine Instanz zugehöriger Daten haben. [`CustomData`](#customdata) ist jedoch eine Ausnahme. Besucher können eine Instanz von zugehörigem `CustomData` pro Index haben.
```rust theme={null}
use kameleoon_client::data::{Browser, BrowserKind, PageView, UserAgent};
client.add_data(visitor_code, [Browser::new(BrowserKind::Chrome, Some(123.0))])?;
client.add_data(
visitor_code,
[
PageView::new("https://example.com/pricing".to_owned(), Some("Pricing".to_owned()), vec![3]).into(),
UserAgent::new("Mozilla/5.0".to_owned()).into(),
],
)?;
client.add_data_with_track(
visitor_code,
vec![PageView::new("https://example.com/checkout".to_owned(), Some("Checkout".to_owned()), vec![])],
false,
)?;
```
##### Argumente
| Name | Typ | Beschreibung | Standardwert |
| ------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| visitor\_code (*erforderlich*) | `&str` | Eindeutige Kennung des Besuchers. | |
| data (*erforderlich*) | `impl IntoIterator- >` | Sammlung von Kameleoon-Datentypen. | |
| 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` |
##### Rückgabewert
| Typ | Beschreibung |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| `Result<(), KameleoonError>` | Gibt an, ob die Daten erfolgreich hinzugefügt wurden oder ein Fehler aufgetreten ist. |
##### Fehler
| Typ | Beschreibung |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `ErrorCode::VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
#### flush()
* *📨 Sendet Tracking-Daten an Kameleoon*
Die Methode `flush()` aggregiert alle einem Besucher zugeordneten Kameleoon-Daten und sendet eine Tracking-Anfrage an den Server. Diese Anfrage umfasst alle zuvor über die Methode [`add_data`](#add_data) hinzugefügten Daten, die noch nicht über andere Tracking-Mechanismen übertragen wurden (siehe die referenzierten Methoden für Details). Die `flush()`-Operation ist nicht blockierend, da der Serveraufruf asynchron erfolgt.
Diese Methode bietet Kontrolle darüber, wann die mit einem bestimmten `visitor_code` verknüpften Daten übertragen werden. Wenn `add_data()` beispielsweise mehrmals aufgerufen wird, wäre das Senden einer Anfrage nach jedem Aufruf ineffizient. Stattdessen können Sie diese Aktualisierungen bündeln und `flush()` einmal aufrufen, um alle gesammelten Daten in einer einzigen Anfrage zu senden.
Die Methode `flush()` verwendet den bereitgestellten `visitor_code` als eindeutige Besucherkennung.
* `flush()` — Stellt eine Flush-Operation gemäß dem konfigurierten Tracking-Intervall in die Warteschlange.
* `flush_instant()` — Sendet Tracking-Daten sofort, ohne auf das Intervall zu warten.
```rust theme={null}
// Queues a flush operation for the given visitor_code.
// Data will be sent according to the configured tracking interval (non-blocking).
client.flush(visitor_code)?;
// Immediately sends all pending tracking data for the given visitor_code.
// This is an async operation and must be awaited.
client.flush_instant(visitor_code).await?;
```
##### Argumente
| Name | Typ | Beschreibung |
| ------------------------------- | ------ | --------------------------------- |
| `visitor_code` (*erforderlich*) | `&str` | Eindeutige Kennung des Besuchers. |
##### Rückgabewert
| Typ | Beschreibung |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| `Result<(), KameleoonError>` | Gibt an, ob die Operation erfolgreich geplant oder ausgeführt wurde oder ob ein Fehler aufgetreten ist. |
##### Fehler
| Typ | Beschreibung |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `ErrorCode::VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
#### get\_remote\_data()
Mit der Methode `get_remote_data()` können Sie Remote-Daten abrufen, die auf Kameleoon-Servern für den angegebenen `key` gespeichert sind. In den meisten Setups werden diese Daten über die Kameleoon Data API geschrieben und können später von Ihrem Rust-Dienst abgerufen werden, wann immer Sie zusätzlichen Anwendungskontext benötigen.
Diese Methode ist nützlich, wenn Sie strukturierte Informationen auf der Remote-Infrastruktur von Kameleoon aufbewahren und von Ihrem Backend aus wiederverwenden möchten, ohne einen separaten Abrufmechanismus zu pflegen.
```rust theme={null}
let data = client.get_remote_data("test-key").await?;
```
##### Argumente
| Name | Typ | Beschreibung |
| ---------------------- | ------ | ------------------------------------------------------------------------ |
| `key` (*erforderlich*) | `&str` | Schlüssel, der den Remote-Daten zugeordnet ist, die Sie abrufen möchten. |
##### Rückgabewert
| Typ | Beschreibung |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Result` | Nutzlast, die dem angegebenen `key` zugeordnet ist, bei Erfolg, andernfalls ein Fehler. In den meisten Fällen ist die Nutzlast als Zeichenkette serialisiertes JSON. |
##### Fehler
| Typ | Beschreibung |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `ErrorCode::Network` | Wird zurückgegeben, wenn die Remote-Daten-Anfrage fehlschlägt oder der Server mit einem nicht erfolgreichen Statuscode antwortet. |
#### get\_remote\_visitor\_data()
`get_remote_visitor_data()` ist eine asynchrone Methode zum Abrufen von Kameleoon-Besuchsdaten für den angegebenen `visitor_code`. Die Methode fügt die Daten dem lokalen Besucherspeicher hinzu, damit andere SDK-Methoden sie für Targeting-Entscheidungen verwenden können.
Mit dieser Methode erhaltene Daten sind besonders nützlich, wenn Sie:
* von anderen Geräten gesammelte Daten verwenden möchten.
* auf den Verlauf eines Besuchers zugreifen möchten, z. B. zuvor angesehene Seiten aus vergangenen Besuchen.
* Daten verwenden möchten, die nur auf der Clientseite verfügbar sind, wie z. B. Datalayer-Variablen und Frontend-Ziel-Conversions.
Lesen Sie [diesen Artikel](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation), um die möglichen Anwendungsfälle besser zu verstehen.
Standardmäßig ruft `get_remote_visitor_data()` automatisch die zuletzt gespeicherten Custom Data mit `scope=Visitor` ab und fügt sie dem Besucher hinzu, ohne dass [`add_data()`](#add_data) aufgerufen werden muss. Dies ist besonders nützlich für die [Synchronisierung von Custom Data über mehrere Geräte hinweg](/developer-docs/cross-device-experimentation/).
```rust theme={null}
use kameleoon_client::types::RemoteVisitorDataFilter;
// Fetch remote visitor data without any filter
// This will return all available data for the given visitor
client.get_remote_visitor_data(visitor_code, None).await?;
// Create a filter to limit the returned data
let filter = RemoteVisitorDataFilter {
// Include data from the last 5 visits
previous_visit_amount: 5,
// Include conversion events (e.g., goals, transactions)
conversions: true,
// Include page view history
page_views: true,
// Use default values for all other fields
..Default::default()
};
// Fetch remote visitor data using the specified filter
// This will return only the data matching the filter criteria
client.get_remote_visitor_data(visitor_code, Some(filter)).await?;
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------- | --------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------ |
| `visitor_code` (*erforderlich*) | `&str` | Besuchercode, dessen Daten abgerufen werden sollen. | |
| `filter` (*optional*) | `Option` | Filter, der beschreibt, welche Remote-Besucherdaten abgerufen werden sollen. | `RemoteVisitorDataFilter::default()` |
##### Rückgabewert
| Typ | Beschreibung |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| `Result<(), KameleoonError>` | Gibt bei Erfolg zurück, wenn die Daten abgerufen und lokal hinzugefügt werden, andernfalls ein Fehler. |
##### Fehler
| Typ | Beschreibung |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `ErrorCode::VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
| `ErrorCode::Network` | Wird zurückgegeben, wenn die Anfrage für Remote-Besucherdaten fehlschlägt, nicht analysiert werden kann oder der Server mit einem nicht erfolgreichen Statuscode antwortet. |
##### Verwendung von Parametern in get\_remote\_visitor\_data()
Mit der Methode `get_remote_visitor_data()` können Sie steuern, welche Daten für einen Besucher abgerufen werden. Derselbe Filteransatz funktioniert für Ziele, Experimente, Variationen und andere Besucherdaten.
Wenn Sie beispielsweise Benutzer ansprechen möchten, die bei ihren letzten fünf Besuchen für ein Ziel konvertiert haben, können Sie `previous_visit_amount` auf `5` und `conversions` auf `true` setzen.
Die in diesem Beispiel gezeigte Flexibilität ist nicht auf Zieldaten beschränkt. Sie können den Filter verwenden, um viele verschiedene Besucherverhalten abzurufen und sie der Targeting- und Reporting-Logik in Ihrer Rust-Anwendung zur Verfügung zu stellen.
##### `RemoteVisitorDataFilter`-Felder
| Name | Typ | Beschreibung | Standard |
| ----------------------- | ------ | ----------------------------------------------------------------------- | -------- |
| `previous_visit_amount` | `i32` | Anzahl der vorherigen Besuche, aus denen Daten abgerufen werden sollen. | `1` |
| `current_visit` | `bool` | Wenn `true`, werden die Daten des aktuellen Besuchs abgerufen. | `true` |
| `custom_data` | `bool` | Wenn `true`, werden Custom Data abgerufen. | `true` |
| `visitor_code` | `bool` | Wenn `true`, wird der zuletzt verwendete Besuchercode wiederverwendet. | `true` |
| `page_views` | `bool` | Wenn `true`, werden Seitenaufrufdaten abgerufen. | `false` |
| `geolocation` | `bool` | Wenn `true`, werden Geolokalisierungsdaten abgerufen. | `false` |
| `device` | `bool` | Wenn `true`, werden Gerätedaten abgerufen. | `false` |
| `browser` | `bool` | Wenn `true`, werden Browserdaten abgerufen. | `false` |
| `operating_system` | `bool` | Wenn `true`, werden Betriebssystemdaten abgerufen. | `false` |
| `conversions` | `bool` | Wenn `true`, werden Conversion-Daten abgerufen. | `false` |
| `experiments` | `bool` | Wenn `true`, werden Experiment-Daten abgerufen. | `false` |
| `kcs` | `bool` | Wenn `true`, werden Kameleoon Conversion Score-Daten abgerufen. | `false` |
| `personalizations` | `bool` | Wenn `true`, werden Personalisierungsdaten abgerufen. | `false` |
| `cbs` | `bool` | Wenn true, werden Contextual Bandit Score-Daten abgerufen. | `false` |
#### get\_visitor\_warehouse\_audience()
Diese Methode ruft Audience-Daten ab, die einem Besucher in Ihrer Warehouse-Integration zugeordnet sind, indem sie den angegebenen `visitor_code` und optional einen `warehouse_key` verwendet. Der `warehouse_key` ist normalerweise Ihre interne Benutzer-ID. Der Parameter `custom_data_index` entspricht den Kameleoon-Custom-Data, die Kameleoon verwendet, um Ihre Besucher anzusprechen.
Wenn der Aufruf erfolgreich ist, konvertiert das SDK die zurückgegebene Audience-Liste in [`CustomData`](#customdata), fügt sie dem Besucher lokal hinzu und macht sie für Targeting-Zwecke verfügbar. Weitere Hintergrundinformationen finden Sie in der [Warehouse-Targeting-Dokumentation](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting).
```rust theme={null}
// Fetch audience data for a visitor using only the visitor_code.
client.get_visitor_warehouse_audience(visitor_code, None, 98).await?;
// Fetch audience data for a visitor using both visitor_code and warehouse_key.
// Useful when your warehouse uses a different identifier than visitor_code.
client.get_visitor_warehouse_audience(visitor_code, Some("internal-user-id"), 98).await?;
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------------ | -------------- | ----------------------------------------------------------------------------------- | -------------- |
| `visitor_code` (*erforderlich*) | `&str` | Besucher, dessen Warehouse-Audiences abgerufen werden sollen. | |
| `warehouse_key` (*optional*) | `Option<&str>` | Externer Warehouse-Schlüssel, normalerweise Ihre interne Benutzer-ID. | `visitor_code` |
| `custom_data_index` (*erforderlich*) | `u32` | In Kameleoon konfigurierter Custom-Data-Index für das Warehouse-Audience-Targeting. | |
##### Rückgabewert
| Typ | Beschreibung |
| ---------------------------- | -------------------------------------------------------------------------------------------------- |
| `Result<(), KameleoonError>` | Erfolg, wenn die Warehouse-Audience-Daten abgerufen und lokal als `CustomData` gespeichert werden. |
##### Fehler
| Typ | Beschreibung |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `ErrorCode::VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
| `ErrorCode::Network` | Wird zurückgegeben, wenn die Warehouse-Audience-Anfrage fehlschlägt, nicht analysiert werden kann oder der Server mit einem nicht erfolgreichen Statuscode antwortet. |
#### set\_legal\_consent()
Sie müssen diese Methode verwenden, um anzugeben, ob der Besucher seine rechtliche Einwilligung zur Verwendung personenbezogener Daten gegeben hat. Das Setzen von `legal_consent` auf `false` schränkt die Datentypen ein, die in Tracking-Anfragen aufgenommen werden können. Dies hilft Ihnen, rechtliche und regulatorische Anforderungen einzuhalten und gleichzeitig Besucherdaten verantwortungsbewusst zu verwalten. Weitere Informationen finden Sie in der [Richtlinie zur Einwilligungsverwaltung](/user-manual/project-management/consent-management-policy).
Wenn Sie einen Cookie-Accessor bereitstellen, aktualisiert das SDK auch die Besucher-Cookies entsprechend dem Einwilligungsstatus.
```rust theme={null}
// Set consent and update cookies
client.set_legal_consent(visitor_code, true, Some(&mut cookies))?;
// Set consent without updating cookies
client.set_legal_consent(visitor_code, true, None)?;
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| -------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `visitor_code` (*erforderlich*) | `&str` | Die eindeutige Kennung des Benutzers. | |
| `legal_consent` (*erforderlich*) | `bool` | `true` gibt an, dass der Besucher seine rechtliche Einwilligung gegeben hat, `false` gibt an, dass der Besucher nie eine rechtliche Einwilligung erteilt oder diese zurückgezogen hat. | |
| `cookies` (*optional*) | `Option<&mut impl CookieAccessor>` | Optionaler Cookie-Accessor zur Aktualisierung von Cookies. | `None` |
##### Rückgabewert
| Typ | Beschreibung |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `Result<(), KameleoonError>` | Gibt an, ob der Einwilligungsstatus des Besuchers erfolgreich aktualisiert wurde, andernfalls ein Fehler. |
##### Fehler
| Typ | Beschreibung |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `ErrorCode::VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
##### Verhalten beim Widerruf der Einwilligung
Wenn Sie `set_legal_consent()` mit `legal_consent=false` aufrufen, löscht das SDK das `kameleoonVisitorCode`-Cookie nicht. Stattdessen verlängert es das Ablaufdatum des Cookies nicht mehr, sodass das Cookie bis zu seinem natürlichen Ablauf bestehen bleibt.
Wenn Ihre Compliance-Anforderungen die sofortige Entfernung der Cookie-Datei beim Opt-out vorschreiben, müssen Sie sie manuell mit den nativen Cookie-Verwaltungsmethoden Ihres Frameworks löschen. Das SDK entfernt die Datei nicht automatisch.
### Ziele und Drittanbieter-Analytik
#### track\_conversion()
* 📨 *Sendet Tracking-Daten an Kameleoon*
Verwenden Sie diese Methode, um eine Conversion für ein bestimmtes [Ziel](/user-manual//assets/goals/create-a-goal) und einen bestimmten Benutzer zu verfolgen. Diese Methode erfordert `visitor_code` und `goal_id`. Darüber hinaus akzeptiert diese Methode auch die optionalen Argumente `revenue`, `negative` und `metadata`. Der `visitor_code` ist in der Regel identisch mit dem, der beim Auslösen des Experiments verwendet wurde.
Diese Methode ist nicht blockierend, da der Serveraufruf asynchron erfolgt.
```rust theme={null}
use kameleoon_client::client::TrackConversionOpts;
use kameleoon_client::data::CustomData;
// Track a goal
client.track_conversion(visitor_code, goal_id)?;
// Track a goal with revenue
client.track_conversion_with_opts(visitor_code, goal_id, TrackConversionOpts::new().revenue(100.0))?;
// Track a goal with negative revenue
client.track_conversion_with_opts(
visitor_code,
goal_id,
TrackConversionOpts::new().revenue(100.0).negative(true)
)?;
// Track a goal with custom metadata
client.track_conversion_with_opts(
visitor_code,
goal_id,
TrackConversionOpts::new().metadata(vec![CustomData::new(4, vec!["true".to_owned()])]),
)?;
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| visitor\_code (*erforderlich*) | `&str` | Eindeutige Kennung des Besuchers. | |
| goal\_id (*erforderlich*) | `u32` | ID des Ziels. | |
| negative (*optional*) | `bool` | Definiert, ob der Umsatz positiv oder negativ ist. | `false` |
| revenue (*optional*) | `f32` | Umsatz der Conversion. | `0` |
| metadata (*optional*) | `Vec` | Metadaten der Conversion. [Müssen zuvor in der Kameleoon-App definiert werden](/de/user-manual/assets/goals/create-a-goal#metadaten). | `vec![]` |
Die Metadaten-Werte sind über [Rohdaten-Exporte](/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` angegeben wird, verwendet Kameleoon diese angegebenen Werte für die aktuelle Conversion anstelle dessen, was zuvor mit der Methode [`add_data()`](#add_data) gesammelt wurde. Wenn der Parameter weggelassen wird, verwendet Kameleoon die zuletzt verfolgten Werte für diese [`CustomData`](#customdata) vor der Conversion und innerhalb desselben Besuchs.
Kameleoon berücksichtigt nur die Metadaten-Werte, die explizit als Parameter an die Methode `track_conversion()` übergeben werden.
Im folgenden Beispiel verknüpft Kameleoon die Conversion nur mit dem Custom-Data-Wert, der explizit als Parameter angegeben wird (hier: Index 5 mit dem Wert 'Amex Credit Card').
```rust theme={null}
client.add_data(
visitor_code,
[
CustomData::new(5, vec!["Credit Card".to_owned()]),
CustomData::new(9, vec!["Express Delivery".to_owned()])
]
)?;
client.track_conversion_with_opts(
visitor_code,
goal_id,
TrackConversionOpts::new().metadata(vec![CustomData::new(5, vec!["Amex Credit Card".to_owned()])]),
)?
```
##### Rückgabewert
| Typ | Beschreibung |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `Result<(), KameleoonError>` | Gibt an, ob die Conversion erfolgreich für das asynchrone Tracking in die Warteschlange gestellt wurde, andernfalls ein Fehler. |
##### Fehler
| Typ | Beschreibung |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `ErrorCode::VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Besuchercode ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
#### get\_engine\_tracking\_code()
Kameleoon lässt sich in mehrere Analyselösungen integrieren, darunter Mixpanel, Google Analytics 4 und Segment. Um serverseitige Experimente korrekt zu verfolgen, rufen Sie die Methode `get_engine_tracking_code()` auf, nachdem der Besucher ein Experiment ausgelöst hat. Das SDK gibt JavaScript-Warteschlangenbefehle für die Experimente zurück, die der Besucher in den letzten fünf Sekunden ausgelöst hat. Wenn Sie diesen Code in die Seite einfügen, verarbeitet Engine.js die Befehle und sendet die Expositions-Events über die aktive Analyseintegration.
Weitere Informationen zur Implementierung dieser Methode finden Sie unter [Hybrid-Experimentierung](/developer-docs/feature-experimentation/get-started/hybrid-experimentation).
```rust theme={null}
let tracking_code = client.get_engine_tracking_code(visitor_code)?;
```
* Um diese Funktion zu nutzen, implementieren Sie sowohl das Rust SDK als auch [Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation) von Kameleoon. Da Engine.js in diesem Flow nur für das Tracking verwendet wird, können Sie das asynchrone Tag vor dem schließenden `
`-Tag installieren.
* Wenn Sie Experimente nur in Kameleoon verfolgen möchten und keine Expositions-Events an Drittanbieter-Analysetools senden müssen, verwenden Sie das [JavaScript / TypeScript SDK](/developer-docs/sdks/web-sdks/js-sdk). Diese Option eignet sich gut für [Serverless-Edge-Compute-Plattformen](/developer-docs/feature-experimentation/implementation-and-deployment/serverless-edge-compute-starter-kits). Das JavaScript / TypeScript SDK verfolgt Variationen automatisch, wenn Sie [`getVisitorCode`](/developer-docs/sdks/web-sdks/js-sdk#getvisitorcode) aufrufen, solange Sie die entsprechenden Experimentzuweisungen zu `window.kameleoonQueue` hinzufügen.
* Sie können den zurückgegebenen Tracking-Code direkt in ein HTML-`