> ## 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.
# Elixir SDK
> Integrieren Sie das Kameleoon Elixir SDK, um Experimente auszuführen und Feature Flags in Elixir-Diensten und Web-Backends zu aktivieren.
Mit dem Kameleoon Elixir SDK können Sie Experimente ausführen und Feature Flags in Ihren Elixir-Diensten und Web-Backends aktivieren.
**Erste Schritte**: Hilfe für den Einstieg finden Sie im [Entwicklerhandbuch](#entwicklerhandbuch).
**Version**: Aktuelle Version des Elixir SDK: 0.8.6 [Changelog](https://docs.kameleoon.com/developer-docs/sdks/web-sdks/elixir-sdk).
**SDK-Methoden**: Die vollständige Referenzdokumentation des Elixir SDK finden Sie im Abschnitt [Referenz](#referenz).
## Entwicklerhandbuch
Dieses Handbuch soll Ihnen helfen, das Elixir SDK schnell zu integrieren und mit der Auswertung von Feature Flags in Ihrer Elixir-Anwendung zu beginnen.
### Erste Schritte
#### Den Elixir-Client installieren
Fügen Sie das SDK als Abhängigkeit in Ihrer `mix.exs`-Datei hinzu:
```elixir title="mix.exs" theme={null}
def deps do
[
{:kameleoon_client, "~> 0.8.6"}
]
end
```
#### Zusätzliche Konfiguration
Erstellen Sie eine Konfigurationsdatei `client-elixir.conf`, um Anmeldedaten bereitzustellen und das Verhalten des SDK anzupassen.
Wir empfehlen, diese Datei im Standardpfad `/etc/kameleoon/client-elixir.conf` zu speichern. `Kameleoon.ClientFactory.create` verwendet diesen Pfad automatisch, wenn Sie keine Konfigurationsoptionen übergeben. Wenn Sie die Datei an einem anderen Ort ablegen, übergeben Sie den Pfad beim Erstellen des Clients über die Option `config_path:`.
Das Elixir SDK kann entweder über eine Konfigurationsdatei konfiguriert werden, die von `Kameleoon.ClientFactory.create` verwendet wird, oder durch Übergabe einer `%Kameleoon.ClientConfig\{\}`-Struktur über die Option `config:`.
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_minutes` / `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_minutes` / `refreshIntervalMinutes` (*optional*) | Intervall in Minuten, das verwendet wird, um die Konfiguration aktiver Experimente und Feature Flags zu aktualisieren. | `60` Minuten |
| `default_timeout_millis` / `defaultTimeoutMillis` (*optional*) | Standard-Timeout in Millisekunden für SDK-Netzwerkanfragen. | `10000` Millisekunden |
| `tracking_interval_millis` / `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. | `nil` |
| `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`. | `nil` |
| `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. | `nil` |
#### Den Kameleoon-Client initialisieren
Nachdem Sie das SDK installiert und Ihre Anmeldedaten konfiguriert haben, erstellen Sie einen `%Kameleoon.Client\{\}` mithilfe von `Kameleoon.ClientFactory`.
```elixir theme={null}
alias Kameleoon.Client
alias Kameleoon.ClientFactory
site_code = "a8st4f59bj"
{:ok, client} = ClientFactory.create(site_code, config_path: "/etc/kameleoon/client-elixir.conf")
:ok = Client.initialize(client)
```
```elixir theme={null}
alias Kameleoon.Client
alias Kameleoon.ClientConfig
alias Kameleoon.ClientFactory
site_code = "a8st4f59bj"
config = %ClientConfig{
client_id: "",
client_secret: "",
refresh_interval_minutes: 60,
session_duration_minutes: 30,
default_timeout_millis: 10_000,
tracking_interval_millis: 1_000,
environment: "development",
top_level_domain: ".example.com",
proxy_host: "http://192.168.0.25:8080",
network_domain: "example.com"
}
{:ok, client} = ClientFactory.create(site_code, config: config)
:ok = Client.initialize(client)
```
Ein `%Kameleoon.Client\{\}` ist das Hauptobjekt zur Auswertung von Feature Flags, zum Hinzufügen von Besucherdaten und zum Senden von Tracking-Anfragen.
* Es wird empfohlen, `%Kameleoon.Client\{\}` als Singleton-Objekt zu verwenden, da es die Brücke zwischen Ihrer Anwendung und der Kameleoon-Plattform bildet. Es stellt alle erforderlichen Methoden und Eigenschaften bereit, um Experimente effizient auszuführen.
* Das Elixir SDK initialisiert sich über den nativen Core. Sie sollten [`initialize()`](#initialize) aufrufen, bevor Sie sich im Produktivcode auf die Feature-Auswertung verlassen.
#### Aktivieren eines Feature Flags
##### Einem Benutzer eine eindeutige ID zuweisen
Um einem Benutzer eine eindeutige ID zuzuweisen, können Sie die Methode [`Client.get_visitor_code`](#get_visitor_code) verwenden. Wenn kein **Visitor Code** (aus dem Cookie der Request-Header) vorhanden ist, generiert die Methode eine zufällige eindeutige ID oder verwendet einen von Ihnen erzeugten `default_visitor_code`. Die ID wird anschließend in einem Cookie in den Response-Headern gesetzt.
Wenn Sie Kameleoon im [Hybridmodus](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) verwenden, stellt der Aufruf der Methode `Client.get_visitor_code` sicher, dass die eindeutige ID (**Visitor Code**) zwischen der Anwendungsdatei `engine.js` (zuvor `kameleoon.js` genannt) und dem SDK geteilt wird.
##### Eine Flag-Konfiguration abrufen
Um ein Feature Flag in Ihrem Code zu implementieren, müssen Sie das 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 [`Client.get_variation`](#get_variation) oder [`Client.is_feature_active?`](#is_feature_active) verwenden, um die Konfiguration anhand des `feature_key` abzurufen.
Die Methode `Client.get_variation` verarbeitet sowohl einfache Feature Flags mit ON/OFF-Zuständen als auch komplexere Flags mit mehreren Variationen. Die Methode ruft die passende Variation für den Benutzer ab, indem sie die Feature-Regeln prüft, die Variation zuweist und sie anhand des `feature_key` und `visitor_code` zurückgibt.
Die Methode `Client.is_feature_active?` kann verwendet werden, wenn Sie die Konfiguration eines einfachen Feature Flags abrufen möchten, das nur einen ON- oder OFF-Zustand hat – im Gegensatz zu komplexeren Feature Flags mit mehreren Variationen oder Targeting-Optionen.
Wenn Ihrem Feature Flag Variablen zugeordnet sind (z. B. spezifische Verhaltensweisen, die mit den einzelnen Variationen verbunden sind), ermöglicht `Client.get_variation` auch den Zugriff auf das [`Variation`](#variation)-Objekt, das Details zur zugewiesenen Variation und zum zugehörigen Experiment bereitstellt. Diese Methode prüft, ob der Benutzer als Zielgruppe definiert ist, ermittelt die dem Besucher zugewiesene Variation und speichert sie. Wenn `track=true`, sendet das SDK das Expositionsereignis bei der nächsten Tracking-Anfrage an das angegebene Experiment. Diese wird automatisch basierend auf dem [`tracking_interval_millis`](#zusätzliche-konfiguration) des SDK ausgelöst. Standardmäßig ist dieses Intervall auf 1000 Millisekunden (1 Sekunde) eingestellt.
Mit der Methode `Client.get_variation` können Sie steuern, ob Tracking erfolgen soll. Bei `track=false` werden vom SDK keine Expositionsereignisse gesendet. Das ist nützlich, wenn Sie Daten nicht über das SDK tracken möchten und stattdessen z. B. clientseitiges Tracking durch die Kameleoon Engine verwenden. Außerdem ist `track=false` hilfreich bei der Verwendung der Methode `Client.get_variations`, wenn Sie nur die Variationen für alle Flags benötigen, ohne Tracking-Ereignisse 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 Benutzer anzusprechen oder Besuche in Berichten zu filtern/aufzuschlüsseln
Um einen Benutzer anzusprechen, stellen Sie sicher, dass Sie seinem Profil relevante Datenpunkte hinzugefügt haben, bevor Sie die Feature-Variation abrufen oder prüfen, ob das Flag aktiv ist. Verwenden Sie die Methode [`Client.add_data`](#add_data), um diese Datenpunkte zum Profil des Benutzers hinzuzufügen.
Um Datenpunkte abzurufen, die auf anderen Geräten erfasst wurden, oder auf vergangene Benutzerdaten zuzugreifen (clientseitig erfasst bei Verwendung von Kameleoon im Hybridmodus), verwenden Sie die Methode [`Client.get_remote_visitor_data`](#get_remote_visitor_data). Diese Methode ruft Daten asynchron von den Servern ab. Es ist wichtig, `Client.get_remote_visitor_data` *vor* dem Abrufen der Variation oder der Prüfung, ob das Feature Flag aktiv ist, aufzurufen, da diese Daten möglicherweise erforderlich sind, um einem Benutzer eine bestimmte Variation zuzuweisen.
Weitere Informationen zu den verfügbaren Targeting-Bedingungen finden Sie im [ausführlichen Artikel zu diesem Thema](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
Außerdem stehen Ihnen die zum Besucherprofil hinzugefügten Datenpunkte bei der Analyse Ihrer Experimente zur Verfügung, sodass Sie Ihre Ergebnisse nach Faktoren wie Gerät und Browser filtern und aufschlüsseln können. Der Kameleoon-Hybridmodus erfasst clientseitig automatisch eine Vielzahl von Datenpunkten, was es einfach macht, Ihre Ergebnisse anhand dieser vorab erfassten Datenpunkte aufzuschlüsseln. 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 die automatisch erfassten hinaus verfolgen möchten, können Sie die Funktion [Custom Data](#customdata) von Kameleoon verwenden. Mit Custom Data können Sie spezifische, für Ihre Experimente relevante Informationen erfassen und analysieren. Vergessen Sie nicht, die Methode [`Client.flush`](#flush) aufzurufen, um die gesammelten Daten zur Analyse an die Kameleoon-Server zu senden.
Um die Genauigkeit Ihrer Ergebnisse zu gewährleisten, wird empfohlen, Bots mithilfe des Datentyps [`UserAgent`](#useragent) herauszufiltern.
##### Tracking von Zielkonvertierungen
Wenn ein Benutzer eine gewünschte Aktion ausführt (z. B. einen Kauf tätigt), wird dies als Konvertierung erfasst. Verwenden Sie die Methode [`Client.track_conversion`](#track_conversion) und geben Sie die erforderlichen Parameter `visitor_code` und `goal_id` an, um Konvertierungen zu tracken.
Die Anfrage zum Tracken der Konvertierung wird zusammen mit der nächsten geplanten Tracking-Anfrage gesendet, die das SDK in regelmäßigen Abständen (definiert durch [`tracking_interval_millis`](#zusätzliche-konfiguration)) sendet. Wenn Sie die Anfrage sofort senden möchten, verwenden Sie die Methode [`Client.flush_instant`](#flush).
##### Ereignisse an Analyselösungen senden
Um Konvertierungen zu tracken und Expositionsereignisse 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 anschließend die Methode [`Client.get_engine_tracking_code`](#get_engine_tracking_code).
Die Methode `Client.get_engine_tracking_code` ruft den eindeutigen Tracking-Code ab, der erforderlich ist, um Expositionsereignisse an Ihre Analyselösung zu senden. Mit dieser Methode können Sie Ereignisse 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 den Variationen von Feature Flags zuzuweisen. Diese ID wird typischerweise auf dem Gerät des Benutzers generiert und gespeichert (in einem Browser-Cookie bei client- und serverseitigen SDKs – im persistenten Speicher bei mobilen SDKs). In bestimmten Szenarien müssen Sie jedoch möglicherweise sicherstellen, dass alle Benutzer derselben Organisation dieselbe Variante eines Feature Flags sehen.
Die Option **benutzerdefinierter Bucketing-Schlüssel** ermöglicht es Ihnen, dieses Standardverhalten zu überschreiben, indem Sie Ihren eigenen benutzerdefinierten Bezeichner für das Bucketing angeben. Diese Überschreibung stellt sicher, dass die Zuweisungslogik von Kameleoon den von Ihnen angegebenen Schlüssel anstelle des standardmäßigen `visitor_code` verwendet.
#### Anwendungsfälle
Die Verwendung eines benutzerdefinierten Bucketing-Schlüssels ist entscheidend für die Aufrechterhaltung von Konsistenz und Genauigkeit bei Ihren Feature-Flag-Zuweisungen, insbesondere in folgenden Situationen:
* **Experimente auf Konto- oder Organisationsebene:** Bei B2B-Produkten 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-Tests von 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 Ihrer Experimente, was zu verlässlicheren Ergebnissen und einer besseren Benutzererfahrung führt.
#### Technische Details
Wenn Sie einen benutzerdefinierten Bucketing-Schlüssel für ein Feature Flag konfigurieren, übergeben Sie Kameleoon einen spezifischen Bezeichner aus den Daten Ihrer Anwendung:
```elixir theme={null}
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
:ok = Client.add_data(client, visitor_code, CustomData.new!(42, ["new_visitor_code"]))
```
* **Bereitstellung des benutzerdefinierten Schlüssels:** Sie übergeben Ihren benutzerdefinierten Bezeichner an das Kameleoon SDK mithilfe der Methode [`Client.add_data`](#add_data). Bei dieser Methode übergeben Sie den von Ihnen gewählten benutzerdefinierten Bucketing-Schlüssel als [`CustomData`](#customdata)-Objekt. Hier bezeichnet `new_visitor_code` den Bezeichner, den Sie für Ihr Bucketing verwenden möchten (z. B. die neue `user_id` oder `account_id`).
Damit der benutzerdefinierte Bucketing-Schlüssel korrekt funktioniert, muss er auch beim Erstellen oder Bearbeiten des Feature Flags definiert und konfiguriert werden. Ohne diese entsprechende Konfiguration wendet das SDK Ihren benutzerdefinierten Schlüssel nicht beim Bucketing 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 `Client.add_data` bereitgestellt wurde, verwenden alle Hash-Berechnungen zur Zuweisung von Benutzern zu Variationen diesen `new_visitor_code` (Ihren benutzerdefinierten Schlüssel) anstelle des standardmäßigen `visitor_code`. Durch die Verwendung des `new_visitor_code` ist die Bucketing-Entscheidung an Ihren benutzerdefinierten Bezeichner gebunden, was konsistente Zuweisungen in verschiedenen Kontexten gewährleistet, in denen dieser Bezeichner vorhanden ist.
* **Datenverfolgung und Analyse:** Es ist wichtig zu beachten, dass zwar der `new_visitor_code` (Ihr benutzerdefinierter Schlüssel) für Bucketing-Entscheidungen verwendet wird, aber **alle nachfolgenden Daten (z. B. Tracking-Ereignisse und Konvertierungen) mit dem *ursprünglichen* `visitor_code` gesendet und verknüpft werden.** Diese Trennung stellt sicher, dass Ihre Analysen die individuellen Benutzerreisen und Interaktionen im breiteren Kontext Ihres Experiments korrekt widerspiegeln, selbst wenn das Bucketing auf einer höheren Ebene (z. B. einem Konto) oder über mehrere Geräte/Sitzungen hinweg erfolgt. Ihre ursprünglichen Besucherdaten bleiben für umfassende Berichte erhalten.
#### Technische Anforderungen
Um einen benutzerdefinierten Bucketing-Schlüssel effektiv zu verwenden:
* Der Schlüssel muss ein `String.t()` sein.
* Er muss für die Entität, für die Sie das Bucketing durchführen möchten, eindeutig sein (z. B. 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, die Sie verwenden können, um Benutzer in Ihren Kampagnen anzusprechen. Eine Liste der von diesem SDK unterstützten Bedingungen finden Sie unter [Besuchshistorie 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 verwenden](/developer-docs/apis/data-api-rest/tutorials/storing-and-retrieving-external-data-to-target-users).
### Geräteübergreifende Experimente
Um Besucher zu unterstützen, die von mehreren Geräten aus auf eine App zugreifen, ermöglicht Kameleoon die Synchronisierung zuvor erfasster Besucherdaten zwischen allen Geräten eines Besuchers und die Zusammenführung seiner Besuchshistorie geräteübergreifend mithilfe geräteübergreifender Experimente. Fallstudien und detaillierte Informationen darüber, wie Kameleoon Daten geräteübergreifend handhabt, finden Sie im [Artikel zu geräteübergreifenden Experimenten](/developer-docs/cross-device-experimentation).
#### Synchronisieren von benutzerdefinierten Daten geräteübergreifend
Obwohl benutzerdefinierte Mapping-Synchronisierung verwendet wird, um Besucherdaten geräteübergreifend abzugleichen, ist sie nicht immer erforderlich. Im Folgenden werden zwei Szenarien beschrieben, in denen eine benutzerdefinierte Mapping-Synchronisierung nicht notwendig ist:
**Gleiche Benutzer-ID auf allen Geräten**
Wenn dieselbe Benutzer-ID auf allen Geräten konsistent verwendet wird, erfolgt die Synchronisierung automatisch ohne benutzerdefinierte Mapping-Synchronisierung. Es genügt, die Methode `Client.get_remote_visitor_data` aufzurufen, wenn Sie die zwischen mehreren Geräten erfassten 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 auf allen Servern verfügbar ist, ist die Synchronisierung zwischen Servern (mit `Client.get_remote_visitor_data`) ausreichend, ohne dass eine zusätzliche benutzerdefinierte Mapping-Synchronisierung erforderlich ist.
Kunden, die zusätzliche Daten benötigen, finden weitere Hinweise in der Beschreibung der Methode [`Client.get_remote_visitor_data`](#get_remote_visitor_data). Im untenstehenden Code wird davon ausgegangen, dass derselbe eindeutige Bezeichner (in diesem Fall der `visitor_code`, der auch als `userId` bezeichnet werden kann) auf den beiden Geräten für einen genauen Datenabruf konsistent verwendet wird.
Wenn Sie erfasste Daten in Echtzeit synchronisieren möchten, müssen Sie den Scope **Visitor** für Ihre benutzerdefinierten Daten wählen.
```elixir title="Device A" theme={null}
# In this example, a Custom data with index `90` was set to "Visitor" scope in Kameleoon.
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
visitor_scope_custom_data_index = 90
:ok = Client.add_data(client, visitor_code, CustomData.new!(visitor_scope_custom_data_index, ["your data"]))
:ok = Client.flush_instant(client, visitor_code)
```
```elixir title="Device B" theme={null}
# Before working with the data, call the `get_remote_visitor_data` method.
:ok = Client.get_remote_visitor_data(client, visitor_code)
# 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 benutzerdefinierten Daten zur Sitzungszusammenführung
[Geräteübergreifende Experimente](/developer-docs/cross-device-experimentation) ermöglichen es, die Historie eines Besuchers über alle seine Geräte hinweg zu kombinieren (Historien-Zusammenführung). Die Historien-Zusammenführung ermöglicht das Zusammenführen verschiedener Besuchersitzungen zu einer einzigen. Verwenden Sie [`CustomData`](#customdata), um einen eindeutigen Bezeichner für den Besucher bereitzustellen und die Besuchshistorie zusammenzuführen. Weitere Informationen finden Sie in der [entsprechenden Dokumentation](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation).
Nachdem die geräteübergreifende Zusammenführung aktiviert ist, ruft der Aufruf von [`Client.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 werden in einem Experiment immer derselben Variation zugeordnet. In der Besucheransicht Ihrer Experimentergebnisseiten erscheinen diese Sitzungen als ein einziger Besucher.
Die SDK-Konfiguration stellt sicher, dass zugeordnete Sitzungen immer dieselbe Variation des Experiments sehen. Es gibt jedoch einige Einschränkungen hinsichtlich der geräteübergreifenden Variationszuweisung. Diese Einschränkungen sind [hier](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights) beschrieben.
Folgen Sie der Anleitung [Aktivieren der geräteübergreifenden Historien-Zusammenführung](#geräteübergreifende-experimente), um Ihre benutzerdefinierten Daten 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:
* `Client.get_remote_visitor_data` mit hinzugefügtem `UniqueIdentifier(true)` – um Daten für alle verknüpften Besucher abzurufen.
* [`Client.track_conversion`](#track_conversion) oder [`Client.flush`](#flush) mit hinzugefügtem `UniqueIdentifier(true)`-Datentyp – um bestimmte Daten für einen Besucher zu tracken, der mit einem anderen Besucher verknüpft ist.
Da die von Ihnen als Bezeichner verwendeten benutzerdefinierten Daten auf den **Visitor-Scope** gesetzt werden müssen, müssen Sie die [geräteübergreifende Synchronisierung benutzerdefinierter Daten](/developer-docs/cross-device-experimentation) verwenden, um den Bezeichner auf jedem Gerät mit der Methode [`Client.get_remote_visitor_data`](#get_remote_visitor_data) abzurufen.
Hier ist ein Beispiel für die Verwendung benutzerdefinierter Daten zur Sitzungszusammenführung.
```elixir theme={null}
# In this example, 91 represents the Custom Data's index configured as a unique identifier in Kameleoon.
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
alias Kameleoon.Data.UniqueIdentifier
mapping_index = 91
feature_key = "ff123"
anonymous_visitor_code = "anonymous-visitor"
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.
{:ok, anonymous_variation} = Client.get_variation(client, anonymous_visitor_code, feature_key)
# 2. After the visitor is authenticated
# Assume `userId` is the visitor code of the authenticated visitor.
:ok = Client.add_data(client, anonymous_visitor_code, CustomData.new!(mapping_index, [user_id]))
:ok = Client.flush_instant(client, anonymous_visitor_code)
# Indicate that `userId` is a unique identifier.
:ok = Client.add_data(client, 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.
{:ok, user_variation} = Client.get_variation(client, user_id, feature_key)
is_same_variation = user_variation.key == anonymous_variation.key # true
# `userId` and `anonymousVisitorCode` are now linked and can be tracked as a single visitor.
:ok = Client.track_conversion(client, user_id, 123)
# Additionally, the linked visitors share all fetched previously tracked remote data.
:ok = Client.get_remote_visitor_data(client, user_id)
```
In diesem Beispiel verfügt die Anwendung über eine Anmeldeseite. Da die Benutzer-ID zum Zeitpunkt der Anmeldung unbekannt ist, wird ein anonymer Besucher-Bezeichner verwendet, der von der Methode [`Client.get_visitor_code`](#get_visitor_code) generiert wurde. Nachdem sich der Benutzer angemeldet hat, wird der anonyme Besucher mit der Benutzer-ID verknüpft und als eindeutiger Bezeichner für den Besucher verwendet.
### Logging
Das SDK generiert Logs, um verschiedene interne Prozesse und Probleme abzubilden.
#### Log-Level
Das SDK unterstützt die Konfiguration der Logging-Begrenzung durch ein Log-Level.
```elixir theme={null}
alias Kameleoon.Logger
# The `:none` log level does not allow logging.
:ok = Logger.set_log_level(:none)
# The `:error` log level only allows logging issues that may affect the SDK's primary behaviour.
:ok = Logger.set_log_level(:error)
# The `:warning` log level allows logging issues which may require attention.
# It extends the `:error` log level.
# The `:warning` log level is the default log level.
:ok = Logger.set_log_level(:warning)
# The `:info` log level allows logging general information on the SDK's internal processes.
# It extends the `:warning` log level.
:ok = Logger.set_log_level(:info)
# The `:debug` level logs additional details about the SDK's internal processes.
:ok = Logger.set_log_level(:debug)
```
#### Benutzerdefinierte Verarbeitung von Logs
Das SDK schreibt seine Logs standardmäßig in die Konsolenausgabe. Dieses Verhalten kann überschrieben werden.
Die Begrenzung des Loggings nach Log-Level erfolgt unabhängig von der Logik der Logverarbeitung.
```elixir theme={null}
defmodule MyKameleoonLogger do
@behaviour Kameleoon.Logger
require Logger
@impl true
def log(level, message) do
Logger.log(level, message)
end
end
# 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.
:ok = Kameleoon.Logger.set_log_level(:debug)
:ok = Kameleoon.Logger.set_logger(MyKameleoonLogger)
```
## Referenz
Dies ist die vollständige Referenzdokumentation für das Elixir SDK.
### Initialisierung
#### create()
Um das SDK zu verwenden, erstellen Sie einen `%Kameleoon.Client\{\}` mit `Kameleoon.ClientFactory.create`. Standardmäßig liest `create` die Datei `/etc/kameleoon/client-elixir.conf`. Sie können auch entweder eine `%Kameleoon.ClientConfig\{\}`-Struktur über `config:` oder einen benutzerdefinierten Konfigurationsdateipfad über `config_path:` angeben.
```elixir theme={null}
alias Kameleoon.ClientConfig
alias Kameleoon.ClientFactory
config = %ClientConfig{
client_id: "",
client_secret: "",
refresh_interval_minutes: 60,
session_duration_minutes: 30,
default_timeout_millis: 10_000,
tracking_interval_millis: 1_000,
environment: "development",
top_level_domain: ".example.com",
proxy_host: "http://192.168.0.25:8080",
network_domain: "example.com"
}
{:ok, client} = ClientFactory.create(site_code, config: config)
```
##### Argumente
| Name | Typ | Beschreibung |
| ---------------------------- | ---------------------------- | ----------------------------------------------------------------- |
| `site_code` (*erforderlich*) | `String.t()` | Eindeutiger Schlüssel des vom SDK verwendeten Kameleoon-Projekts. |
| `config` (*erforderlich*) | `Kameleoon.ClientConfig.t()` | SDK-Konfigurationsstruktur. |
```elixir theme={null}
alias Kameleoon.ClientFactory
{:ok, client} = ClientFactory.create("a8st4f59bj", config_path: "/etc/kameleoon/client-elixir.conf")
```
##### Argumente
| Name | Typ | Beschreibung |
| ------------------------------ | ------------ | ----------------------------------------------------------------- |
| `site_code` (*erforderlich*) | `String.t()` | Eindeutiger Schlüssel des vom SDK verwendeten Kameleoon-Projekts. |
| `config_path` (*erforderlich*) | `String.t()` | Pfad zur Konfigurationsdatei. |
##### Rückgabewert
| Typ | Beschreibung | |
| ------------------------------ | -------------------------------- | ----------------------------------------------------------------------- |
| \`\{:ok, Kameleoon.Client.t()} | \{:error, Kameleoon.Error.t()}\` | Bei Erfolg eine Client-Instanz, andernfalls ein Initialisierungsfehler. |
##### Fehler
| Typ | Beschreibung |
| -------------------------- | ---------------------------------- |
| `ConfigCredentialsInvalid` | Die SDK-Anmeldedaten fehlen. |
| `SiteCodeIsEmpty` | Der angegebene Site-Code ist leer. |
#### initialize()
Wartet auf die Initialisierung des Kameleoon-Clients, entweder mit dem konfigurierten [`default_timeout_millis`](#zusätzliche-konfiguration) oder mit einem bereitgestellten `timeout`. Diese Methode stellt sicher, dass der Client vollständig initialisiert ist, bevor weitere Operationen ausgeführt werden.
```elixir theme={null}
alias Kameleoon.Client
# Initializes the client using the configured default timeout
:ok = Client.initialize(client)
# Initializes the client with a custom timeout of 5 seconds
:ok = Client.initialize(client, timeout: 5_000)
```
##### Argumente
| Name | Typ | Beschreibung |
| ---------------------- | ------------------- | ------------------------------------------------------------ |
| `timeout` (*optional*) | `non_neg_integer()` | Maximale Wartezeit für die Initialisierung in Millisekunden. |
##### Rückgabewert
| Typ | Beschreibung | |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------------------ |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Gibt an, ob die Initialisierung erfolgreich abgeschlossen wurde oder ein Fehler aufgetreten ist. |
##### Fehler
| Typ | Beschreibung |
| ---------------- | --------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
#### is\_ready()
Prüft, ob der Client initialisiert wurde.
```elixir theme={null}
{:ok, ready?} = Kameleoon.Client.is_ready?(client)
if ready? do
# The client is ready
end
```
##### Rückgabewert
| Typ | Beschreibung | |
| ------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| \`\{:ok, boolean()} | \{:error, Kameleoon.Error.t()}\` | `\{:ok, true\}`, wenn der Client einsatzbereit ist, `\{:ok, false\}`, wenn er nicht bereit ist, andernfalls ein Fehler. |
#### forget()
Entfernt den zwischengespeicherten SDK-Client, der mit dem angegebenen `site_code` verknüpft ist.
```elixir theme={null}
alias Kameleoon.ClientFactory
# Removes the cached client for the given site code
:ok = ClientFactory.forget("a8st4f59bj")
# Removes the cached client for the given site code and environment
:ok = ClientFactory.forget("a8st4f59bj", environment: "production")
```
##### Argumente
| Name | Typ | Beschreibung |
| ---------------------------- | ------------ | --------------------------------------------------------------------------- |
| `site_code` (*erforderlich*) | `String.t()` | Eindeutiger Bezeichner des Kameleoon-Projekts. |
| `environment` (*optional*) | `String.t()` | Umgebungsschlüssel, der mit dem zwischengespeicherten Client verknüpft ist. |
##### Rückgabewert
| Typ | Beschreibung | |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | 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 `track`-Option)*
Bestimmt, ob ein Feature Flag für einen bestimmten Benutzer aktiv ist.
Wenn der Besucher für dieses Feature Flag noch nicht ausgewertet wurde, wertet das SDK die Targeting-Regeln aus und gibt das Ergebnis zurück. Wenn der Besucher bereits über eine gespeicherte Auswertung für das Feature verfügt, verwendet das SDK das vorhandene Ergebnis erneut, um die Konsistenz zu gewährleisten.
Kameleoon verwendet Tracking, um Sitzungen und Besucher zu zählen, wenn Sie bestimmte Methoden aufrufen, z. B. `Client.is_feature_active?`, `Client.get_variation` oder `Client.get_variations`.
Verwenden Sie den Standardwert `true` für den Parameter `track`, wenn Sie Besucher einer Variation aussetzen und sie zählen möchten. Setzen Sie den Parameter `track` nur dann auf `false`, wenn Sie diese Methoden aufrufen, bevor Sie die Besucher aussetzen.
Wenn Sie beispielsweise `Client.get_variations` aufrufen, um vor der Aussetzung der Besucher alle Variationen abzurufen, setzen Sie den Parameter `track` auf `false`. Diese Einstellung verhindert, dass Kameleoon eine Sitzung vorzeitig zählt. Sie können das Tracking später auslösen, wenn Sie den Besucher explizit aussetzen.
Kameleoon sendet Tracking-Daten standardmäßig jede Sekunde. Sie können dieses Intervall über die Konfigurationsoption 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 den Tracking-Ereignissen mehr als 30 Minuten vergehen, zählt Kameleoon die Ereignisse als separate Sitzungen. Ein Besuch erscheint 30 Minuten nach dem zuletzt aufgezeichneten Ereignis der Sitzung in Ihren Berichten.
Die Methode `Client.is_feature_active?` wertet die ausgelieferte Variante aus, nicht den Master-Flag-Status. Wenn Sie Regeln ausschließen, verwendet die Methode den Standardstatus **Dann allen anderen ausliefern**. Wenn Sie für diesen Standardstatus **Off** auswählen, gibt die Methode immer `false` zurück, selbst wenn das Master-Feature-Flag **On** ist.
```elixir theme={null}
alias Kameleoon.Client
feature_key = "new_checkout"
# Evaluates the feature flag and sends tracking data (default behavior)
{:ok, active?} = Client.is_feature_active?(client, visitor_code, feature_key)
# Evaluates the feature flag without sending tracking data
{:ok, active_without_tracking?} =
Client.is_feature_active?(client, visitor_code, feature_key, track: false)
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------- | ------------ | --------------------------------------------------------------------- | -------- |
| `visitor_code` (*erforderlich*) | `String.t()` | Eindeutiger Bezeichner des Benutzers. | |
| `feature_key` (*erforderlich*) | `String.t()` | Schlüssel des Features, das für den Benutzer ausgewertet werden soll. | |
| `track` (*optional*) | `boolean()` | Aktiviert oder deaktiviert das Tracking der Feature-Auswertung. | `true` |
##### Rückgabewert
| Typ | Beschreibung | |
| ------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------- |
| \`\{:ok, boolean()} | \{:error, Kameleoon.Error.t()}\` | Gibt an, ob das Feature Flag für den angegebenen `visitor_code` aktiv ist, oder gibt einen Fehler zurück. |
##### Fehler
| Typ | Beschreibung |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `FeatureNotFound` | Ausnahme, die angibt, dass der angeforderte Feature-Schlüssel in der internen Konfiguration des SDK nicht gefunden wurde. Das bedeutet normalerweise, dass das Feature Flag in der Kameleoon-App nicht aktiviert ist (während der Code, der das Feature implementiert, bereits in der Anwendung bereitgestellt wurde). |
| `VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Visitor Code 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 ein bestimmtes Feature Flag zugewiesene [`Variation`](#variation) ab.
Diese Methode akzeptiert `visitor_code` und `feature_key` 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 keinen Feature-Flag-Regeln zugeordnet ist, gibt die Methode die standardmäßige `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 keiner der vordefinierten Auslieferungsregeln eines Feature Flags entspricht. Mit anderen Worten ist es die Fallback-Variation, die auf alle Benutzer angewendet wird, die nicht durch spezifische Regeln angesprochen werden. Sie wird durch die Variation im Abschnitt „Dann für alle anderen ...“ in einer Verwaltungsoberfläche dargestellt.
```elixir theme={null}
alias Kameleoon.Client
feature_key = "new_checkout"
# Retrieves the variation assigned to the visitor (with tracking enabled by default)
{:ok, variation} = Client.get_variation(client, visitor_code, feature_key)
# Retrieves the variation without sending tracking data
{:ok, variation_without_tracking} =
Client.get_variation(client, visitor_code, feature_key, track: false)
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------ | ------------ | ----------------------------------------------------------------------------------------------- | -------- |
| visitor\_code (*erforderlich*) | `String.t()` | Eindeutiger Bezeichner des Besuchers. | |
| feature\_key (*erforderlich*) | `String.t()` | Schlüssel des Features, das einem Besucher ausgespielt werden soll. | |
| track (*optional*) | `boolean()` | Ein optionaler Parameter zum Aktivieren oder Deaktivieren des Trackings der Feature-Auswertung. | `true` |
##### Rückgabewert
| Typ | Beschreibung |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `\{:ok, Kameleoon.Types.Variation.t()\} \| \{:error, Kameleoon.Error.t()\}` | Bei Erfolg eine zugewiesene [`Variation`](#variation) für einen bestimmten Besucher zu einem bestimmten Feature Flag, andernfalls ein Fehler. |
##### Fehler
| Typ | Beschreibung |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Visitor Code ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
| `FeatureNotFound` | Ausnahme, die angibt, dass der angeforderte Feature-Schlüssel in der internen Konfiguration des SDK nicht gefunden wurde. Das bedeutet normalerweise, dass das Feature Flag in der Kameleoon-App nicht aktiviert ist (während der Code, der das Feature implementiert, bereits in der Anwendung bereitgestellt wurde). |
| `FeatureEnvironmentDisabled` | Ausnahme, die angibt, dass das Feature Flag für die aktuelle Umgebung des Besuchers (z. B. Production, Staging oder Development) deaktiviert ist. |
| `FeatureEvaluationBlocked` | Ausnahme, die angibt, dass die Feature-Auswertung blockiert ist. Der Grund wird in der Fehlermeldung beschrieben. Dies tritt normalerweise aufgrund von DSGVO-Einschrä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 über alle Feature Flags hinweg zugewiesen sind.
Diese Methode iteriert über alle verfügbaren Feature Flags und gibt die zugewiesene `Variation` für jedes Flag zurück, das dem angegebenen Besucher zugeordnet ist. Sie akzeptiert `visitor_code` als obligatorisches Argument, während `only_active` und `track` optional sind.
* Wenn `only_active` auf `true` gesetzt ist, gibt die Methode `Client.get_variations` die Feature-Flag-Variationen zurück, sofern der Benutzer nicht der `off`-Variation zugeordnet ist.
* Der Parameter `track` steuert, ob die Methode die Variationszuweisungen trackt. Standardmäßig ist er auf `true` gesetzt. Bei `false` wird das Tracking deaktiviert.
Die zurückgegebene Map enthält Feature-Flag-Schlüssel als Schlüssel und ihre entsprechenden `Variation` als Werte. Wenn einem 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 keiner der vordefinierten Auslieferungsregeln eines Feature Flags entspricht. Mit anderen Worten ist es die Fallback-Variation, die auf alle Benutzer angewendet wird, die nicht durch spezifische Regeln angesprochen werden. Sie wird durch die Variation im Abschnitt „Dann für alle anderen ...“ in einer Verwaltungsoberfläche dargestellt.
```elixir theme={null}
alias Kameleoon.Client
# Retrieves all variations assigned to the visitor (with default options)
{:ok, variations} = Client.get_variations(client, visitor_code)
# Retrieves only active variations for the visitor
{:ok, only_active_variations} = Client.get_variations(client, visitor_code, only_active: true)
# Retrieves variations without sending tracking data
{:ok, variations_without_tracking} = Client.get_variations(client, visitor_code, track: false)
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| visitor\_code (*erforderlich*) | `String.t()` | Eindeutiger Bezeichner des Besuchers. | |
| only\_active (*optional*) | `boolean()` | Ein optionaler Parameter, der angibt, ob Variationen für aktive (`true`) oder alle (`false`) Feature Flags zurückgegeben werden sollen. | `false` |
| track (*optional*) | `boolean()` | Ein optionaler Parameter zum Aktivieren oder Deaktivieren des Trackings der Feature-Auswertung. | `true` |
##### Rückgabewert
| Typ | Beschreibung |
| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `\{:ok, %\{String.t() => Kameleoon.Types.Variation.t()\}\} \| \{:error, Kameleoon.Error.t()\}` | Map, die bei Erfolg die zugewiesenen [`Variation`](#variation)-Objekte der Feature Flags unter den Schlüsseln der entsprechenden Features enthält, andernfalls ein Fehler. |
##### Fehler
| Typ | Beschreibung |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Visitor Code ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
#### set\_forced\_variation()
Mit dieser Methode können Sie einem Benutzer programmgesteuert eine bestimmte [`Variation`](#variation) zuweisen und so den üblichen Auswertungsprozess 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 gesetzt 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 `force_targeting=false`.
**Simulierte** Variationen haben in der Ausführungsreihenfolge immer Vorrang. Wenn eine Berechnung einer **simulierten** Variation ausgelöst wird, wird sie zuerst vollständig verarbeitet und abgeschlossen.
Eine erzwungene Variation wird genauso behandelt wie eine ausgewertete Variation. Sie wird in Analysen getrackt und im Benutzerkontext wie jede standardmäßig ausgewertete Variation gespeichert, um Konsistenz in den Berichten 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**: Wirken sich auf das Gesamtergebnis des **Feature Flags** aus.
```elixir theme={null}
alias Kameleoon.Client
experiment_id = 202_387
# Forces the visitor into "variation_2" for the given experiment
:ok = Client.set_forced_variation(client, visitor_code, experiment_id, "variation_2")
# Removes any previously forced variation for the visitor in this experiment
:ok = Client.set_forced_variation(client, visitor_code, experiment_id, nil)
# Forces the visitor into "variation_2" with custom options.
# In this case, targeting rules are respected (force_targeting = false).
:ok =
Client.set_forced_variation(
client,
visitor_code,
experiment_id,
"variation_2",
force_targeting: false
)
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| visitor\_code (*erforderlich*) | `String.t()` | Eindeutiger Bezeichner des Besuchers. | |
| experiment\_id (*erforderlich*) | `non_neg_integer()` | **Experiment-ID**, die während des Auswertungsprozesses gezielt angesprochen und ausgewählt wird. | |
| variation\_key (*erforderlich*) | `String.t() \| nil` | **Variation-Key**, der einer `Variation` entspricht, die als Rückgabewert für das Experiment erzwungen werden soll. Wenn der Wert `nil` ist, wird die erzwungene Variation zurückgesetzt. | |
| force\_targeting (*optional*) | `boolean()` | Gibt an, ob das Targeting für das Experiment erzwungen und übersprungen werden soll (`true`) oder wie im standardmäßigen Auswertungsprozess angewendet werden soll (`false`). | `true` |
##### Rückgabewert
| Typ | Beschreibung | |
| ----- | -------------------------------- | ----------------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Gibt an, ob die erzwungene Variation erfolgreich gesetzt wurde oder ein Fehler aufgetreten ist. |
##### Fehler
| Typ | Beschreibung |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Visitor Code ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
| `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 Kameleoon-Seite noch nicht aktiviert wurde. |
| `FeatureVariationNotFound` | Ausnahme, die angibt, dass der angeforderte Variations-Schlüssel (ID) in der internen Konfiguration des SDK nicht gefunden wurde. Dies ist normalerweise normal und bedeutet, dass das der Variation entsprechende Experiment auf Kameleoon-Seite noch nicht aktiviert wurde. |
#### evaluate\_audiences()
* 📨 *Sendet Tracking-Daten an Kameleoon*
Diese Methode wertet Besucher gegen alle verfügbaren Audiences-Explorer-Segmente aus und trackt diejenigen, die übereinstimmen.
`Client.evaluate_audiences` sollte aufgerufen werden, **nachdem alle relevanten Besucherdaten gesetzt oder aktualisiert wurden**, und **kurz bevor** eine Feature-Variation abgerufen oder ein Feature Flag geprüft wird. Dieser Ansatz stellt sicher, dass der Besucher anhand der aktuellsten verfügbaren Daten ausgewertet wird und ermöglicht eine genaue Audience-Zuweisung anhand aller Kriterien.
Nach dem Aufruf dieser Methode können Sie eine detaillierte Analyse der Segmentleistung im Audiences Explorer durchführen.
```elixir theme={null}
:ok = Kameleoon.Client.evaluate_audiences(client, visitor_code)
```
##### Argumente
| Name | Typ | Beschreibung |
| ------------------------------ | ------------ | ------------------------------------- |
| visitor\_code (*erforderlich*) | `String.t()` | Eindeutiger Bezeichner des Besuchers. |
##### Rückgabewert
| Typ | Beschreibung | |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------ |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Gibt an, ob die Audience-Auswertung erfolgreich war oder ein Fehler aufgetreten ist. |
##### Fehler
| Typ | Beschreibung |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Visitor Code ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
#### get\_datafile()
Um alle Feature Flags auszuwerten, verwenden Sie [`Client.get_variations`](#get_variations). Diese Methode ist effizienter als der Aufruf von `DataFile` und das Iterieren durch die Flags mit [`Client.get_variation`](#get_variation).
Gibt die aktuelle SDK-Konfiguration als [`DataFile`](#datafile)-Objekt zurück.
```elixir theme={null}
{:ok, datafile} = Kameleoon.Client.get_datafile(client)
```
##### Rückgabewert
| Typ | Beschreibung |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `\{:ok, Kameleoon.Types.DataFile.t()\} \| \{:error, Kameleoon.Error.t()\}` | Bei Erfolg das [`DataFile`](#datafile) mit der SDK-Konfiguration, andernfalls ein Fehler. |
##### Fehler
| Typ | Beschreibung |
| ---------------- | --------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
### Besucherdaten
#### get\_visitor\_code()
Verwenden Sie `get_visitor_code()`, um den Kameleoon `visitor_code` des aktuellen Besuchers zu erhalten. Die Methode funktioniert mit jedem Cookie-Speicher, der das Behaviour `Kameleoon.CookieAccessor` implementiert.
Die Implementierungslogik lautet 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 den `default_visitor_code`, sofern Sie einen bereitstellen.
3. Andernfalls generiert das SDK einen neuen Visitor Code und speichert ihn über den Accessor.
Weitere Informationen finden Sie unter [Hybride Experimente](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/).
Wenn Sie Ihren eigenen `visitor_code` angeben, muss dessen Eindeutigkeit auf Ihrer Seite gewährleistet sein. Beachten Sie außerdem, dass die Länge des `visitor_code` auf `255` Zeichen begrenzt ist.
Mit der Methode `Client.get_visitor_code` können Sie **simulierte** Variationen für einen Besucher festlegen. Wenn Cookies (aus einer **Request** oder einem **Dokument**) den Schlüssel `kameleoonSimulationFFData` enthalten, wird der Standard-Auswertungsprozess 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 beim Simulieren der Anzeige einer Variante über das [Simulations-Panel](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode) automatisch erstellt.
* **Manuell:** Setzen Sie das Cookie `kameleoonSimulationFFData` manuell.
Es ist wichtig, **simulierte** Variationen von **[erzwungenen](#set_forced_variation)** Variationen zu unterscheiden:
* **Simulierte Variationen**: Wirken sich auf das Gesamtergebnis des **Feature Flags** aus.
* **Erzwungene Variationen**: Sind spezifisch für ein einzelnes Experiment.
⚙️ **Manuelle Einrichtung**
Stellen Sie sicher, dass das Cookie `kameleoonSimulationFFData` dem folgenden Format entspricht:
* `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 **Dann allen anderen in Production ausliefern**) für den angegebenen `featureKey`.
⚠️ Um die ordnungsgemäße Funktionalität sicherzustellen, muss der Cookie-Wert als URI-Komponente kodiert werden, beispielsweise mit einer Methode wie [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent).
```elixir theme={null}
defmodule MemoryCookies do
@behaviour Kameleoon.CookieAccessor
@impl true
def get(cookies, key), do: Map.get(cookies, key)
@impl true
def set(cookies, key, value, _max_age, _top_level_domain) do
Map.put(cookies, key, value)
end
end
cookies = {MemoryCookies, %{}}
# Generate or retrieve a visitor code using an auto-generated value.
{:ok, visitor_code, cookies} = Kameleoon.Client.get_visitor_code(client, cookies)
# Generate or retrieve a visitor code using a predefined user ID.
{:ok, visitor_code, cookies} = Kameleoon.Client.get_visitor_code(client, {MemoryCookies, cookies}, "user_id")
```
```elixir theme={null}
defmodule PlugConnCookies do
@behaviour Kameleoon.CookieAccessor
@impl true
def get(conn, key), do: conn.req_cookies[key]
@impl true
def set(conn, key, value, max_age, top_level_domain) do
opts = [path: "/", max_age: max_age]
opts = if top_level_domain, do: Keyword.put(opts, :domain, top_level_domain), else: opts
Plug.Conn.put_resp_cookie(conn, key, value, opts)
end
end
def get_visitor_code(conn, client) do
cookies = {PlugConnCookies, conn}
with {:ok, visitor_code, conn} <- Kameleoon.Client.get_visitor_code(client, cookies) do
{:ok, visitor_code, conn}
end
end
```
##### Argumente
| Name | Typ | Beschreibung | |
| ----------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| `cookies` (*erforderlich*) | `\{module(), term()\}` | Cookie-Accessor-Modul und framework-spezifischer Zustand zum Lesen und Speichern des Besucher-Cookies. | |
| `default_visitor_code` (*optional*) | \`String.t() | nil\` | Visitor Code, der verwendet wird, wenn kein Cookie vorhanden ist. |
Das Accessor-Modul muss `get` und `set` implementieren. `get` liest einen Cookie-Wert aus dem Accessor-Zustand, und `set` gibt den aktualisierten Zustand zurück, nachdem es `key`, `value`, `max_age` und `top_level_domain` erhalten hat.
##### Rückgabewert
| Typ | Beschreibung | |
| ---------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| \`\{:ok, String.t(), term()} | \{:error, Kameleoon.Error.t()}\` | Bei Erfolg ein String, der einen eindeutigen Visitor Code darstellt, der im SDK verwendet wird, andernfalls ein Fehler. |
#### add\_data()
Die Methode `Client.add_data` fügt [Targeting-Daten](#datentypen) zum Speicher hinzu, sodass andere Methoden anhand dieser Daten entscheiden können, ob der aktuelle Besucher angesprochen werden soll oder nicht.
Die Methode `Client.add_data` gibt keinen Wert zurück und interagiert nicht eigenständig mit den Kameleoon-Backend-Servern. Stattdessen werden alle deklarierten Daten für eine spätere Übertragung mit der Methode [`Client.flush`](#flush) gespeichert. Dieser Ansatz reduziert die Anzahl der Server-Aufrufe, da die Daten typischerweise in einem einzigen Server-Aufruf gebündelt werden, der durch `Client.flush` ausgelöst wird.
Die Methode [`Client.track_conversion`](#track_conversion) sendet ebenfalls alle zuvor zugeordneten Daten, genau wie `Client.flush`. Dasselbe gilt für die Methoden [`Client.get_variation`](#get_variation) und [`Client.get_variations`](#get_variations), wenn eine Experiment-Regel ausgelöst wird.
Jeder Besucher kann für die meisten Datentypen nur eine Instanz zugeordneter Daten haben. [`CustomData`](#customdata) bildet jedoch eine Ausnahme. Besucher können pro Index eine Instanz von `CustomData` zugeordnet haben.
```elixir theme={null}
alias Kameleoon.Client
alias Kameleoon.Data.Browser
alias Kameleoon.Data.PageView
alias Kameleoon.Data.UserAgent
:ok = Client.add_data(client, visitor_code, Browser.new!(:chrome, version: 123.0))
:ok =
Client.add_data(client, visitor_code, [
PageView.new!("https://example.com/pricing", title: "Pricing", referrers: [3]),
UserAgent.new!("Mozilla/5.0")
])
:ok =
Client.add_data(
client,
visitor_code,
PageView.new!("https://example.com/checkout", title: "Checkout"),
track: false
)
```
##### Argumente
| Name | Typ | Beschreibung | Standardwert |
| ------------------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| visitor\_code (*erforderlich*) | `String.t()` | Eindeutiger Bezeichner des Besuchers. | |
| data (*erforderlich*) | `struct() \| [struct()]` | Sammlung von Kameleoon-Datentypen. | |
| track (*optional*) | `boolean()` | Gibt an, ob die hinzugefügten Daten für das Tracking infrage kommen. Bei `false` werden die Daten nur lokal gespeichert und ausschließlich für die Targeting-Auswertung verwendet; sie werden nicht an die Kameleoon Data API gesendet. | `true` |
##### Rückgabewert
| Typ | Beschreibung | |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Gibt an, ob die Daten erfolgreich hinzugefügt wurden oder ein Fehler aufgetreten ist. |
##### Fehler
| Typ | Beschreibung |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Visitor Code 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 enthält 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 Server-Aufruf asynchron durchgeführt wird.
Diese Methode bietet Kontrolle darüber, wann Daten, die mit einem bestimmten `visitor_code` verknüpft sind, übertragen werden. Wenn z. B. `add_data()` 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 eindeutigen Besucher-Bezeichner.
* `flush()` – Stellt einen Flush-Vorgang gemäß dem konfigurierten Tracking-Intervall in die Warteschlange.
* `flush_instant()` – Sendet Tracking-Daten sofort, ohne auf das Intervall zu warten.
```elixir theme={null}
# Queues a flush operation for the given visitor_code.
# Data will be sent according to the configured tracking interval.
:ok = Kameleoon.Client.flush(client, visitor_code)
# Immediately sends all pending tracking data for the given visitor_code.
:ok = Kameleoon.Client.flush_instant(client, visitor_code)
```
##### Argumente
| Name | Typ | Beschreibung |
| ------------------------------- | ------------ | ------------------------------------- |
| `visitor_code` (*erforderlich*) | `String.t()` | Eindeutiger Bezeichner des Besuchers. |
##### Rückgabewert
| Typ | Beschreibung | |
| ----- | -------------------------------- | ----------------------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Gibt an, ob der Vorgang erfolgreich geplant oder ausgeführt wurde oder ob ein Fehler aufgetreten ist. |
##### Fehler
| Typ | Beschreibung |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Visitor Code 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 Elixir-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 speichern und von Ihrem Backend aus wiederverwenden möchten, ohne einen separaten Abrufmechanismus zu pflegen.
```elixir theme={null}
{:ok, data} = Kameleoon.Client.get_remote_data(client, "test-key")
```
##### Argumente
| Name | Typ | Beschreibung |
| ---------------------- | ------------ | --------------------------------------------------------------- |
| `key` (*erforderlich*) | `String.t()` | Schlüssel, der mit den abzurufenden Remote-Daten verknüpft ist. |
##### Rückgabewert
| Typ | Beschreibung | |
| -------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| \`\{:ok, String.t()} | \{:error, Kameleoon.Error.t()}\` | Bei Erfolg die Payload, die mit dem angegebenen `key` verknüpft ist, andernfalls ein Fehler. In den meisten Fällen ist die Payload als String serialisiertes JSON. |
##### Fehler
| Typ | Beschreibung |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `Network` | Wird zurückgegeben, wenn die Remote-Datenanfrage fehlschlägt oder der Server mit einem Nicht-Erfolgs-Statuscode antwortet. |
#### get\_remote\_visitor\_data()
`get_remote_visitor_data()` ruft Kameleoon-Besuchsdaten für den angegebenen `visitor_code` ab. Die Methode fügt die Daten dem lokalen Besucherspeicher hinzu, sodass andere SDK-Methoden sie für Targeting-Entscheidungen verwenden können.
Mit dieser Methode abgerufene Daten sind besonders nützlich, wenn Sie:
* Daten verwenden möchten, die von anderen Geräten erfasst wurden.
* auf die Historie eines Besuchers zugreifen möchten, z. B. zuvor angesehene Seiten aus früheren Besuchen.
* Daten verwenden möchten, die nur clientseitig verfügbar sind, z. B. Datalayer-Variablen und Front-End-Zielkonvertierungen.
Lesen Sie [diesen Artikel](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation), um mögliche Anwendungsfälle besser zu verstehen.
Standardmäßig ruft `get_remote_visitor_data()` automatisch die zuletzt gespeicherten benutzerdefinierten Daten mit `scope=Visitor` ab und ordnet sie dem Besucher zu, ohne dass [`add_data()`](#add_data) aufgerufen werden muss. Dies ist besonders nützlich für die [Synchronisierung benutzerdefinierter Daten über mehrere Geräte hinweg](/developer-docs/cross-device-experimentation/).
```elixir theme={null}
alias Kameleoon.Client
alias Kameleoon.Types.RemoteVisitorDataFilter
# Fetch remote visitor data without any filter.
# This will return all available data for the given visitor.
:ok = Client.get_remote_visitor_data(client, visitor_code)
# Create a filter to limit the returned data.
filter = %RemoteVisitorDataFilter{
previous_visit_amount: 5,
conversions: true,
page_views: true
}
# Fetch remote visitor data using the specified filter.
# This will return only the data matching the filter criteria.
:ok = Client.get_remote_visitor_data(client, visitor_code, filter: filter)
```
##### Argumente
| Name | Typ | Beschreibung | Standard | |
| ------------------------------- | --------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------ |
| `visitor_code` (*erforderlich*) | `String.t()` | Visitor Code, dessen Daten abgerufen werden sollen. | | |
| `filter` (*optional*) | \`Kameleoon.Types.RemoteVisitorDataFilter.t() | nil\` | Filter, der beschreibt, welche Remote-Besucherdaten abgerufen werden sollen. | `%RemoteVisitorDataFilter\{\}` |
##### Rückgabewert
| Typ | Beschreibung | |
| ----- | -------------------------------- | ----------------------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Erfolgreiche Rückgabe, wenn die Daten abgerufen und lokal hinzugefügt wurden, andernfalls ein Fehler. |
##### Fehler
| Typ | Beschreibung |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Visitor Code ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
| `Network` | Wird zurückgegeben, wenn die Anfrage nach Remote-Besucherdaten fehlschlägt, nicht geparst werden kann oder der Server mit einem Nicht-Erfolgs-Statuscode antwortet. |
##### Verwenden 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 z. B. Benutzer ansprechen möchten, die in ihren letzten fünf Besuchen auf 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 Besucherverhaltensweisen abzurufen und sie in der Targeting- und Berichtslogik Ihrer Elixir-Anwendung verfügbar zu machen.
##### Felder von `RemoteVisitorDataFilter`
| Name | Typ | Beschreibung | Standard |
| ----------------------- | ------------------- | ----------------------------------------------------------------------- | -------- |
| `previous_visit_amount` | `non_neg_integer()` | Anzahl der vorherigen Besuche, aus denen Daten abgerufen werden sollen. | `1` |
| `current_visit` | `boolean()` | Bei `true` werden die Daten des aktuellen Besuchs abgerufen. | `true` |
| `custom_data` | `boolean()` | Bei `true` werden benutzerdefinierte Daten abgerufen. | `true` |
| `visitor_code` | `boolean()` | Bei `true` wird der zuletzt verwendete Visitor Code wiederverwendet. | `true` |
| `page_views` | `boolean()` | Bei `true` werden Seitenaufrufdaten abgerufen. | `false` |
| `geolocation` | `boolean()` | Bei `true` werden Geolokalisierungsdaten abgerufen. | `false` |
| `device` | `boolean()` | Bei `true` werden Gerätedaten abgerufen. | `false` |
| `browser` | `boolean()` | Bei `true` werden Browserdaten abgerufen. | `false` |
| `operating_system` | `boolean()` | Bei `true` werden Betriebssystemdaten abgerufen. | `false` |
| `conversions` | `boolean()` | Bei `true` werden Konvertierungsdaten abgerufen. | `false` |
| `experiments` | `boolean()` | Bei `true` werden Experimentdaten abgerufen. | `false` |
| `kcs` | `boolean()` | Bei `true` werden Daten des Kameleoon Conversion Score abgerufen. | `false` |
| `personalizations` | `boolean()` | Bei `true` werden Personalisierungsdaten abgerufen. | `false` |
| `cbs` | `boolean()` | Bei true werden Daten des Contextual Bandit Score abgerufen. | `false` |
#### get\_visitor\_warehouse\_audience()
Diese Methode ruft die mit einem Besucher in Ihrer Warehouse-Integration verknüpften Audience-Daten ab, 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 benutzerdefinierten Kameleoon-Daten, die Kameleoon zum Ansprechen Ihrer Besucher verwendet.
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 [Dokumentation zum Warehouse-Targeting](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting).
```elixir theme={null}
alias Kameleoon.Client
# Fetch audience data for a visitor using only the visitor_code.
:ok = Client.get_visitor_warehouse_audience(client, visitor_code, 98)
# Fetch audience data for a visitor using both visitor_code and warehouse_key.
# Useful when your warehouse uses a different identifier than visitor_code.
:ok = Client.get_visitor_warehouse_audience(client, visitor_code, 98, warehouse_key: "internal-user-id")
```
##### Argumente
| Name | Typ | Beschreibung | Standard | |
| ------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | -------------- |
| `visitor_code` (*erforderlich*) | `String.t()` | Besucher, dessen Warehouse-Audiences abgerufen werden sollen. | | |
| `custom_data_index` (*erforderlich*) | `non_neg_integer()` | Index der benutzerdefinierten Daten, der in Kameleoon für das Warehouse-Audience-Targeting konfiguriert ist. | | |
| `warehouse_key` (*optional*) | \`String.t() | nil\` | Externer Warehouse-Schlüssel, normalerweise Ihre interne Benutzer-ID. | `visitor_code` |
##### Rückgabewert
| Typ | Beschreibung | |
| ----- | -------------------------------- | -------------------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Erfolg, wenn die Warehouse-Audience-Daten abgerufen und lokal als `CustomData` gespeichert wurden. |
##### Fehler
| Typ | Beschreibung |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Visitor Code ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
| `Network` | Wird zurückgegeben, wenn die Warehouse-Audience-Anfrage fehlschlägt, nicht geparst werden kann oder der Server mit einem Nicht-Erfolgs-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. Wenn `legal_consent` auf `false` gesetzt wird, werden die Datentypen, die in Tracking-Anfragen enthalten sein können, eingeschränkt. Dies hilft Ihnen, gesetzliche und regulatorische Anforderungen einzuhalten und gleichzeitig die Besucherdaten verantwortungsvoll zu verwalten. Weitere Informationen finden Sie in der [Richtlinie zur Einwilligungsverwaltung](/user-manual/project-management/consent-management-policy).
Das Elixir SDK aktualisiert Besucher-Cookies über den erforderlichen `Kameleoon.CookieAccessor`-Adapter und gibt den aktualisierten Adapterzustand zurück.
```elixir theme={null}
cookies = {PlugConnCookies, conn}
# Set consent and update cookies.
{:ok, conn} = Kameleoon.Client.set_legal_consent(client, visitor_code, true, cookies)
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `visitor_code` (*erforderlich*) | `String.t()` | Der eindeutige Bezeichner des Benutzers. | |
| `consent` (*erforderlich*) | `boolean()` | `true` gibt an, dass der Besucher die rechtliche Einwilligung erteilt hat, `false` gibt an, dass der Besucher die rechtliche Einwilligung nie erteilt oder widerrufen hat. | |
| `cookies` (*erforderlich*) | `\{module(), term()\}` | Cookie-Accessor-Modul und framework-spezifischer Zustand zum Aktualisieren von Cookies. | |
##### Rückgabewert
| Typ | Beschreibung | |
| ---------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| \`\{:ok, term()} | \{:error, Kameleoon.Error.t()}\` | Gibt den aktualisierten Cookie-Zustand zurück, wenn der Einwilligungsstatus des Besuchers erfolgreich aktualisiert wurde, andernfalls einen Fehler. |
##### Fehler
| Typ | Beschreibung |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Visitor Code ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
##### Verhalten beim Widerruf der Einwilligung
Wenn Sie `Client.set_legal_consent` mit `legal_consent=false` aufrufen, löscht das SDK das Cookie `kameleoonVisitorCode` nicht. Stattdessen wird das Ablaufdatum des Cookies nicht mehr verlängert, sodass das Cookie bestehen bleibt, bis es auf natürliche Weise abläuft.
Wenn Ihre Compliance-Anforderungen das sofortige Entfernen 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-Analysen
#### track\_conversion()
* 📨 *Sendet Tracking-Daten an Kameleoon*
Verwenden Sie diese Methode, um eine Konvertierung für ein bestimmtes [Ziel](/user-manual//assets/goals/create-a-goal) und einen Benutzer zu tracken. 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 normalerweise identisch mit dem, der beim Auslösen des Experiments verwendet wurde.
Diese Methode ist nicht blockierend, da der Server-Aufruf asynchron erfolgt.
```elixir theme={null}
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
# Track a goal.
:ok = Client.track_conversion(client, visitor_code, goal_id)
# Track a goal with revenue.
:ok = Client.track_conversion(client, visitor_code, goal_id, revenue: 100.0)
# Track a goal with negative revenue.
:ok = Client.track_conversion(client, visitor_code, goal_id, revenue: 100.0, negative: true)
# Track a goal with custom metadata.
:ok =
Client.track_conversion(
client,
visitor_code,
goal_id,
metadata: [CustomData.new!(4, ["true"])]
)
```
##### Argumente
| Name | Typ | Beschreibung | Standard |
| ------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `visitor_code` (*erforderlich*) | `String.t()` | Eindeutiger Bezeichner des Besuchers. | |
| `goal_id` (*erforderlich*) | `non_neg_integer()` | ID des Ziels. | |
| `revenue` (*optional*) | `number() \| nil` | Umsatz der Konvertierung. | `0` |
| `negative` (*optional*) | `boolean()` | Definiert, ob der Umsatz positiv oder negativ ist. | `false` |
| `metadata` (*optional*) | `[Kameleoon.Data.CustomData.t()]` | Metadaten der Konvertierung. [Muss zuvor in der Kameleoon-App definiert sein](/de/user-manual/assets/goals/create-a-goal#metadaten). | `[]` |
Metadatenwerte 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` angegeben wird, verwendet Kameleoon diese angegebenen Werte für die aktuelle Konvertierung anstelle der zuvor mit der Methode [`Client.add_data`](#add_data) erfassten Werte. Wenn der Parameter weggelassen wird, verwendet Kameleoon die zuletzt getrackten Werte für diese [`CustomData`](#customdata) vor der Konvertierung und innerhalb desselben Besuchs.
Kameleoon berücksichtigt nur die Metadatenwerte, die explizit als Parameter an die Methode `Client.track_conversion` übergeben werden.
Im folgenden Beispiel verknüpft Kameleoon die Konvertierung nur mit dem benutzerdefinierten Datenwert, der explizit als Parameter angegeben wurde (hier: Index 5 mit dem Wert „Amex Credit Card“).
```elixir theme={null}
:ok =
Client.add_data(client, visitor_code, [
CustomData.new!(5, ["Credit Card"]),
CustomData.new!(9, ["Express Delivery"])
])
:ok =
Client.track_conversion(
client,
visitor_code,
goal_id,
metadata: [CustomData.new!(5, ["Amex Credit Card"])]
)
```
##### Rückgabewert
| Typ | Beschreibung | |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Gibt an, ob die Konvertierung erfolgreich für das asynchrone Tracking in die Warteschlange gestellt wurde, andernfalls einen Fehler. |
##### Fehler
| Typ | Beschreibung |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Gibt an, dass das SDK noch nicht vollständig initialisiert ist. |
| `VisitorCodeInvalid` | Ausnahme, die angibt, dass der angegebene Visitor Code ungültig ist. Er ist entweder leer oder länger als 255 Zeichen. |
#### get\_engine\_tracking\_code()
Kameleoon ist mit mehreren Analyselösungen integriert, darunter Mixpanel, Google Analytics 4 und Segment. Um serverseitige Experimente korrekt zu tracken, rufen Sie die Methode `Client.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 Expositionsereignisse über die aktive Analyseintegration.
Weitere Informationen zur Implementierung dieser Methode finden Sie unter [Hybride Experimente](/developer-docs/feature-experimentation/get-started/hybrid-experimentation).
```elixir theme={null}
{:ok, tracking_code} = Kameleoon.Client.get_engine_tracking_code(client, visitor_code)
```
* Um diese Funktion zu nutzen, implementieren Sie sowohl das Elixir SDK als auch Kameleoon [Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation). Da Engine.js in diesem Ablauf nur für das Tracking verwendet wird, können Sie das asynchrone Tag vor dem schließenden ``-Tag einbinden.
* Wenn Sie nur Experimente in Kameleoon tracken möchten und keine Expositionsereignisse 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 trackt Variationen automatisch, wenn Sie [`getVisitorCode`](/developer-docs/sdks/web-sdks/js-sdk#getvisitorcode) aufrufen, sofern Sie die entsprechenden Experimentzuweisungen zu `window.kameleoonQueue` hinzufügen.
* Sie können den zurückgegebenen Tracking-Code direkt in ein HTML-`