> ## 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.
# SDK Elixir
> Intégrez le SDK Elixir de Kameleoon pour exécuter des expériences et activer des feature flags dans vos services et back-ends web Elixir.
Avec le SDK Elixir de Kameleoon, vous pouvez exécuter des expériences et activer des feature flags dans vos services et back-ends web Elixir.
**Pour commencer** : Pour obtenir de l'aide pour démarrer, consultez le [guide du développeur](#guide-du-développeur).
**Version** : Dernière version du SDK Elixir : 0.8.6 [Changelog](https://docs.kameleoon.com/developer-docs/sdks/web-sdks/elixir-sdk).
**Méthodes du SDK** : Pour la documentation complète de référence du SDK Elixir, consultez la section [référence](#référence).
## Guide du développeur
Ce guide est conçu pour vous aider à intégrer rapidement le SDK Elixir et à commencer à évaluer des feature flags dans votre application Elixir.
### Pour commencer
#### Installer le client Elixir
Ajoutez le SDK comme dépendance dans votre fichier `mix.exs` :
```elixir title="mix.exs" theme={null}
def deps do
[
{:kameleoon_client, "~> 0.8.6"}
]
end
```
#### Configuration supplémentaire
Créez un fichier de configuration `client-elixir.conf` pour fournir les identifiants et personnaliser le comportement du SDK.
Nous recommandons d'enregistrer ce fichier au chemin par défaut, `/etc/kameleoon/client-elixir.conf`. `Kameleoon.ClientFactory.create` utilise automatiquement ce chemin lorsque vous ne transmettez pas d'options de configuration. Si vous stockez le fichier ailleurs, indiquez le chemin avec l'option `config_path:` lors de la création du client.
Le SDK Elixir peut être configuré soit avec un fichier de configuration utilisé par `Kameleoon.ClientFactory.create`, soit en passant une structure `%Kameleoon.ClientConfig\{\}` avec l'option `config:`.
Le tableau suivant présente les propriétés disponibles que vous pouvez définir :
| Clé (Code / Fichier de configuration) | Description | Valeur par défaut |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| `client_id` / `clientId` (*obligatoire*) | Requis pour l'authentification au service Kameleoon. Pour trouver votre `client_id`, consultez la documentation [API credentials](/user-manual/account-and-team-management/users-and-teams/api-credentials). | |
| `client_secret` / `clientSecret` (*obligatoire*) | Requis pour l'authentification au service Kameleoon. Pour trouver votre `client_secret`, consultez la documentation [API credentials](/user-manual/account-and-team-management/users-and-teams/api-credentials). | |
| `session_duration_minutes` / `sessionDurationMinutes` (*optionnel*) | Intervalle de temps, en minutes, pendant lequel le SDK conserve un visiteur et ses données associées en mémoire. | `30` minutes |
| `refresh_interval_minutes` / `refreshIntervalMinutes` (*optionnel*) | Intervalle, en minutes, utilisé pour rafraîchir la configuration des expériences actives et des feature flags. | `60` minutes |
| `default_timeout_millis` / `defaultTimeoutMillis` (*optionnel*) | Délai d'attente par défaut, en millisecondes, pour les requêtes réseau du SDK. | `10000` millisecondes |
| `tracking_interval_millis` / `trackingIntervalMillis` (*optionnel*) | Intervalle, en millisecondes, utilisé pour regrouper les requêtes de tracking. Les valeurs sont limitées à la plage `[1000, 5000]`. | `1000` millisecondes |
| `environment` / `environment` (*optionnel*) | Environnement à partir duquel la configuration du feature flag doit être utilisée. La valeur peut être `production`, `staging` ou `development`. | `production` |
| `top_level_domain` / `topLevelDomain` (*optionnel*) | Le domaine de premier niveau actuel pour votre site web. Utilisez le format `example.com` sans protocole ni sous-domaines. | `nil` |
| `proxy_host` / `proxyHost` (*optionnel*) | Hôte proxy pour les appels sortants du SDK. Formats pris en charge : `https://my.prox`, `https://my.prox:4545`, `socks5://192.168.1.1:9000`. | `nil` |
| `network_domain` / `networkDomain` (*optionnel*) | Domaine personnalisé utilisé par les SDK pour les requêtes sortantes, souvent pour le proxy. Doit être un domaine valide (par exemple, example.com ou sub.example.com). Les formats invalides utilisent la valeur par défaut de Kameleoon. | `nil` |
#### Initialiser le client Kameleoon
Une fois que vous avez installé le SDK et configuré vos identifiants, créez un `%Kameleoon.Client\{\}` en utilisant `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)
```
Un `%Kameleoon.Client\{\}` est l'objet principal utilisé pour évaluer les feature flags, ajouter des données de visiteur et envoyer des requêtes de tracking.
* Il est recommandé d'utiliser `%Kameleoon.Client\{\}` comme un objet singleton, car il sert de pont entre votre application et la plateforme Kameleoon. Il expose toutes les méthodes et propriétés requises pour exécuter efficacement vos expériences.
* Le SDK Elixir s'initialise via le Core natif. Vous devez appeler [`initialize()`](#initialize) avant de vous appuyer sur l'évaluation des fonctionnalités dans du code de production.
#### Activation d'un feature flag
##### Attribution d'un identifiant unique à un utilisateur
Pour attribuer un identifiant unique à un utilisateur, vous pouvez utiliser la méthode [`Client.get_visitor_code`](#get_visitor_code). Si un **visitor code** n'existe pas (à partir du cookie des en-têtes de requête), la méthode génère un identifiant unique aléatoire ou utilise un `default_visitor_code` que vous auriez généré. L'identifiant est ensuite défini dans un cookie des en-têtes de réponse.
Si vous utilisez Kameleoon en [mode hybride](/developer-docs/feature-experimentation/get-started/hybrid-experimentation), l'appel à la méthode `Client.get_visitor_code` garantit que l'identifiant unique (**visitor code**) est partagé entre le fichier d'application `engine.js` (anciennement nommé `kameleoon.js`) et le SDK.
##### Récupération de la configuration d'un flag
Pour implémenter un feature flag dans votre code, vous devez d'abord créer le feature flag dans votre compte Kameleoon.
Pour déterminer le statut ou la variation d'un feature flag pour un utilisateur spécifique, vous devez utiliser la méthode [`Client.get_variation`](#get_variation) ou [`Client.is_feature_active?`](#is_feature_active) afin de récupérer la configuration en fonction de la `feature_key`.
La méthode `Client.get_variation` gère à la fois les feature flags simples avec des états ON/OFF et les flags plus complexes avec plusieurs variations. La méthode récupère la variation appropriée pour l'utilisateur en vérifiant les règles du feature, en attribuant la variation et en la renvoyant en fonction de la `feature_key` et du `visitor_code`.
La méthode `Client.is_feature_active?` peut être utilisée si vous souhaitez récupérer la configuration d'un feature flag simple qui n'a qu'un état ON ou OFF, par opposition à des feature flags plus complexes avec plusieurs variations ou options de ciblage.
Si votre feature flag est associé à des variables (telles que des comportements spécifiques liés à chaque variation), `Client.get_variation` vous permet également d'accéder à l'objet [`Variation`](#variation), qui fournit des détails sur la variation attribuée et son expérience associée. Cette méthode vérifie si l'utilisateur est ciblé, trouve la variation attribuée au visiteur et l'enregistre dans le stockage. Lorsque `track=true`, le SDK enverra l'événement d'exposition à l'expérience spécifiée lors de la prochaine requête de tracking, qui est automatiquement déclenchée en fonction du paramètre [`tracking_interval_millis`](#configuration-supplémentaire) du SDK. Par défaut, cet intervalle est défini à 1000 millisecondes (1 seconde).
La méthode `Client.get_variation` vous permet de contrôler si le tracking est effectué. Si `track=false`, aucun événement d'exposition ne sera envoyé par le SDK. Cela est utile si vous préférez ne pas suivre les données via le SDK et plutôt vous appuyer sur le tracking côté client géré par le moteur Kameleoon, par exemple. De plus, définir `track=false` est utile lors de l'utilisation de la méthode `Client.get_variations`, où vous pourriez n'avoir besoin que des variations de tous les flags sans déclencher d'événements de tracking. Si vous souhaitez en savoir plus sur le fonctionnement du tracking, consultez [cet article](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics).
##### Ajout de points de données pour cibler un utilisateur ou filtrer / découper les visites dans les rapports
Pour cibler un utilisateur, assurez-vous d'avoir ajouté les points de données pertinents à son profil avant de récupérer la variation du feature ou de vérifier si le flag est actif. Utilisez la méthode [`Client.add_data`](#add_data) pour ajouter ces points de données au profil de l'utilisateur.
Pour récupérer les points de données collectés sur d'autres appareils ou pour accéder aux données passées de l'utilisateur (collectées côté client lors de l'utilisation de Kameleoon en mode hybride), utilisez la méthode [`Client.get_remote_visitor_data`](#get_remote_visitor_data). Cette méthode récupère les données depuis les serveurs de manière asynchrone. Il est important d'appeler `Client.get_remote_visitor_data` *avant* de récupérer la variation ou de vérifier si le feature flag est actif, car ces données peuvent être nécessaires pour attribuer un utilisateur à une variation donnée.
Pour en savoir plus sur les conditions de ciblage disponibles, consultez [l'article détaillé à ce sujet](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
De plus, les points de données que vous ajoutez au profil du visiteur seront disponibles lors de l'analyse de vos expériences, vous permettant de filtrer et de découper vos résultats par facteurs tels que l'appareil et le navigateur. Le mode hybride de Kameleoon collecte automatiquement une variété de points de données côté client, ce qui facilite la décomposition de vos résultats en fonction de ces points de données pré-collectés. Consultez la liste complète [ici](/fr/user-manual/experiment-analytics/analyze-results/results-page/results-page-settings#ventiler-l’audience).
Si vous devez suivre des points de données supplémentaires au-delà de ceux collectés automatiquement, vous pouvez utiliser la fonctionnalité [Custom Data](#customdata) de Kameleoon. Les Custom Data vous permettent de capturer et d'analyser des informations spécifiques pertinentes pour vos expériences. N'oubliez pas d'appeler la méthode [`Client.flush`](#flush) pour envoyer les données collectées aux serveurs Kameleoon pour analyse.
Pour garantir l'exactitude de vos résultats, il est recommandé de filtrer les bots à l'aide du type de données [`UserAgent`](#useragent).
##### Suivi des conversions d'objectifs
Lorsqu'un utilisateur effectue une action souhaitée (telle qu'un achat), elle est enregistrée comme une conversion. Pour suivre les conversions, utilisez la méthode [`Client.track_conversion`](#track_conversion) et fournissez les paramètres `visitor_code` et `goal_id` requis.
La requête de suivi de conversion sera envoyée avec la prochaine requête de tracking planifiée, que le SDK envoie à intervalles réguliers (définis par [`tracking_interval_millis`](#configuration-supplémentaire)). Si vous préférez envoyer la requête immédiatement, utilisez la méthode [`Client.flush_instant`](#flush).
##### Envoi d'événements aux solutions d'analyse
Pour suivre les conversions et envoyer des événements d'exposition à votre solution d'analyse client, vous devez d'abord implémenter Kameleoon en [mode hybride](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/). Ensuite, utilisez la méthode [`Client.get_engine_tracking_code`](#get_engine_tracking_code).
La méthode `Client.get_engine_tracking_code` récupère le code de tracking unique requis pour envoyer des événements d'exposition à votre solution d'analyse. L'utilisation de cette méthode vous permet d'enregistrer les événements et de les envoyer à la plateforme d'analyse de votre choix.
### Utilisation d'une clé de bucketing personnalisée
Par défaut, Kameleoon utilise un identifiant de visiteur anonyme unique (`visitor_code`) pour attribuer les utilisateurs aux variations des feature flags. Cet identifiant est généralement généré et stocké sur l'appareil de l'utilisateur (dans un cookie de navigateur pour les SDK côté client et côté serveur — dans un stockage persistant pour les SDK mobiles). Cependant, dans certains scénarios, vous pouvez avoir besoin de garantir que tous les utilisateurs d'une même organisation voient la même variante d'un feature flag.
L'option **Clé de bucketing personnalisée** vous permet de remplacer ce comportement par défaut en fournissant votre propre identifiant personnalisé pour le bucketing. Ce remplacement garantit que la logique d'attribution de Kameleoon utilise la clé que vous avez spécifiée au lieu du `visitor_code` par défaut.
#### Cas d'usage
L'utilisation d'une clé de bucketing personnalisée est essentielle pour maintenir la cohérence et l'exactitude de vos attributions de feature flags, en particulier dans les situations suivantes :
* **Expériences au niveau du compte ou de l'organisation :** Pour les produits B2B ou les scénarios où vous souhaitez attribuer tous les utilisateurs d'une même organisation à la même variation, vous pouvez utiliser un identifiant tel qu'un `account_id`. Les clés de bucketing personnalisées sont cruciales pour les tests A/B de fonctionnalités qui impactent toute une équipe ou une entreprise.
En implémentant une clé de bucketing personnalisée, vous garantissez une cohérence et une exactitude accrues dans vos expériences, ce qui conduit à des résultats plus fiables et à une meilleure expérience utilisateur.
#### Détails techniques
Lorsque vous configurez une clé de bucketing personnalisée pour un feature flag, vous fournissez à Kameleoon un identifiant spécifique provenant des données de votre application :
```elixir theme={null}
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
:ok = Client.add_data(client, visitor_code, CustomData.new!(42, ["new_visitor_code"]))
```
* **Fournir la clé personnalisée :** Vous fournissez votre identifiant personnalisé au SDK Kameleoon en utilisant la méthode [`Client.add_data`](#add_data). Dans cette méthode, vous passerez votre clé de bucketing personnalisée choisie sous la forme d'un objet [`CustomData`](#customdata). Ici, `new_visitor_code` fait référence à l'identifiant que vous souhaitez utiliser pour votre bucketing (par exemple, le nouveau `user_id` ou `account_id`).
Pour que la clé de bucketing personnalisée fonctionne correctement, elle doit également être définie et configurée pour le feature flag lors du processus de création ou de modification du flag. Sans cette configuration correspondante, le bucketing du SDK n'appliquera pas votre clé personnalisée. Pour des instructions détaillées sur la façon de configurer cela dans Kameleoon, consultez cet [article](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag#Advanced_Flag_Settings).
* **Logique de bucketing :** Une fois qu'une clé de bucketing personnalisée est fournie via la méthode `Client.add_data`, tous les calculs de hachage pour attribuer les utilisateurs aux variations utiliseront ce `new_visitor_code` (votre clé personnalisée) au lieu du `visitor_code` par défaut. L'utilisation du `new_visitor_code` signifie que la décision de bucketing est liée à votre identifiant personnalisé, garantissant des attributions cohérentes dans divers contextes où cet identifiant est présent.
* **Suivi des données et analyse :** Il est crucial de noter que, bien que le `new_visitor_code` (votre clé personnalisée) soit utilisé pour les décisions de bucketing, **toutes les données ultérieures (événements de tracking et conversions, par exemple) sont envoyées et associées au `visitor_code` *d'origine*.** Cette séparation garantit que vos analyses reflètent avec précision les parcours et interactions individuels des utilisateurs dans le contexte plus large de votre expérience, même lorsque le bucketing est effectué à un niveau supérieur (comme un compte) ou sur plusieurs appareils/sessions. Vos données originales de visiteur restent intactes pour un reporting complet.
#### Exigences techniques
Pour utiliser efficacement une clé de bucketing personnalisée :
* La clé doit être un `String.t()`.
* Elle doit être unique pour l'entité que vous souhaitez bucketer (par exemple, si vous utilisez un `user_id`, l'identifiant de chaque utilisateur doit être unique).
* La clé doit être disponible pour le SDK au moment exact où la décision du feature flag est évaluée pour cet utilisateur ou cette requête.
### Conditions de ciblage
Les SDK Kameleoon prennent en charge une variété de conditions de ciblage prédéfinies que vous pouvez utiliser pour cibler les utilisateurs dans vos campagnes. Pour la liste des conditions prises en charge par ce SDK, consultez [utiliser l'historique de visite pour cibler les utilisateurs](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
Vous pouvez également utiliser vos propres [données externes pour cibler les utilisateurs](/developer-docs/apis/data-api-rest/tutorials/storing-and-retrieving-external-data-to-target-users).
### Expérimentation cross-device
Pour prendre en charge les visiteurs qui accèdent à une application depuis plusieurs appareils, Kameleoon permet la synchronisation des données de visiteur précédemment collectées sur chacun des appareils du visiteur, ainsi que la réconciliation de leur historique de visite sur tous les appareils grâce à l'expérimentation cross-device. Des études de cas et des informations détaillées sur la façon dont Kameleoon gère les données entre les appareils sont disponibles dans l'[article sur l'expérimentation cross-device](/developer-docs/cross-device-experimentation).
#### Synchronisation des données personnalisées entre les appareils
Bien que la synchronisation par mappage personnalisé soit utilisée pour aligner les données de visiteur entre les appareils, elle n'est pas toujours nécessaire. Voici deux scénarios où la synchronisation par mappage personnalisé n'est pas requise :
**Même ID utilisateur sur tous les appareils**
Si le même ID utilisateur est utilisé de manière cohérente sur tous les appareils, la synchronisation est gérée automatiquement sans synchronisation par mappage personnalisé. Il suffit d'appeler la méthode `Client.get_remote_visitor_data` lorsque vous souhaitez synchroniser les données collectées entre plusieurs appareils.
**Instances multi-serveurs avec identifiants cohérents**
Dans des configurations complexes impliquant plusieurs serveurs (par exemple, des instances de serveurs distribués), où le même ID utilisateur est disponible sur tous les serveurs, la synchronisation entre les serveurs (avec `Client.get_remote_visitor_data`) est suffisante sans synchronisation par mappage personnalisé supplémentaire.
Les clients qui ont besoin de données supplémentaires peuvent se référer à la description de la méthode [`Client.get_remote_visitor_data`](#get_remote_visitor_data) pour plus d'informations. Dans le code ci-dessous, on suppose que le même identifiant unique (dans ce cas, le `visitor_code`, également appelé `userId`) est utilisé de manière cohérente entre les deux appareils pour une récupération précise des données.
Si vous souhaitez synchroniser les données collectées en temps réel, vous devez choisir le scope **Visitor** pour vos données personnalisées.
```elixir title="Appareil A" theme={null}
# Dans cet exemple, une Custom Data avec l'index `90` a été définie sur le scope "Visitor" dans 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="Appareil B" theme={null}
# Avant de travailler avec les données, appelez la méthode `get_remote_visitor_data`.
:ok = Client.get_remote_visitor_data(client, visitor_code)
# Après avoir appelé la méthode, le SDK sur l'Appareil B aura accès aux CustomData de scope Visitor définies sur l'Appareil A.
# Ainsi, "your data" sera disponible pour le ciblage et le suivi du visiteur.
```
#### Utilisation de données personnalisées pour la fusion de sessions
L'[expérimentation cross-device](/developer-docs/cross-device-experimentation) permet de combiner l'historique d'un visiteur sur chacun de ses appareils (réconciliation d'historique). La réconciliation d'historique permet de fusionner différentes sessions de visiteur en une seule. Pour réconcilier l'historique des visites, utilisez [`CustomData`](#customdata) pour fournir un identifiant unique pour le visiteur. Pour plus d'informations, consultez la [documentation dédiée](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation).
Une fois la réconciliation cross-device activée, l'appel à [`Client.get_remote_visitor_data`](#get_remote_visitor_data) avec le paramètre `userId` récupère toutes les données connues pour un utilisateur donné.
Les sessions avec le même identifiant verront toujours la même variation dans une expérience. Dans la vue Visiteur des pages de résultats de votre expérience, ces sessions apparaîtront comme un visiteur unique.
La configuration du SDK garantit que les sessions associées voient toujours la même variation de l'expérience. Cependant, il existe certaines limitations concernant l'attribution de variations cross-device. Ces limitations sont décrites [ici](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights).
Suivez le guide [activation de la réconciliation d'historique cross-device](#expérimentation-cross-device) pour configurer vos données personnalisées sur la plateforme Kameleoon.
Ensuite, vous pouvez utiliser le SDK normalement. Les méthodes suivantes peuvent être utiles dans le contexte de la fusion de sessions :
* `Client.get_remote_visitor_data` avec `UniqueIdentifier(true)` ajouté - pour récupérer les données de tous les visiteurs liés.
* [`Client.track_conversion`](#track_conversion) ou [`Client.flush`](#flush) avec la donnée `UniqueIdentifier(true)` ajoutée - pour suivre certaines données pour un visiteur spécifique qui est associé à un autre visiteur.
Comme la donnée personnalisée que vous utilisez comme identifiant doit être définie sur le **scope Visitor**, vous devez utiliser la [synchronisation des données personnalisées cross-device](/developer-docs/cross-device-experimentation) pour récupérer l'identifiant avec la méthode [`Client.get_remote_visitor_data`](#get_remote_visitor_data) sur chaque appareil.
Voici un exemple d'utilisation de données personnalisées pour la fusion de sessions.
```elixir theme={null}
# Dans cet exemple, 91 représente l'index de la Custom Data configurée comme identifiant unique dans 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. Avant l'authentification du visiteur
# Récupérer la variation pour un visiteur non authentifié.
# On suppose que anonymousVisitorCode est l'ID généré aléatoirement pour ce visiteur.
{:ok, anonymous_variation} = Client.get_variation(client, anonymous_visitor_code, feature_key)
# 2. Après l'authentification du visiteur
# On suppose que `userId` est le code visiteur du visiteur authentifié.
:ok = Client.add_data(client, anonymous_visitor_code, CustomData.new!(mapping_index, [user_id]))
:ok = Client.flush_instant(client, anonymous_visitor_code)
# Indiquer que `userId` est un identifiant unique.
:ok = Client.add_data(client, user_id, UniqueIdentifier.new!(true))
# 3. Après l'autorisation du visiteur
# Récupérer la variation pour le `userId`, qui correspondra à la variation du code visiteur anonyme.
{:ok, user_variation} = Client.get_variation(client, user_id, feature_key)
is_same_variation = user_variation.key == anonymous_variation.key # true
# `userId` et `anonymousVisitorCode` sont désormais liés et peuvent être suivis comme un seul visiteur.
:ok = Client.track_conversion(client, user_id, 123)
# De plus, les visiteurs liés partagent toutes les données distantes précédemment suivies et récupérées.
:ok = Client.get_remote_visitor_data(client, user_id)
```
Dans cet exemple, l'application dispose d'une page de connexion. Comme l'ID utilisateur est inconnu au moment de la connexion, un identifiant de visiteur anonyme généré par la méthode [`Client.get_visitor_code`](#get_visitor_code) est utilisé. Après la connexion de l'utilisateur, le visiteur anonyme est associé à l'ID utilisateur et utilisé comme identifiant unique pour le visiteur.
### Journalisation
Le SDK génère des logs pour refléter les différents processus et problèmes internes.
#### Niveaux de log
Le SDK prend en charge la limitation de la journalisation par niveau de log.
```elixir theme={null}
alias Kameleoon.Logger
# Le niveau de log `:none` désactive la journalisation.
:ok = Logger.set_log_level(:none)
# Le niveau de log `:error` permet uniquement de journaliser les problèmes susceptibles d'affecter le comportement principal du SDK.
:ok = Logger.set_log_level(:error)
# Le niveau de log `:warning` permet de journaliser les problèmes nécessitant une attention.
# Il étend le niveau de log `:error`.
# Le niveau de log `:warning` est le niveau par défaut.
:ok = Logger.set_log_level(:warning)
# Le niveau de log `:info` permet de journaliser des informations générales sur les processus internes du SDK.
# Il étend le niveau de log `:warning`.
:ok = Logger.set_log_level(:info)
# Le niveau `:debug` consigne des détails supplémentaires sur les processus internes du SDK.
:ok = Logger.set_log_level(:debug)
```
#### Gestion personnalisée des logs
Le SDK écrit ses logs sur la sortie console par défaut. Ce comportement peut être remplacé.
La limitation de la journalisation par niveau de log est effectuée indépendamment de la logique de gestion des logs.
```elixir theme={null}
defmodule MyKameleoonLogger do
@behaviour Kameleoon.Logger
require Logger
@impl true
def log(level, message) do
Logger.log(level, message)
end
end
# Le filtrage par niveau de log est appliqué séparément de la logique de gestion des logs.
# Le logger personnalisé n'acceptera que les logs qui correspondent ou dépassent le niveau de log spécifié.
:ok = Kameleoon.Logger.set_log_level(:debug)
:ok = Kameleoon.Logger.set_logger(MyKameleoonLogger)
```
## Référence
Voici la documentation complète de référence pour le SDK Elixir.
### Initialisation
#### create()
Pour utiliser le SDK, créez un `%Kameleoon.Client\{\}` avec `Kameleoon.ClientFactory.create`. Par défaut, `create` lit `/etc/kameleoon/client-elixir.conf`. Vous pouvez également fournir soit une structure `%Kameleoon.ClientConfig\{\}` via `config:`, soit un chemin de fichier de configuration personnalisé via `config_path:`.
```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)
```
##### Arguments
| Nom | Type | Description |
| --------------------------- | ---------------------------- | --------------------------------------------------- |
| `site_code` (*obligatoire*) | `String.t()` | Clé unique du projet Kameleoon utilisée par le SDK. |
| `config` (*obligatoire*) | `Kameleoon.ClientConfig.t()` | Structure de configuration du SDK. |
```elixir theme={null}
alias Kameleoon.ClientFactory
{:ok, client} = ClientFactory.create("a8st4f59bj", config_path: "/etc/kameleoon/client-elixir.conf")
```
##### Arguments
| Nom | Type | Description |
| ----------------------------- | ------------ | --------------------------------------------------- |
| `site_code` (*obligatoire*) | `String.t()` | Clé unique du projet Kameleoon utilisée par le SDK. |
| `config_path` (*obligatoire*) | `String.t()` | Chemin vers le fichier de configuration. |
##### Valeur retournée
| Type | Description | |
| ------------------------------ | -------------------------------- | --------------------------------------------------------------------------- |
| \`\{:ok, Kameleoon.Client.t()} | \{:error, Kameleoon.Error.t()}\` | Une instance du client en cas de succès, sinon une erreur d'initialisation. |
##### Erreurs
| Type | Description |
| -------------------------- | --------------------------------------- |
| `ConfigCredentialsInvalid` | Les identifiants du SDK sont manquants. |
| `SiteCodeIsEmpty` | Le site code fourni est vide. |
#### initialize()
Attend que le client Kameleoon soit initialisé, en utilisant soit la valeur configurée [`default_timeout_millis`](#configuration-supplémentaire), soit un `timeout` fourni. Cette méthode garantit que le client est entièrement initialisé avant d'effectuer toute autre opération.
```elixir theme={null}
alias Kameleoon.Client
# Initialise le client en utilisant le délai d'attente par défaut configuré
:ok = Client.initialize(client)
# Initialise le client avec un délai d'attente personnalisé de 5 secondes
:ok = Client.initialize(client, timeout: 5_000)
```
##### Arguments
| Nom | Type | Description |
| ----------------------- | ------------------- | ---------------------------------------------------------------- |
| `timeout` (*optionnel*) | `non_neg_integer()` | Temps maximal d'attente pour l'initialisation, en millisecondes. |
##### Valeur retournée
| Type | Description | |
| ----- | -------------------------------- | --------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Indique si l'initialisation s'est terminée avec succès ou si une erreur s'est produite. |
##### Erreurs
| Type | Description |
| ---------------- | ----------------------------------------------------------- |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
#### is\_ready()
Vérifie si le client a été initialisé.
```elixir theme={null}
{:ok, ready?} = Kameleoon.Client.is_ready?(client)
if ready? do
# Le client est prêt
end
```
##### Valeur retournée
| Type | Description | |
| ------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| \`\{:ok, boolean()} | \{:error, Kameleoon.Error.t()}\` | `\{:ok, true\}` si le client est prêt à être utilisé, `\{:ok, false\}` s'il n'est pas prêt, sinon une erreur. |
#### forget()
Supprime le client SDK mis en cache associé au `site_code` spécifié.
```elixir theme={null}
alias Kameleoon.ClientFactory
# Supprime le client mis en cache pour le site code donné
:ok = ClientFactory.forget("a8st4f59bj")
# Supprime le client mis en cache pour le site code et l'environnement donnés
:ok = ClientFactory.forget("a8st4f59bj", environment: "production")
```
##### Arguments
| Nom | Type | Description |
| --------------------------- | ------------ | ---------------------------------------------------- |
| `site_code` (*obligatoire*) | `String.t()` | Identifiant unique du projet Kameleoon. |
| `environment` (*optionnel*) | `String.t()` | Clé d'environnement associée au client mis en cache. |
##### Valeur retournée
| Type | Description | |
| ----- | -------------------------------- | ---------------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Indique si le client mis en cache a été correctement supprimé ou si une erreur s'est produite. |
### Feature flags et variations
#### is\_feature\_active()
* 📨 *Envoie des données de tracking à Kameleoon (selon l'option `track`)*
Détermine si un feature flag est actif pour un utilisateur donné.
Si le visiteur n'a pas encore été évalué pour ce feature flag, le SDK évalue les règles de ciblage et renvoie le résultat. Si le visiteur dispose déjà d'une évaluation stockée pour le feature, le SDK réutilise le résultat existant pour garantir la cohérence.
Kameleoon utilise le tracking pour compter les sessions et les visiteurs lorsque vous appelez certaines méthodes, telles que `Client.is_feature_active?`, `Client.get_variation` ou `Client.get_variations`.
Utilisez la valeur par défaut `true` pour le paramètre `track` lorsque vous exposez les visiteurs à une variation et devez les compter. Définissez le paramètre `track` sur `false` uniquement si vous appelez ces méthodes avant d'exposer les visiteurs.
Par exemple, si vous appelez `Client.get_variations` pour récupérer toutes les variations avant d'exposer les visiteurs, définissez le paramètre `track` sur `false`. Ce paramètre empêche Kameleoon de comptabiliser prématurément une session. Vous pouvez ensuite déclencher le tracking ultérieurement lorsque vous exposez explicitement le visiteur.
Kameleoon envoie les données de tracking chaque seconde par défaut. Vous pouvez configurer cet intervalle jusqu'à cinq secondes à l'aide de l'option de configuration de l'intervalle de tracking. Kameleoon regroupe les événements de tracking dans une seule session tant que l'intervalle entre les événements est inférieur à 30 minutes. Si plus de 30 minutes s'écoulent entre les événements de tracking, Kameleoon comptabilise les événements comme des sessions distinctes. Une visite apparaît dans vos rapports 30 minutes après le dernier événement enregistré dans la session.
La méthode `Client.is_feature_active?` évalue la variante servie, et non l'état du master flag. Si vous excluez des règles, la méthode utilise l'état par défaut **Then, for everyone else serve**. Si vous sélectionnez **Off** pour cet état par défaut, la méthode renvoie toujours `false` même lorsque le master feature flag est sur **On**.
```elixir theme={null}
alias Kameleoon.Client
feature_key = "new_checkout"
# Évalue le feature flag et envoie les données de tracking (comportement par défaut)
{:ok, active?} = Client.is_feature_active?(client, visitor_code, feature_key)
# Évalue le feature flag sans envoyer de données de tracking
{:ok, active_without_tracking?} =
Client.is_feature_active?(client, visitor_code, feature_key, track: false)
```
##### Arguments
| Nom | Type | Description | Par défaut |
| ------------------------------ | ------------ | -------------------------------------------------------- | ---------- |
| `visitor_code` (*obligatoire*) | `String.t()` | Identifiant unique de l'utilisateur. | |
| `feature_key` (*obligatoire*) | `String.t()` | Clé du feature à évaluer pour l'utilisateur. | |
| `track` (*optionnel*) | `boolean()` | Active ou désactive le suivi de l'évaluation du feature. | `true` |
##### Valeur retournée
| Type | Description | |
| ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- |
| \`\{:ok, boolean()} | \{:error, Kameleoon.Error.t()}\` | Indique si le feature flag est actif pour le `visitor_code` spécifié, ou renvoie une erreur. |
##### Erreurs
| Type | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `FeatureNotFound` | Exception indiquant que la clé du feature demandée est introuvable dans la configuration interne du SDK. Cela signifie généralement que le feature flag n'est pas activé dans l'application Kameleoon (mais que le code implémentant le feature est déjà déployé dans l'application). |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
#### get\_variation()
* 📨 *Envoie des données de tracking à Kameleoon (selon le paramètre `track`)*
Récupère la [`Variation`](#variation) attribuée à un visiteur donné pour un feature flag spécifique.
Cette méthode prend un `visitor_code` et une `feature_key` comme arguments obligatoires. L'argument `track` est optionnel et vaut `true` par défaut.
Elle renvoie la `Variation` attribuée au visiteur. Si le visiteur n'est associé à aucune règle de feature flag, la méthode renvoie la `Variation` par défaut pour le feature flag donné.
Assurez-vous qu'une gestion appropriée des erreurs est implémentée dans votre code pour gérer les exceptions potentielles.
La variation par défaut désigne la variation attribuée à un visiteur lorsqu'il ne correspond à aucune règle de livraison prédéfinie pour un feature flag. En d'autres termes, il s'agit de la variation de repli appliquée à tous les utilisateurs qui ne sont pas ciblés par des règles spécifiques. Elle est représentée comme la variation dans la section « Then, for everyone else... » d'une interface de gestion.
```elixir theme={null}
alias Kameleoon.Client
feature_key = "new_checkout"
# Récupère la variation attribuée au visiteur (avec le tracking activé par défaut)
{:ok, variation} = Client.get_variation(client, visitor_code, feature_key)
# Récupère la variation sans envoyer de données de tracking
{:ok, variation_without_tracking} =
Client.get_variation(client, visitor_code, feature_key, track: false)
```
##### Arguments
| Nom | Type | Description | Par défaut |
| ----------------------------- | ------------ | ----------------------------------------------------------------------------------- | ---------- |
| visitor\_code (*obligatoire*) | `String.t()` | Identifiant unique du visiteur. | |
| feature\_key (*obligatoire*) | `String.t()` | Clé du feature que vous souhaitez exposer à un visiteur. | |
| track (*optionnel*) | `boolean()` | Paramètre optionnel pour activer ou désactiver le suivi de l'évaluation du feature. | `true` |
##### Valeur retournée
| Type | Description |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `\{:ok, Kameleoon.Types.Variation.t()\} \| \{:error, Kameleoon.Error.t()\}` | Une [`Variation`](#variation) attribuée à un visiteur donné pour un feature flag spécifique en cas de succès, sinon une erreur. |
##### Erreurs
| Type | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
| `FeatureNotFound` | Exception indiquant que la clé du feature demandée est introuvable dans la configuration interne du SDK. Cela signifie généralement que le feature flag n'est pas activé dans l'application Kameleoon (mais que le code implémentant le feature est déjà déployé dans l'application). |
| `FeatureEnvironmentDisabled` | Exception indiquant que le feature flag est désactivé pour l'environnement actuel du visiteur (par exemple, production, staging ou development). |
| `FeatureEvaluationBlocked` | Exception indiquant que l'évaluation du feature est bloquée. La raison est décrite dans le message d'erreur. Cela se produit généralement en raison de restrictions RGPD lorsque le visiteur n'a pas fourni de consentement légal. |
#### get\_variations()
* 📨 *Envoie des données de tracking à Kameleoon (selon le paramètre `track`)*
Récupère une map d'objets [`Variation`](#variation) attribués à un visiteur donné pour tous les feature flags.
Cette méthode itère sur tous les feature flags disponibles et renvoie la `Variation` attribuée pour chaque flag associé au visiteur spécifié. Elle prend `visitor_code` comme argument obligatoire, tandis que `only_active` et `track` sont optionnels.
* Si `only_active` est défini sur `true`, la méthode `Client.get_variations` renverra les variations des feature flags à condition que l'utilisateur ne soit pas bucketé avec la variation `off`.
* Le paramètre `track` contrôle si la méthode suivra ou non les attributions de variations. Par défaut, il est défini sur `true`. S'il est défini sur `false`, le tracking sera désactivé.
La map retournée se compose des clés des feature flags en tant que clés et de leurs `Variation` correspondantes en tant que valeurs. Si aucune variation n'est attribuée pour un feature flag, la méthode renvoie la `Variation` par défaut pour ce flag.
Une gestion appropriée des erreurs doit être implémentée pour gérer les exceptions potentielles.
La variation par défaut désigne la variation attribuée à un visiteur lorsqu'il ne correspond à aucune règle de livraison prédéfinie pour un feature flag. En d'autres termes, il s'agit de la variation de repli appliquée à tous les utilisateurs qui ne sont pas ciblés par des règles spécifiques. Elle est représentée comme la variation dans la section « Then, for everyone else... » d'une interface de gestion.
```elixir theme={null}
alias Kameleoon.Client
# Récupère toutes les variations attribuées au visiteur (avec les options par défaut)
{:ok, variations} = Client.get_variations(client, visitor_code)
# Récupère uniquement les variations actives pour le visiteur
{:ok, only_active_variations} = Client.get_variations(client, visitor_code, only_active: true)
# Récupère les variations sans envoyer de données de tracking
{:ok, variations_without_tracking} = Client.get_variations(client, visitor_code, track: false)
```
##### Arguments
| Nom | Type | Description | Par défaut |
| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- | ---------- |
| visitor\_code (*obligatoire*) | `String.t()` | Identifiant unique du visiteur. | |
| only\_active (*optionnel*) | `boolean()` | Paramètre optionnel indiquant s'il faut renvoyer les variations pour les feature flags actifs (`true`) ou tous (`false`). | `false` |
| track (*optionnel*) | `boolean()` | Paramètre optionnel pour activer ou désactiver le suivi de l'évaluation du feature. | `true` |
##### Valeur retournée
| Type | Description |
| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `\{:ok, %\{String.t() => Kameleoon.Types.Variation.t()\}\} \| \{:error, Kameleoon.Error.t()\}` | Map contenant les objets [`Variation`](#variation) attribués des feature flags en utilisant les clés des features correspondants en cas de succès, sinon une erreur. |
##### Erreurs
| Type | Description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
#### set\_forced\_variation()
La méthode vous permet d'attribuer par programmation une [`Variation`](#variation) spécifique à un utilisateur, en contournant le processus d'évaluation standard. Cela est particulièrement précieux pour les expériences contrôlées où la logique d'évaluation habituelle n'est pas requise ou doit être ignorée. Cela peut également être utile dans des scénarios tels que le débogage ou les tests personnalisés.
Lorsqu'une variation **forcée** est définie, elle remplace la logique d'évaluation en temps réel de Kameleoon. Les processus tels que la segmentation, les conditions de ciblage et les calculs algorithmiques sont ignorés. Pour préserver la segmentation et les conditions de ciblage pendant une expérience, définissez plutôt `force_targeting=false`.
Les variations **simulées** ont toujours la priorité dans l'ordre d'exécution. Si un calcul de variation **simulée** est déclenché, il sera entièrement traité et terminé en premier.
Une variation forcée est traitée de la même manière qu'une variation évaluée. Elle est suivie dans les analyses et stockée dans le contexte utilisateur comme toute variation évaluée standard, garantissant la cohérence du reporting.
La méthode peut lever des exceptions dans certaines conditions (par exemple, paramètres invalides, contexte utilisateur ou problèmes internes). Une gestion appropriée des exceptions est essentielle pour garantir que votre application reste stable et résiliente.
Il est important de distinguer les variations **forcées** des variations **[simulées](#get_visitor_code)** :
* **Variations forcées** : Sont spécifiques à une expérience individuelle.
* **Variations simulées** : Affectent le résultat global du **feature flag**.
```elixir theme={null}
alias Kameleoon.Client
experiment_id = 202_387
# Force le visiteur dans "variation_2" pour l'expérience donnée
:ok = Client.set_forced_variation(client, visitor_code, experiment_id, "variation_2")
# Supprime toute variation précédemment forcée pour le visiteur dans cette expérience
:ok = Client.set_forced_variation(client, visitor_code, experiment_id, nil)
# Force le visiteur dans "variation_2" avec des options personnalisées.
# Dans ce cas, les règles de ciblage sont respectées (force_targeting = false).
:ok =
Client.set_forced_variation(
client,
visitor_code,
experiment_id,
"variation_2",
force_targeting: false
)
```
##### Arguments
| Nom | Type | Description | Par défaut |
| ------------------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| visitor\_code (*obligatoire*) | `String.t()` | Identifiant unique du visiteur. | |
| experiment\_id (*obligatoire*) | `non_neg_integer()` | **ID d'expérience** qui sera ciblé et sélectionné lors du processus d'évaluation. | |
| variation\_key (*obligatoire*) | `String.t() \| nil` | **Clé de variation** correspondant à une `Variation` qui doit être forcée comme valeur retournée pour l'expérience. Si la valeur est `nil`, la variation forcée sera réinitialisée. | |
| force\_targeting (*optionnel*) | `boolean()` | Indique si le ciblage de l'expérience doit être forcé et ignoré (`true`) ou appliqué comme dans le processus d'évaluation standard (`false`). | `true` |
##### Valeur retournée
| Type | Description | |
| ----- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Indique si la variation forcée a été définie avec succès ou si une erreur s'est produite. |
##### Erreurs
| Type | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
| `FeatureExperimentNotFound` | Exception indiquant que l'ID d'expérience demandé est introuvable dans la configuration interne du SDK. C'est généralement normal et signifie que l'expérience correspondante de la règle n'a pas encore été activée du côté de Kameleoon. |
| `FeatureVariationNotFound` | Exception indiquant que la clé (id) de variation demandée est introuvable dans la configuration interne du SDK. C'est généralement normal et signifie que l'expérience correspondante de la variation n'a pas encore été activée du côté de Kameleoon. |
#### evaluate\_audiences()
* 📨 *Envoie des données de tracking à Kameleoon*
Cette méthode évalue les visiteurs par rapport à tous les segments Audiences Explorer disponibles et suit ceux qui correspondent.
`Client.evaluate_audiences` doit être appelée **après que toutes les données pertinentes du visiteur ont été définies ou mises à jour**, et **juste avant** d'obtenir une variation de feature ou de vérifier un feature flag. Cette approche garantit que le visiteur est évalué par rapport aux données les plus récentes disponibles, permettant une attribution d'audience précise basée sur tous les critères.
Après avoir appelé cette méthode, vous pouvez effectuer une analyse détaillée des performances des segments dans Audiences Explorer.
```elixir theme={null}
:ok = Kameleoon.Client.evaluate_audiences(client, visitor_code)
```
##### Arguments
| Nom | Type | Description |
| ----------------------------- | ------------ | ------------------------------- |
| visitor\_code (*obligatoire*) | `String.t()` | Identifiant unique du visiteur. |
##### Valeur retournée
| Type | Description | |
| ----- | -------------------------------- | ------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Indique si l'évaluation de l'audience a réussi ou si une erreur s'est produite. |
##### Erreurs
| Type | Description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
#### get\_datafile()
Pour évaluer tous les feature flags, utilisez [`Client.get_variations`](#get_variations). Cette méthode est plus efficace que d'appeler `DataFile` et d'itérer sur les flags avec [`Client.get_variation`](#get_variation).
Renvoie la configuration actuelle du SDK sous forme d'objet [`DataFile`](#datafile).
```elixir theme={null}
{:ok, datafile} = Kameleoon.Client.get_datafile(client)
```
##### Valeur retournée
| Type | Description |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `\{:ok, Kameleoon.Types.DataFile.t()\} \| \{:error, Kameleoon.Error.t()\}` | Le [`DataFile`](#datafile) contenant la configuration du SDK en cas de succès, sinon une erreur. |
##### Erreurs
| Type | Description |
| ---------------- | ----------------------------------------------------------- |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
### Données du visiteur
#### get\_visitor\_code()
Utilisez `get_visitor_code()` pour obtenir le `visitor_code` Kameleoon du visiteur actuel. La méthode fonctionne avec n'importe quel store de cookies qui implémente le behaviour `Kameleoon.CookieAccessor`.
La logique d'implémentation est la suivante :
1. Le SDK vérifie si un cookie `kameleoonVisitorCode` est déjà disponible via l'accessor fourni.
2. Si le cookie est absent, le SDK utilise `default_visitor_code` lorsque vous en fournissez un.
3. Sinon, le SDK génère un nouveau visitor code et le stocke via l'accessor.
Pour plus d'informations, consultez [Expérimentation hybride](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/).
Si vous fournissez votre propre `visitor_code`, son unicité doit être garantie de votre côté. Notez également que la longueur de `visitor_code` est limitée à `255` caractères.
La méthode `Client.get_visitor_code` vous permet de définir des variations **simulées** pour un visiteur. Lorsque les cookies (d'une **requête** ou d'un **document**) contiennent la clé `kameleoonSimulationFFData`, le processus d'évaluation standard est contourné. Au lieu de cela, la méthode renvoie directement une [`Variation`](#variation) basée sur les données fournies.
Vous pouvez appliquer les simulations de deux manières :
* **Automatiquement (recommandé) :** Si vous utilisez Kameleoon Web Experimentation ou le SDK en [mode hybride](/developer-docs/feature-experimentation/get-started/hybrid-experimentation#linking-feature-experiments-with-front-end-tracking-code), le cookie est créé automatiquement lors de la simulation de l'affichage d'une variante via le [Simulation Panel](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode).
* **Manuellement :** Définissez manuellement le cookie `kameleoonSimulationFFData`.
Il est important de distinguer les variations **simulées** des variations **[forcées](#set_forced_variation)** :
* **Variations simulées** : Affectent le résultat global du **feature flag**.
* **Variations forcées** : Sont spécifiques à une expérience individuelle.
⚙️ **Configuration manuelle**
Veuillez vous assurer que le cookie `kameleoonSimulationFFData` suit ce format :
* `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}` : Simule la variation avec `varId` de l'expérience `expId` pour la `featureKey` donnée.
* `kameleoonSimulationFFData={"featureKey":{"expId":0}}` : Simule la variation par défaut (définie dans la section **Then, for everyone else in Production, serve**) pour la `featureKey` donnée.
⚠️ Pour garantir le bon fonctionnement, la valeur du cookie doit être encodée en tant que composant URI à l'aide d'une méthode telle que [`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, %{}}
# Génère ou récupère un visitor code en utilisant une valeur générée automatiquement.
{:ok, visitor_code, cookies} = Kameleoon.Client.get_visitor_code(client, cookies)
# Génère ou récupère un visitor code en utilisant un ID utilisateur prédéfini.
{: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
```
##### Arguments
| Nom | Type | Description | |
| ------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `cookies` (*obligatoire*) | `\{module(), term()\}` | Module accessor de cookies et état spécifique au framework utilisés pour lire et stocker le cookie du visiteur. | |
| `default_visitor_code` (*optionnel*) | \`String.t() | nil\` | Visitor code à utiliser lorsqu'aucun cookie n'est présent. |
Le module accessor doit implémenter `get` et `set`. `get` lit une valeur de cookie depuis l'état de l'accessor, et `set` renvoie l'état mis à jour après avoir reçu `key`, `value`, `max_age` et `top_level_domain`.
##### Valeur retournée
| Type | Description | |
| ---------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------- |
| \`\{:ok, String.t(), term()} | \{:error, Kameleoon.Error.t()}\` | Chaîne représentant un visitor code unique utilisé dans le SDK en cas de succès, sinon une erreur. |
#### add\_data()
La méthode `Client.add_data` ajoute des [données de ciblage](#types-de-données) au stockage afin que d'autres méthodes puissent les utiliser pour décider s'il faut cibler ou non le visiteur actuel.
La méthode `Client.add_data` ne renvoie aucune valeur et n'interagit pas avec les serveurs back-end de Kameleoon par elle-même. Au lieu de cela, toutes les données déclarées sont enregistrées pour une transmission ultérieure via la méthode [`Client.flush`](#flush). Cette approche réduit le nombre d'appels au serveur, car les données sont généralement regroupées en un seul appel au serveur déclenché par `Client.flush`.
La méthode [`Client.track_conversion`](#track_conversion) envoie également toutes les données précédemment associées, tout comme `Client.flush`. Il en va de même pour les méthodes [`Client.get_variation`](#get_variation) et [`Client.get_variations`](#get_variations) si une règle d'expérimentation est déclenchée.
Chaque visiteur ne peut avoir qu'une seule instance de données associées pour la plupart des types de données. Cependant, [`CustomData`](#customdata) est une exception. Les visiteurs peuvent avoir une instance de `CustomData` associée par index.
```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
)
```
##### Arguments
| Nom | Type | Description | Valeur par défaut |
| ----------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| visitor\_code (*obligatoire*) | `String.t()` | Identifiant unique du visiteur. | |
| data (*obligatoire*) | `struct() \| [struct()]` | Collection de types de données Kameleoon. | |
| track (*optionnel*) | `boolean()` | Spécifie si les données ajoutées sont éligibles au tracking. Lorsqu'elles sont définies sur `false`, les données sont stockées localement et utilisées uniquement pour l'évaluation du ciblage ; elles ne sont pas envoyées à l'API Data de Kameleoon. | `true` |
##### Valeur retournée
| Type | Description | |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------ |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Indique si les données ont été ajoutées avec succès ou si une erreur s'est produite. |
##### Erreurs
| Type | Description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
#### flush()
* *📨 Envoie des données de tracking à Kameleoon*
La méthode `flush()` agrège toutes les données Kameleoon associées à un visiteur et envoie une requête de tracking au serveur. Cette requête inclut toutes les données précédemment ajoutées via la méthode [`add_data`](#add_data) qui n'ont pas encore été transmises par d'autres mécanismes de tracking (voir les méthodes référencées pour plus de détails). L'opération `flush()` est non bloquante, car l'appel au serveur est effectué de manière asynchrone.
Cette méthode offre un contrôle sur le moment où les données liées à un `visitor_code` spécifique sont transmises. Par exemple, si `add_data()` est appelée plusieurs fois, l'envoi d'une requête après chaque invocation serait inefficace. Au lieu de cela, vous pouvez regrouper ces mises à jour et appeler `flush()` une seule fois pour envoyer toutes les données accumulées en une seule requête.
La méthode `flush()` utilise le `visitor_code` fourni comme identifiant unique du visiteur.
* `flush()` — Met en file d'attente une opération de flush selon l'intervalle de tracking configuré.
* `flush_instant()` — Envoie immédiatement les données de tracking sans attendre l'intervalle.
```elixir theme={null}
# Met en file d'attente une opération de flush pour le visitor_code donné.
# Les données seront envoyées selon l'intervalle de tracking configuré.
:ok = Kameleoon.Client.flush(client, visitor_code)
# Envoie immédiatement toutes les données de tracking en attente pour le visitor_code donné.
:ok = Kameleoon.Client.flush_instant(client, visitor_code)
```
##### Arguments
| Nom | Type | Description |
| ------------------------------ | ------------ | ------------------------------- |
| `visitor_code` (*obligatoire*) | `String.t()` | Identifiant unique du visiteur. |
##### Valeur retournée
| Type | Description | |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------------------ |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Indique si l'opération a été planifiée ou exécutée avec succès, ou si une erreur s'est produite. |
##### Erreurs
| Type | Description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
#### get\_remote\_data()
La méthode `get_remote_data()` vous permet de récupérer des données distantes stockées sur les serveurs Kameleoon pour la `key` spécifiée. Dans la plupart des configurations, ces données sont écrites via l'API Data de Kameleoon et peuvent ensuite être récupérées par votre service Elixir chaque fois que vous avez besoin d'un contexte applicatif supplémentaire.
Cette méthode est utile lorsque vous souhaitez conserver des informations structurées sur l'infrastructure distante de Kameleoon et les réutiliser depuis votre back-end sans maintenir un mécanisme de récupération séparé.
```elixir theme={null}
{:ok, data} = Kameleoon.Client.get_remote_data(client, "test-key")
```
##### Arguments
| Nom | Type | Description |
| --------------------- | ------------ | ---------------------------------------------------------------- |
| `key` (*obligatoire*) | `String.t()` | Clé associée aux données distantes que vous souhaitez récupérer. |
##### Valeur retournée
| Type | Description | |
| -------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \`\{:ok, String.t()} | \{:error, Kameleoon.Error.t()}\` | Charge utile associée à la `key` spécifiée en cas de succès, sinon une erreur. Dans la plupart des cas, la charge utile est sérialisée au format JSON sous forme de chaîne. |
##### Erreurs
| Type | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `Network` | Renvoyé lorsque la requête de données distantes échoue ou que le serveur répond avec un code de statut non réussi. |
#### get\_remote\_visitor\_data()
`get_remote_visitor_data()` récupère les données de visite Kameleoon pour le `visitor_code` fourni. La méthode ajoute les données au stockage local du visiteur afin que d'autres méthodes du SDK puissent les utiliser pour les décisions de ciblage.
Les données obtenues via cette méthode sont particulièrement utiles lorsque vous souhaitez :
* utiliser des données collectées depuis d'autres appareils.
* accéder à l'historique d'un visiteur, comme les pages précédemment consultées lors de visites passées.
* utiliser des données qui ne sont disponibles que côté client, telles que les variables de datalayer et les conversions d'objectifs front-end.
Lisez [cet article](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) pour mieux comprendre les cas d'utilisation possibles.
Par défaut, `get_remote_visitor_data()` récupère automatiquement les dernières données personnalisées stockées avec `scope=Visitor` et les attache au visiteur sans avoir besoin d'appeler [`add_data()`](#add_data). Cela est particulièrement utile pour [synchroniser les données personnalisées entre plusieurs appareils](/developer-docs/cross-device-experimentation/).
```elixir theme={null}
alias Kameleoon.Client
alias Kameleoon.Types.RemoteVisitorDataFilter
# Récupérer les données distantes du visiteur sans aucun filtre.
# Cela renverra toutes les données disponibles pour le visiteur donné.
:ok = Client.get_remote_visitor_data(client, visitor_code)
# Créer un filtre pour limiter les données renvoyées.
filter = %RemoteVisitorDataFilter{
previous_visit_amount: 5,
conversions: true,
page_views: true
}
# Récupérer les données distantes du visiteur en utilisant le filtre spécifié.
# Cela ne renverra que les données correspondant aux critères du filtre.
:ok = Client.get_remote_visitor_data(client, visitor_code, filter: filter)
```
##### Arguments
| Nom | Type | Description | Par défaut | |
| ------------------------------ | --------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------- | ------------------------------ |
| `visitor_code` (*obligatoire*) | `String.t()` | Visitor code dont les données doivent être récupérées. | | |
| `filter` (*optionnel*) | \`Kameleoon.Types.RemoteVisitorDataFilter.t() | nil\` | Filtre décrivant quelles données distantes du visiteur doivent être récupérées. | `%RemoteVisitorDataFilter\{\}` |
##### Valeur retournée
| Type | Description | |
| ----- | -------------------------------- | ------------------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Renvoie avec succès lorsque les données sont récupérées et ajoutées localement, sinon une erreur. |
##### Erreurs
| Type | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
| `Network` | Renvoyé lorsque la requête de données distantes du visiteur échoue, ne peut pas être analysée, ou que le serveur répond avec un code de statut non réussi. |
##### Utilisation des paramètres dans get\_remote\_visitor\_data()
La méthode `get_remote_visitor_data()` vous permet de contrôler quelles données sont récupérées pour un visiteur. La même approche de filtrage fonctionne pour les objectifs, les expériences, les variations et autres données du visiteur.
Par exemple, si vous souhaitez cibler les utilisateurs qui ont converti sur un objectif lors de leurs cinq dernières visites, vous pouvez définir `previous_visit_amount` sur `5` et `conversions` sur `true`.
La flexibilité illustrée dans cet exemple ne se limite pas aux données d'objectifs. Vous pouvez utiliser le filtre pour récupérer de nombreux comportements de visiteurs différents et les rendre disponibles pour la logique de ciblage et de reporting dans votre application Elixir.
##### Champs de `RemoteVisitorDataFilter`
| Nom | Type | Description | Par défaut |
| ----------------------- | ------------------- | ------------------------------------------------------------------------ | ---------- |
| `previous_visit_amount` | `non_neg_integer()` | Nombre de visites précédentes à partir desquelles récupérer les données. | `1` |
| `current_visit` | `boolean()` | Si `true`, les données de la visite actuelle seront récupérées. | `true` |
| `custom_data` | `boolean()` | Si `true`, les données personnalisées seront récupérées. | `true` |
| `visitor_code` | `boolean()` | Si `true`, le visitor code le plus récent sera réutilisé. | `true` |
| `page_views` | `boolean()` | Si `true`, les données de page vue seront récupérées. | `false` |
| `geolocation` | `boolean()` | Si `true`, les données de géolocalisation seront récupérées. | `false` |
| `device` | `boolean()` | Si `true`, les données d'appareil seront récupérées. | `false` |
| `browser` | `boolean()` | Si `true`, les données de navigateur seront récupérées. | `false` |
| `operating_system` | `boolean()` | Si `true`, les données du système d'exploitation seront récupérées. | `false` |
| `conversions` | `boolean()` | Si `true`, les données de conversion seront récupérées. | `false` |
| `experiments` | `boolean()` | Si `true`, les données d'expérience seront récupérées. | `false` |
| `kcs` | `boolean()` | Si `true`, les données du Kameleoon Conversion Score seront récupérées. | `false` |
| `personalizations` | `boolean()` | Si `true`, les données de personnalisation seront récupérées. | `false` |
| `cbs` | `boolean()` | Si true, les données du Contextual Bandit score seront récupérées. | `false` |
#### get\_visitor\_warehouse\_audience()
Cette méthode récupère les données d'audience associées à un visiteur dans votre intégration warehouse en utilisant le `visitor_code` spécifié et, éventuellement, une `warehouse_key`. La `warehouse_key` est généralement votre ID utilisateur interne. Le paramètre `custom_data_index` correspond à la donnée personnalisée Kameleoon que Kameleoon utilise pour cibler vos visiteurs.
Lorsque l'appel réussit, le SDK convertit la liste d'audiences renvoyée en [`CustomData`](#customdata), l'ajoute au visiteur localement et la rend disponible à des fins de ciblage. Pour plus de contexte, consultez la [documentation sur le ciblage warehouse](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting).
```elixir theme={null}
alias Kameleoon.Client
# Récupérer les données d'audience d'un visiteur en utilisant uniquement le visitor_code.
:ok = Client.get_visitor_warehouse_audience(client, visitor_code, 98)
# Récupérer les données d'audience d'un visiteur en utilisant à la fois visitor_code et warehouse_key.
# Utile lorsque votre warehouse utilise un identifiant différent du visitor_code.
:ok = Client.get_visitor_warehouse_audience(client, visitor_code, 98, warehouse_key: "internal-user-id")
```
##### Arguments
| Nom | Type | Description | Par défaut | |
| ----------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------- |
| `visitor_code` (*obligatoire*) | `String.t()` | Visiteur dont les audiences warehouse doivent être récupérées. | | |
| `custom_data_index` (*obligatoire*) | `non_neg_integer()` | Index de données personnalisées configuré dans Kameleoon pour le ciblage d'audience warehouse. | | |
| `warehouse_key` (*optionnel*) | \`String.t() | nil\` | Clé warehouse externe, généralement votre ID utilisateur interne. | `visitor_code` |
##### Valeur retournée
| Type | Description | |
| ----- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Succès lorsque les données d'audience warehouse sont récupérées et stockées localement en tant que `CustomData`. |
##### Erreurs
| Type | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
| `Network` | Renvoyé lorsque la requête d'audience warehouse échoue, ne peut pas être analysée, ou que le serveur répond avec un code de statut non réussi. |
#### set\_legal\_consent()
Vous devez utiliser cette méthode pour spécifier si le visiteur a donné son consentement légal à l'utilisation de ses données personnelles. Définir `legal_consent` sur `false` limite les types de données pouvant être inclus dans les requêtes de tracking. Cela vous aide à respecter les exigences légales et réglementaires tout en gérant les données des visiteurs de manière responsable. Pour plus d'informations, consultez la [politique de gestion du consentement](/user-manual/project-management/consent-management-policy).
Le SDK Elixir met à jour les cookies du visiteur via l'adaptateur `Kameleoon.CookieAccessor` requis et renvoie l'état mis à jour de l'adaptateur.
```elixir theme={null}
cookies = {PlugConnCookies, conn}
# Définir le consentement et mettre à jour les cookies.
{:ok, conn} = Kameleoon.Client.set_legal_consent(client, visitor_code, true, cookies)
```
##### Arguments
| Nom | Type | Description | Par défaut |
| ------------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `visitor_code` (*obligatoire*) | `String.t()` | Identifiant unique de l'utilisateur. | |
| `consent` (*obligatoire*) | `boolean()` | `true` indique que le visiteur a donné son consentement légal, `false` indique que le visiteur n'a jamais fourni ou a retiré son consentement légal. | |
| `cookies` (*obligatoire*) | `\{module(), term()\}` | Module accessor de cookies et état spécifique au framework utilisés pour mettre à jour les cookies. | |
##### Valeur retournée
| Type | Description | |
| ---------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| \`\{:ok, term()} | \{:error, Kameleoon.Error.t()}\` | Renvoie l'état mis à jour du cookie lorsque l'état du consentement du visiteur a été mis à jour avec succès, sinon une erreur. |
##### Erreurs
| Type | Description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
##### Comportement de révocation du consentement
Lorsque vous appelez `Client.set_legal_consent` avec `legal_consent=false`, le SDK ne supprime pas le cookie `kameleoonVisitorCode`. Au lieu de cela, il cesse de prolonger la date d'expiration du cookie, permettant au cookie de persister jusqu'à son expiration naturelle.
Si vos exigences de conformité imposent la suppression immédiate du fichier cookie lors du retrait du consentement, vous devez le supprimer manuellement en utilisant les méthodes natives de gestion des cookies de votre framework. Le SDK ne supprimera pas le fichier automatiquement.
### Objectifs et analyses tierces
#### track\_conversion()
* 📨 *Envoie des données de tracking à Kameleoon*
Utilisez cette méthode pour suivre une conversion pour un [objectif](/user-manual//assets/goals/create-a-goal) et un utilisateur spécifiques. Cette méthode requiert `visitor_code` et `goal_id`. De plus, cette méthode accepte également des arguments optionnels `revenue`, `negative` et `metadata`. Le `visitor_code` est généralement identique à celui utilisé lors du déclenchement de l'expérience.
Cette méthode est non bloquante car l'appel au serveur est effectué de manière asynchrone.
```elixir theme={null}
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
# Suivre un objectif.
:ok = Client.track_conversion(client, visitor_code, goal_id)
# Suivre un objectif avec un revenu.
:ok = Client.track_conversion(client, visitor_code, goal_id, revenue: 100.0)
# Suivre un objectif avec un revenu négatif.
:ok = Client.track_conversion(client, visitor_code, goal_id, revenue: 100.0, negative: true)
# Suivre un objectif avec des métadonnées personnalisées.
:ok =
Client.track_conversion(
client,
visitor_code,
goal_id,
metadata: [CustomData.new!(4, ["true"])]
)
```
##### Arguments
| Nom | Type | Description | Par défaut |
| ------------------------------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `visitor_code` (*obligatoire*) | `String.t()` | Identifiant unique du visiteur. | |
| `goal_id` (*obligatoire*) | `non_neg_integer()` | ID de l'objectif. | |
| `revenue` (*optionnel*) | `number() \| nil` | Revenu de la conversion. | `0` |
| `negative` (*optionnel*) | `boolean()` | Définit si le revenu est positif ou négatif. | `false` |
| `metadata` (*optionnel*) | `[Kameleoon.Data.CustomData.t()]` | Métadonnées de la conversion. [Doivent être définies au préalable dans l'application Kameleoon](/fr/user-manual/assets/goals/create-a-goal#métadonnées). | `[]` |
Les valeurs des métadonnées sont accessibles via les [exports de données brutes](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export) et [la page de résultats](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata).
Si le paramètre `metadata` est fourni, Kameleoon utilisera ces valeurs spécifiées pour la conversion en cours au lieu de ce qui a été précédemment collecté en utilisant la méthode [`Client.add_data`](#add_data). Si le paramètre est omis, Kameleoon utilisera les dernières valeurs suivies pour ces [`CustomData`](#customdata) avant la conversion et au cours de la même visite.
Kameleoon ne prendra en compte que les valeurs de métadonnées explicitement passées en tant que paramètres à la méthode `Client.track_conversion`.
Dans l'exemple ci-dessous, Kameleoon associera la conversion uniquement à la valeur de donnée personnalisée explicitement fournie en paramètre (ici : index 5 avec la valeur '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"])]
)
```
##### Valeur retournée
| Type | Description | |
| ----- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| \`:ok | \{:error, Kameleoon.Error.t()}\` | Indique si la conversion a été correctement mise en file d'attente pour le tracking asynchrone, sinon une erreur. |
##### Erreurs
| Type | Description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Initialization` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
#### get\_engine\_tracking\_code()
Kameleoon s'intègre à plusieurs solutions d'analyse, notamment Mixpanel, Google Analytics 4 et Segment. Pour suivre correctement les expériences côté serveur, appelez la méthode `Client.get_engine_tracking_code` après que le visiteur a déclenché une expérience. Le SDK renvoie des commandes de file d'attente JavaScript pour les expériences que le visiteur a déclenchées au cours des cinq dernières secondes. Lorsque vous insérez ce code dans la page, Engine.js traite les commandes et envoie les événements d'exposition via l'intégration d'analyse active.
Consultez [l'expérimentation hybride](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) pour plus d'informations sur l'implémentation de cette méthode.
```elixir theme={null}
{:ok, tracking_code} = Kameleoon.Client.get_engine_tracking_code(client, visitor_code)
```
* Pour utiliser cette fonctionnalité, implémentez à la fois le SDK Elixir et Kameleoon [Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation). Étant donné qu'Engine.js n'est utilisé que pour le tracking dans ce flux, vous pouvez installer le tag asynchrone avant la balise de fermeture ``.
* Si vous souhaitez uniquement suivre les expériences dans Kameleoon et n'avez pas besoin d'envoyer des événements d'exposition à des outils d'analyse tiers, utilisez le [SDK JavaScript / TypeScript](/developer-docs/sdks/web-sdks/js-sdk). Cette option fonctionne bien pour les [plateformes de calcul serverless en périphérie](/developer-docs/feature-experimentation/implementation-and-deployment/serverless-edge-compute-starter-kits). Le SDK JavaScript / TypeScript suit automatiquement les variations lorsque vous appelez [`getVisitorCode`](/developer-docs/sdks/web-sdks/js-sdk#getvisitorcode), à condition que vous ajoutiez les attributions d'expérience correspondantes à `window.kameleoonQueue`.
* Vous pouvez insérer le code de tracking renvoyé directement dans une balise HTML `