> ## 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 Ruby
> Intégrez le SDK Ruby de Kameleoon pour exécuter des expériences et activer des feature flags sur des serveurs back-end Ruby et des applications Rails.
Avec le SDK Ruby, vous pouvez exécuter des expériences et activer des feature flags sur votre serveur back-end Ruby. L'intégration de notre SDK dans votre application web est simple, et son empreinte (mémoire et utilisation réseau) est faible.
**Pour commencer** : Pour obtenir de l'aide pour démarrer, consultez le [guide du développeur](#guide-du-développeur).
**Changelog** : Dernière version du SDK Ruby : 3.20.0 [Changelog](https://github.com/Kameleoon/client-ruby/blob/master/CHANGELOG.md).
**Méthodes du SDK** : Pour la documentation de référence complète du SDK Ruby, consultez la section [référence](#référence).
## Guide du développeur
Cette section vous explique comment intégrer notre SDK et commencer à exécuter des expériences dans vos applications Ruby. Suivez ce tutoriel pour mettre en place un simple A/B test afin de modifier le nombre de produits recommandés en fonction des différentes variations.
### Pour commencer
#### Installer le SDK
Installez le SDK à l'aide d'un package gem standard, hébergé sur le référentiel officiel RubyGems. Pour l'installer, exécutez la commande suivante :
```cli theme={null}
gem install kameleoon-client-ruby
```
#### Configurer le client
Vous fournissez les identifiants pour le SDK Ruby à l'aide d'un fichier de configuration, que vous pouvez également utiliser pour personnaliser le comportement du SDK. Vous pouvez commencer par notre [exemple de fichier de configuration](/assets/developer-docs/sdks/web-sdks/client-configs/client-ruby.yaml). Nous recommandons d'ajouter ce fichier au chemin par défaut `/etc/kameleoon/client-ruby.yaml`. Si vous utilisez un autre emplacement, vous devez transmettre le chemin en argument à la méthode `Kameleoon::KameleoonClientFactory.Create()` lors de l'initialisation. Voici les clés disponibles dans la dernière version du SDK :
| Clé | Description | Valeur par défaut |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| `client_id` (*requis*) | Requis pour l'authentification auprès du 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` (*requis*) | Requis pour l'authentification auprès du 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_minute` (*optionnel*) | Désigne l'intervalle de temps prédéfini pendant lequel Kameleoon stocke le visiteur et ses données associées en mémoire (RAM). Notez qu'augmenter la durée de la session augmente la quantité de RAM nécessaire pour stocker les données du visiteur. | `30` minutes |
| `refresh_interval_minute` (*optionnel*) | Spécifie l'intervalle de rafraîchissement, en minutes, auquel le SDK récupère la configuration des expériences et des feature flags actifs. La valeur détermine le temps maximum nécessaire pour propager les modifications, comme l'activation ou la désactivation des feature flags ou le lancement d'expériences, vers vos serveurs de production. De plus, nous proposons un [mode streaming](/developer-docs/feature-experimentation/technical-reference/technical-considerations/#streaming-premium-option) qui utilise les server-sent events (SSE) pour envoyer automatiquement les nouvelles configurations au SDK et appliquer les nouvelles configurations en temps réel, sans aucun délai. | `60` minutes |
| `default_timeout_millisecond` (*optionnel*) | Spécifie le délai d'expiration, en millisecondes, des requêtes réseau du SDK. Définissez la valeur à 30 secondes ou plus si vous n'avez pas une connexion stable. Certaines méthodes ont un paramètre supplémentaire que vous pouvez utiliser pour remplacer le délai par défaut pour cette méthode particulière. Si vous ne spécifiez pas explicitement le délai pour une méthode, le SDK utilise cette valeur par défaut. | `10000` millisecondes |
| `tracking_interval_millisecond` (*optionnel*) | Spécifie l'intervalle des requêtes de tracking en millisecondes. Tous les visiteurs que Kameleoon a évalués pour un feature flag ou dont les données ont été vidées sont inclus dans cette requête de tracking, que le SDK effectue une fois par intervalle. La valeur minimale est de `1000` ms, qui est également la valeur par défaut, et la valeur maximale est de `5000` ms. | `1000` millisecondes |
| `environment` (*optionnel*) | Environnement à partir duquel la configuration du feature flag doit être utilisée. La valeur peut être `production`, `staging`, `development`. Consultez l'article [managing environments](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/manage-environments) pour plus de détails. | `production` |
| `top_level_domain` *(requis en mode hybride)* | Le domaine de premier niveau actuel de votre site web. Utilisez le format : `example.com`. N'incluez pas `https://`, `www` ou d'autres sous-domaines. Kameleoon utilise ces informations pour définir le cookie correspondant sur le domaine de premier niveau. | `nil` |
| `network_domain` (*optionnel*) | Domaine personnalisé utilisé par les SDK pour les requêtes sortantes, souvent pour le proxying. Doit être un domaine valide (par exemple, example.com ou sub.example.com). Les formats invalides utiliseront par défaut la valeur de Kameleoon. | `nil` |
| `verbose_mode` *(obsolète)* | Valeur booléenne (`true` ou `false`) qui active la journalisation supplémentaire, y compris les requêtes réseau et les informations de débogage. Ce champ est obsolète et sera supprimé dans la version `4.0.0` du SDK. Utilisez plutôt [`KameleoonLogger.setLogLevel`](#niveaux-de-log). | `nil` |
Le SDK Ruby de Kameleoon utilise l'API Automation et suit le flow d'identifiants client OAuth 2.0.
#### Initialiser le client
Après avoir installé le SDK dans votre application et configuré les identifiants corrects (dans `/etc/kameleoon/client-ruby.yaml` ou `Kameleoon::KameleoonClientConfig`), vous devez configurer une expérience côté serveur dans l'application Kameleoon.
L'étape suivante consiste à créer le client Kameleoon dans le code de votre application. Le code suivant fournit un exemple de création du client Kameleoon. Un `Kameleoon::KameleoonClient` est un objet singleton qui agit comme un pont entre votre application et Kameleoon. Il inclut toutes les méthodes et propriétés dont vous avez besoin pour exécuter une expérience.
Les développeurs sont responsables d'assurer la logique correcte du code de leur application lors de l'implémentation de l'A/B test avec Kameleoon. Une bonne pratique consiste à toujours supposer qu'un visiteur peut être exclu de l'expérience si celle-ci n'a pas encore été lancée. Cette pratique est simple à implémenter, car elle s'aligne sur la logique de la variation par défaut ou de référence, qui doit toujours être en place. Les exemples de code de la section suivante illustrent cette approche.
```ruby theme={null}
# external settings file
require "kameleoon"
site_code = "a8st4f59bj"
kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code)
kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code, config_path: '/etc/kameleoon/client-ruby.yaml')
# internal KameleoonClientConfig object
require 'kameleoon'
require 'kameleoon/kameleoon_client_config'
kameleoon_config = Kameleoon::KameleoonClientConfig.new(
'client_id', # required
'client_secret', # required
refresh_interval_minute: configuration_refresh_interval, # (in minutes) optional, default: 60 minutes
session_duration_minute: session_duration, # (in minutes) optional, default: 30 minutes
default_timeout_millisecond: default_timeout, # (in milliseconds) optional, default: 2000 milliseconds
tracking_interval_millisecond: tracking_interval, # (in milliseconds) optional (1000 ms by default)
environment: environment, # optional, possible values: "production" / "staging" / "development" / "staging", default: "production"
top_level_domain: 'example.com',
verbose_mode: verbose_mode, # optional, default: false
network_domain: 'example.com' # optional
)
kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code, config: kameleoon_config)
```
Si vous utilisez Ruby on Rails, nous vous recommandons d'initialiser le client Kameleoon au démarrage du serveur dans le fichier application.rb.
```ruby theme={null}
require_relative 'boot'
require 'rails/all'
require 'kameleoon'
Bundler.require(*Rails.groups)
module App
class Application < Rails::Application
# Initialize configuration defaults for originally generated Rails version.
config.load_defaults 6.1
if defined?(Rails::Server)
config.after_initialize do
site_code = 'a8st4f59bj'
kameleoon_config = Kameleoon::KameleoonClientConfig.new('client_id', 'client_secret')
config.kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code, config: kameleoon_config)
end
end
end
end
```
Vous pouvez ensuite accéder au client Kameleoon dans vos contrôleurs :
```ruby theme={null}
class YourController < ApplicationController
def index
kameleoon_client = App::Application.config.kameleoon_client
# Your controller code, using the kameleoon_client
end
end
```
#### Activer un feature flag
##### Attribution d'un ID unique à un utilisateur
Pour attribuer un ID unique à un utilisateur, vous pouvez utiliser la méthode [`get_visitor_code()`](#get_visitor_code). Si un **visitor code** n'existe pas (dans le cookie des en-têtes de requête), la méthode génère un ID unique aléatoire ou utilise un `default_visitor_code` que vous auriez généré. L'ID 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), appeler la méthode `get_visitor_code()` garantit que l'ID unique (**visitor code**) est partagé entre le fichier d'application `engine.js` (précédemment nommé `kameleoon.js`) et le SDK.
##### Récupérer 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, utilisez la méthode [`get_variation()`](#get_variation) ou [`feature_active?()`](#feature_active) pour récupérer la configuration en fonction de la `feature_key`.
La méthode `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 `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 aux feature flags plus complexes avec plusieurs variations ou options de targeting.
Si votre feature flag a des variables associées (telles que des comportements spécifiques liés à chaque variation), `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 la sauvegarde 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 [`tracking_interval_millisecond`](#configurer-le-client) du SDK. Par défaut, cet intervalle est défini à 1000 millisecondes (1 seconde).
La méthode `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 lorsque vous utilisez la méthode `get_variations()`, où vous pourriez n'avoir besoin que des variations pour tous les flags sans déclencher d'événements de tracking. Si vous voulez 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)
##### Ajouter des points de données pour cibler un utilisateur ou filtrer / décomposer 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 [`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 [`get_remote_visitor_data()`](#get_remote_visitor_data). Cette méthode récupère les données des serveurs de manière asynchrone. Il est important d'appeler `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 targeting disponibles, consultez l'[article détaillé sur le 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écomposer vos résultats par facteurs comme 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 ce qui est collecté automatiquement, vous pouvez utiliser la [fonctionnalité Custom Data](#customdata) de Kameleoon. Custom Data vous permet de capturer et d'analyser des informations spécifiques pertinentes pour vos expériences. N'oubliez pas d'appeler la méthode [`flush()`](#flush) pour envoyer les données collectées aux serveurs Kameleoon pour analyse.
Pour vous assurer que vos résultats sont exacts, il est recommandé de filtrer les bots en utilisant le type de données [`UserAgent`](#useragent).
##### Suivre les conversions des objectifs
Lorsqu'un utilisateur effectue une action souhaitée (comme faire un achat), elle est enregistrée comme une conversion. Pour suivre les conversions, utilisez la méthode [`track_conversion()`](#track_conversion) et fournissez les paramètres requis `visitor_code` et `goal_id`.
La requête de tracking 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_millisecond`](#configurer-le-client)). Si vous préférez envoyer la requête immédiatement, utilisez la méthode [`flush()`](#flush) avec le paramètre `instant=true`.
##### Envoi d'événements aux solutions d'analytics
Pour suivre les conversions et envoyer des événements d'exposition à votre solution d'analytics client, vous devez d'abord implémenter Kameleoon en [mode hybride](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/). Ensuite, utilisez la méthode [`get_engine_tracking_code()`](#get_engine_tracking_code).
La méthode `get_engine_tracking_code()` récupère le code de tracking unique requis pour envoyer des événements d'exposition à votre solution d'analytics. L'utilisation de cette méthode vous permet d'enregistrer des événements et de les envoyer à votre plateforme d'analytics choisie.
### 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 et la réconciliation de leur historique de visite entre les appareils grâce à l'expérimentation cross-device. Des études de cas et des informations détaillées sur la manière 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).
#### Synchroniser les custom data entre les appareils
Bien que la synchronisation du mapping personnalisé soit utilisée pour aligner les données du visiteur entre les appareils, elle n'est pas toujours nécessaire. Voici deux scénarios où la synchronisation du mapping 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 de mapping personnalisé. Il suffit d'appeler la méthode `get_remote_visitor_data()` lorsque vous voulez synchroniser les données collectées entre plusieurs appareils.
**Instances multi-serveurs avec des ID cohérents**
Dans les configurations complexes impliquant plusieurs serveurs (par exemple, des instances de serveurs distribuées), où le même ID utilisateur est disponible sur tous les serveurs, la synchronisation entre les serveurs (avec `get_remote_visitor_data()`) est suffisante sans synchronisation supplémentaire du mapping personnalisé.
Les clients qui ont besoin de données supplémentaires peuvent se référer à la description de la méthode [`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`, qui peut également être 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 voulez synchroniser les données collectées en temps réel, vous devez choisir le scope **Visitor** pour vos custom data.
```ruby title="Device A" theme={null}
# In this example, Custom data with index `90` was set to "Visitor" scope in Kameleoon.
VISITOR_SCOPE_CUSTOM_DATA_INDEX = 90
kameleoon_client.add_data(visitor_code, CustomData.new(VISITOR_SCOPE_CUSTOM_DATA_INDEX, 'your data'))
kameleoon_client.flush(visitor_code)
```
```ruby title="Device B" theme={null}
# Before working with the data, call `get_remote_visitor_data`.
kameleoon_client.get_remote_visitor_data(visitor_code)
# After calling, the SDK on Device B will have access to CustomData of Visitor scope defined on Device A.
# So, "your data" will be available to target and track the visitor.
```
#### Utiliser les custom data 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 de visite, 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, appeler [`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 Visitor de la page de résultats de votre expérience, ces sessions apparaîtront comme un seul visiteur.
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'allocation des variations cross-device. Ces limitations sont décrites [ici](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights).
Suivez le guide [activating cross-device history reconciliation](#expérimentation-cross-device) pour configurer vos custom data 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 :
* `get_remote_visitor_data()` avec `UniqueIdentifier(true)` ajouté - pour récupérer les données de tous les visiteurs liés.
* [`track_conversion()`](#track_conversion) ou [`flush()`](#flush) avec les données `UniqueIdentifier(true)` ajoutées - pour suivre certaines données pour un visiteur spécifique associé à un autre visiteur.
Comme la custom data que vous utilisez comme identifiant doit être définie sur le **Visitor scope**, vous devez utiliser la [synchronisation des custom data cross-device](/developer-docs/cross-device-experimentation) pour récupérer l'identifiant avec la méthode [`get_remote_visitor_data()`](#get_remote_visitor_data) sur chaque appareil.
Voici un exemple d'utilisation des custom data pour la fusion de sessions.
```ruby theme={null}
# In this example, `91` represents the Custom Data's index configured as a unique identifier in Kameleoon.
MAPPING_INDEX = 91
FEATURE_KEY = 'ff123'
# 1. Before the visitor is authenticated
# Retrieve the variation for an unauthenticated visitor.
# Assume `anonymous_visitor_code` is the randomly generated ID for that visitor.
anonymous_variation = kameleoon_client.get_variation(anonymous_visitor_code, FEATURE_KEY)
# 2. After the visitor is authenticated
# Assume `user_id` is the visitor code of the authenticated visitor.
kameleoon_client.add_data(anonymous_visitor_code, CustomData.new(MAPPING_INDEX, user_id))
kameleoon_client.flush(anonymous_visitor_code, instant: true)
# Indicate that `user_id` is a unique identifier.
kameleoon_client.add_data(user_id, UniqueIdentifier.new(True))
# 3. After the visitor has been authenticated
# Retrieve the variation for the `user_id`, which will match the anonymous visitor code's variation.
user_variation = kameleoon_client.get_variation(user_id, FEATURE_KEY)
is_same_variation = user_variation.key == anonymous_variation.key # true
# The `user_id` and `anonymous_visitor_code` are now linked and tracked as a single visitor.
kameleoon_client.track_conversion(user_id, 123, 10.0)
# Additionally, the linked visitors will share all fetched remote visitor data.
kameleoon_client.get_remote_visitor_data(user_id)
```
Dans cet exemple, l'application possède une page de connexion. Étant donné que l'ID utilisateur est inconnu au moment de la connexion, un identifiant de visiteur anonyme généré par la méthode [`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.
### Utilisation d'une clé de bucketing personnalisée
Par défaut, Kameleoon utilise un ID de visiteur unique et anonyme (`visitor_code`) pour attribuer des utilisateurs aux variations de feature flag. Cet ID est généralement généré et stocké sur l'appareil de l'utilisateur (dans un cookie du 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 pourriez avoir besoin de garantir que tous les utilisateurs d'une même organisation voient la même variante d'un feature flag.
L'option **Custom Bucketing Key** 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 votre clé spécifiée au lieu du `visitor_code` par défaut.
#### Cas d'utilisation
L'utilisation d'une clé de bucketing personnalisée est essentielle pour maintenir la cohérence et la précision dans vos attributions de feature flag, 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 voulez attribuer tous les utilisateurs d'une même organisation à la même variation, vous pouvez utiliser un identifiant comme un `accountId`. Les clés de bucketing personnalisées sont cruciales pour l'A/B test de fonctionnalités qui impactent une équipe ou une entreprise entière.
En implémentant une clé de bucketing personnalisée, vous garantissez une plus grande cohérence et précision dans vos expériences, conduisant à 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 :
```ruby theme={null}
bucketing_key = Kameleoon::CustomData.new(index, 'new_visitor_code')
kameleoon_client.add_data(visitor_code, bucketing_key)
```
* **Fournir la clé personnalisée :** Vous fournissez votre identifiant personnalisé au SDK Kameleoon en utilisant la méthode [`add_data()`](#add_data). Dans cette méthode, vous passerez la clé de bucketing personnalisée choisie en tant qu'objet [`CustomData`](#customdata). Ici, `newVisitorCode` fait référence à l'identifiant que vous souhaitez utiliser pour votre bucketing (par exemple, le nouvel `userId` ou `accountId`).
Pour que la clé de bucketing personnalisée fonctionne correctement, elle doit également être définie et configurée pour le feature flag lors de la création ou de la 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 configuration 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 `add_data()`, tous les calculs de hash pour attribuer les utilisateurs aux variations utiliseront ce `newVisitorCode` (votre clé personnalisée) au lieu du `visitor_code` par défaut. L'utilisation du `newVisitorCode` 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 analytics :** Il est crucial de noter que bien que le `newVisitorCode` (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 analytics 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 visiteur d'origine restent intactes pour des rapports complets.
#### Exigences techniques
Pour utiliser efficacement une clé de bucketing personnalisée :
* La clé doit être une `String`.
* Elle doit être unique pour l'entité que vous souhaitez bucket (par exemple, si vous utilisez un `userId`, l'ID 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 targeting
Les SDK de Kameleoon prennent en charge une variété de conditions de targeting prédéfinies que vous pouvez utiliser pour cibler des utilisateurs dans vos campagnes. Pour la liste des conditions prises en charge par ce SDK, consultez [use visit history to target users](/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).
### Journalisation
Le SDK génère des logs pour refléter divers processus et problèmes internes.
#### Niveaux de log
Le SDK prend en charge la configuration de la limitation de la journalisation par un niveau de log.
```ruby theme={null}
require 'kameleoon/logging/kameleoon_logger'
# The `NONE` log level does not allow logging.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::NONE
# The `ERROR` log level only allows logging issues that may affect the SDK's main behaviour.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::ERROR
# The `WARNING` log level allows logging issues which may require additional attention.
# It extends the `ERROR` log level.
# The `WARNING` log level is a default log level.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::WARNING
# The `INFO` log level allows logging general information on the SDK's internal processes.
# It extends the `WARNING` log level.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::INFO
# The `DEBUG` level logs additional details about the SDK’s internal processes and extends the `INFO` level
# with more granular. diagnostic output.
# This information is not intended for end-user interpretation but can be sent to our support team
# to assist with internal troubleshooting.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::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 un niveau de log est effectuée indépendamment de la logique de gestion des logs.
```ruby theme={null}
require 'logger'
require 'kameleoon/logging/logger'
module Kameleoon
class CustomLogger < Kameleoon::Logging::Logger
def initialize
@internal_logger = Logger.new(STDOUT)
end
def log(level, message)
case level
when Kameleoon::Logging::LogLevel::ERROR
@internal_logger.error(message)
when Kameleoon::Logging::LogLevel::WARNING
@internal_logger.warn(message)
when Kameleoon::Logging::LogLevel::INFO
@internal_logger.info(message)
when Kameleoon::Logging::LogLevel::DEBUG
@internal_logger.debug(message)
end
end
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.
# Ensure the log level is set correctly.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::DEBUG # Optional, defaults to `Kameleoon::Logging::LogLevel::WARNING`.
Kameleoon::Logging::KameleoonLogger.logger = CustomLogger.new
```
## Référence
Voici la documentation de référence complète du SDK Ruby.
### Initialisation
#### create()
Le point de départ pour utiliser le SDK est l'étape d'initialisation. Toutes les interactions avec le SDK se font via un objet nommé Kameleoon::KameleoonClient, vous devez donc créer cet objet.
```ruby theme={null}
kameleoon_config = Kameleoon::KameleoonClientConfig.new('client_id', 'client_secret')
kameleoon_client = Kameleoon::KameleoonClientFactory.create('a8st4f59bj', config: kameleoon_config)
kameleoon_client = Kameleoon::KameleoonClientFactory.create('a8st4f59bj', config_path: '/etc/kameleoon/client-ruby.yaml')
```
##### Arguments
| Nom | Type | Description |
| ------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| site\_code | String | Il s'agit d'une [clé unique](/user-manual/faq#how-do-i-find-my-sitecode) du projet Kameleoon que vous utilisez avec le SDK. Ce champ est obligatoire. |
| configuration\_file\_path | String | Chemin vers le fichier de configuration du SDK. Ce champ est optionnel et défini par défaut sur `/etc/kameleoon/client-ruby.yaml`. |
| config | Kameleoon::KameleoonClientConfig | Objet de configuration du SDK que vous pouvez transmettre au lieu d'utiliser un fichier de configuration. Ce champ est optionnel. |
##### Exceptions levées
| Type | Description |
| ------------------------------------- | --------------------------------------------------------------------------------------- |
| Kameleoon::Exception::SiteCodeIsEmpty | Exception indiquant que le site code spécifié est une chaîne vide, ce qui est invalide. |
#### wait\_init()
`wait_init` attend l'initialisation du client Kameleoon. Cette méthode vous permet de vérifier si le client a été initialisé avec succès avant de procéder à d'autres opérations.
Une fois le client initialisé, `wait_init` renvoie immédiatement. Si la récupération initiale de la configuration échoue, le client continue de réessayer en arrière-plan, de sorte que `wait_init` renvoie dès qu'une récupération aboutit. L'attente est toujours bornée par un délai d'expiration, elle ne bloque donc jamais indéfiniment : si le délai s'écoule avant le chargement de la configuration, `wait_init` renvoie `false`.
```ruby theme={null}
kameleoon_client = Kameleoon::KameleoonClientFactory.create('a8st4f59bj')
if kameleoon_client.wait_init
# The SDK has been initialized;
end
# Wait up to 5 seconds for the SDK to become ready.
if kameleoon_client.wait_init(5000)
# The SDK has been initialized;
end
```
##### Arguments
| Nom | Type | Description | Défaut |
| ----------------------------------- | --------- | ------------------------------------------ | ------------------------------------------------------ |
| `timeout_millisecond` (*optionnel*) | `Integer` | Temps d'attente maximal, en millisecondes. | [`default_timeout_millisecond`](#configurer-le-client) |
##### Valeur de retour
| Type | Description |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Boolean` | `true` si l'instance du client Kameleoon a été initialisée avec succès, sinon `false` (par exemple, si le délai s'est écoulé avant la fin de l'initialisation). |
### Feature flags et variations
#### feature\_active?()
* 📨 *Envoie des données de tracking à Kameleoon (selon le paramètre `track`)*
Précédemment appelé `activate_feature` - supprimé depuis la version `3.0.0` du SDK.
Cette méthode prend un **visitor\_code** et une **feature\_key** comme arguments obligatoires pour vérifier si le feature spécifié sera actif pour un utilisateur.
Si un tel utilisateur n'a jamais été associé à ce feature flag, le SDK renvoie une valeur booléenne de manière aléatoire (**true** si l'utilisateur doit avoir ce feature ou **false** s'il ne doit pas l'avoir). Si un utilisateur avec un **visitor\_code** donné est déjà enregistré avec ce feature flag, il détectera la valeur précédente du **FeatureFlag**.
Vous devez vous assurer qu'une gestion appropriée des erreurs est mise en place dans votre code, comme indiqué dans l'exemple à droite, pour intercepter les exceptions potentielles.
Si vous spécifiez un `visitor_code`, la méthode `feature_active?` utilise le `visitor_code` comme identifiant unique du visiteur, ce qui est utile pour l'[expérimentation cross-device](/developer-docs/cross-device-experimentation). Lorsque vous spécifiez un `visitor_code` et définissez le paramètre `is_unique_identifier` sur `true`, le SDK lie les données vidées au visiteur associé à l'identifiant spécifié.
Le paramètre `is_unique_identifier` est obsolète. Veuillez utiliser [`UniqueIdentifier`](#uniqueidentifier) à la place.
Le `is_unique_identifier` peut également être utile dans d'autres scénarios particuliers, par exemple lorsque vous ne pouvez pas accéder au `visitorCode` anonyme qui a été initialement attribué au visiteur, mais vous avez accès à un ID interne qui est connecté au visiteur anonyme grâce aux capacités de fusion de sessions.
```ruby theme={null}
visitor_code = kameleoon_client.get_visitor_code(cookies)
feature_key = "new_checkout"
has_new_checkout = false
begin
has_new_checkout = kameleoon_client.feature_active?(visitor_code, feature_key)
# disabling tracking
has_new_checkout = kameleoon_client.feature_active?(visitor_code, feature_key, track: false)
rescue Kameleoon::Exception::FeatureNotFound
# The user will not be counted in the experiment, but should see the reference variation.
has_new_checkout = false
end
if has_new_checkout
# Implement new checkout code here
end
```
La méthode `feature_active?()` évalue la variante servie, et non l'état maître du 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 feature flag maître est sur **On**.
##### Arguments
| Nom | Type | Description |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| visitor\_code | `String` | Identifiant unique de l'utilisateur. Ce champ est obligatoire. |
| feature\_key | `String` | Clé du feature que vous voulez exposer à un utilisateur. Ce champ est obligatoire. |
| is\_unique\_identifier (Obsolète) | `Boolean` | Lorsqu'il est défini sur `true`, le SDK lie les données vidées au visiteur associé à l'identifiant spécifié. |
| track | `Boolean` | Un paramètre optionnel pour activer ou désactiver le suivi de l'évaluation du feature (`true` par défaut). |
##### Valeur de retour
| Type | Description |
| --------- | ---------------------------------------------------------------------- |
| `Boolean` | Valeur du feature qui est enregistrée pour un **visitor\_code** donné. |
##### Exceptions levées
| Type | Description |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Kameleoon::Exception::FeatureNotFound | Exception indiquant que l'ID du feature demandé n'a pas été trouvé dans la configuration interne du SDK. Cette exception est généralement normale et signifie que le feature flag n'a pas encore été activé côté Kameleoon (mais le code implémentant le feature est déjà déployé côté application web). |
| Kameleoon::Exception::VisitorCodeInvalid | Exception indiquant que le visitor code fourni est invalide (vide, ou 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 défini par défaut sur `true`.
Elle renvoie la `Variation` attribuée pour le 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 fait référence à 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, c'est 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 par la variation dans la section "Then, for everyone else..." dans une interface de gestion.
```ruby theme={null}
feature_key = "new_checkout"
begin
variation = kameleoon_client.get_variation(visitor_code, feature_key)
# disabling tracking
variation = kameleoon_client.get_variation(visitor_code, feature_key, track: false)
rescue Kameleoon::Exception::FeatureNotFound
# The error has occurred; the feature flag isn't found in the current configuration.
rescue Kameleoon::Exception::FeatureEnvironmentDisabled
# The feature flag is disabled for the environment
rescue Kameleoon::Exception::VisitorCodeInvalid
# The visitor code you passed to the method is invalid and can't be accepted by SDK
end
# Fetch a variable value for the assigned variation
title = variation.variables['title'].value
case variation.key
when 'on'
# Main variation key is selected for visitorCode
when 'alternative_variation'
# Alternative variation key
else
# Default variation key
end
```
##### Arguments
| Nom | Type | Description | Par défaut |
| ------------------------ | -------- | -------------------------------------------------------------------------------------- | ---------- |
| visitor\_code (*requis*) | `String` | Identifiant unique du visiteur. | |
| feature\_key (*requis*) | `String` | Clé du feature que vous voulez exposer à un visiteur. | |
| track (*optionnel*) | `Bool` | Un paramètre optionnel pour activer ou désactiver le suivi de l'évaluation du feature. | `true` |
##### Valeur de retour
| Type | Description |
| ----------- | -------------------------------------------------------------------------------------------- |
| `Variation` | Une [`Variation`](#variation) attribuée à un visiteur donné pour un feature flag spécifique. |
##### Exceptions levées
| 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. |
| `FeatureNotFound` | Exception indiquant que la feature key demandée n'a pas été trouvée dans la configuration interne du SDK. Cela signifie généralement que le feature flag n'est pas activé dans l'application Kameleoon (mais 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). |
#### 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 `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 suit ou non les attributions de variation. Par défaut, il est défini sur `true`. S'il est défini sur `false`, le suivi sera désactivé.
La map renvoyée est composée de clés de feature flag comme clés et de leur `Variation` correspondante comme 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 fait référence à 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, c'est 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 par la variation dans la section "Then, for everyone else..." dans une interface de gestion.
```ruby theme={null}
begin
variations = kameleoon_client.get_variations(visitor_code)
# only active variations
variations = kameleoon_client.get_variations(visitor_code, only_active: true)
# disable tracking
variations = kameleoon_client.get_variations(visitor_code, track: false)
rescue Kameleoon::Exception::VisitorCodeInvalid
# Handle exception
end
```
##### Arguments
| Nom | Type | Description | Par défaut |
| -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------- |
| visitor\_code (*requis*) | `String` | Identifiant unique du visiteur. | |
| only\_active (*optionnel*) | `Bool` | Un paramètre optionnel indiquant s'il faut renvoyer les variations pour les feature flags actifs (`true`) ou tous (`false`). | `false` |
| track (*optionnel*) | `Bool` | Un paramètre optionnel pour activer ou désactiver le suivi de l'évaluation du feature. | `true` |
##### Valeur de retour
| Type | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `Hash` | Map qui contient les objets [`Variation`](#variation) attribués des feature flags en utilisant les clés des features correspondants. |
##### Exceptions levées
| 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. |
#### set\_forced\_variation()
La méthode vous permet d'attribuer par programmation une [`Variation`](#variation) spécifique à un utilisateur, contournant le processus d'évaluation standard. Ceci est particulièrement utile 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 comme 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 targeting et les calculs algorithmiques sont ignorés. Pour préserver les conditions de segmentation et de targeting 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 complété 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 analytics et stockée dans le contexte utilisateur comme toute variation évaluée standard, garantissant la cohérence des rapports.
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 s'assurer 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**.
```ruby theme={null}
experiment_id = 9516
begin
# Forcing the variation "on" for the experiment 9516 for the visitor
kameleoon_client.set_forced_variation(visitor_code, experiment_id, 'on')
# Forcing the variation "on" while preserving segmentation and targeting conditions during the experiment
kameleoon_client.set_forced_variation(visitor_code, experiment_id, 'on', force_targeting: false)
# Resetting the forced variation for the experiment 9516 for the visitor
kameleoon_client.set_forced_variation(visitor_code, experiment_id, nil)
rescue Kameleoon::Exception::KameleoonError => ex
# Handling the exception
end
```
##### Arguments
| Nom | Type | Description | Par défaut | |
| ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| visitor\_code (*requis*) | `String` | Identifiant unique du visiteur. | | |
| experiment\_id (*requis*) | `Integer` | **Experiment Id** qui sera ciblé et sélectionné lors du processus d'évaluation. | | |
| variation\_key (*requis*) | \`String | NilClass\` | **Variation Key** correspondant à une `Variation` qui doit être forcée comme valeur renvoyée pour l'expérience. Si la valeur est `nil`, la variation forcée sera réinitialisée. | |
| force\_targeting (*optionnel*) | `Bool` | Indique si le targeting pour l'expérience doit être forcé et ignoré (`true`) ou appliqué comme dans le processus d'évaluation standard (`false`). | `true` | |
##### Exceptions levées
| 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. |
| `FeatureExperimentNotFound` | Exception indiquant que l'experiment id demandé n'a pas été trouvé dans la configuration interne du SDK. C'est généralement normal et signifie que l'expérience correspondante à la règle n'a pas encore été activée côté Kameleoon. |
| `FeatureVariationNotFound` | Exception indiquant que la clé (id) de variation demandée n'a pas été trouvée dans la configuration interne du SDK. C'est généralement normal et signifie que l'expérience correspondante à la variation n'a pas encore été activée côté Kameleoon. |
Dans la plupart des cas, seule l'erreur de base, `KameleoonError`, doit être gérée, comme démontré dans l'exemple. Cependant, si différents types d'erreurs nécessitent une réponse, gérez chacun séparément en fonction des exigences spécifiques. De plus, pour une fiabilité accrue, les erreurs générales du langage peuvent être gérées en incluant `StandardError`.
#### evaluate\_audiences()
* 📨 *Envoie des données de tracking à Kameleoon*
Cette méthode évalue les visiteurs par rapport à tous les segments d'Audiences Explorer disponibles et suit ceux qui correspondent.
`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.
```ruby theme={null}
begin
kameleoon_client.evaluate_audiences(visitor_code)
rescue Kameleoon::Exception::KameleoonError => ex
# Handling the exception
end
```
##### Arguments
| Nom | Type | Description |
| ------------------------ | -------- | ------------------------------- |
| visitor\_code (*requis*) | `String` | Identifiant unique du visiteur. |
##### Exceptions levées
| 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. |
Dans la plupart des cas, seule l'erreur de base, `KameleoonError`, doit être gérée, comme démontré dans l'exemple. Cependant, si différents types d'erreurs nécessitent une réponse, gérez chacun séparément en fonction des exigences spécifiques. De plus, pour une fiabilité accrue, les erreurs générales du langage peuvent être gérées en incluant `StandardError`.
#### get\_data\_file()
Pour évaluer tous les feature flags, utilisez [`get_variations()`](#get_variations). Cette méthode est plus efficace que d'appeler `DataFile` et d'itérer sur les flags avec [`get_variation()`](#get_variation).
Renvoie la configuration actuelle du SDK sous forme d'objet [`DataFile`](#datafile).
```ruby theme={null}
begin
datafile = kameleoon_client.get_data_file
rescue StandardError => e
# Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
end
```
##### Valeur de retour
| Type | Description |
| ---------- | ------------------------------------------------------------ |
| `DataFile` | Le [`DataFile`](#datafile) contenant la configuration du SDK |
### Données visiteur
#### get\_visitor\_code()
Précédemment appelé `obtain_visitor_code` - supprimé depuis la version `3.0.0` du SDK.
Appelez la méthode d'assistance `get_visitor_code` pour obtenir le **visitor\_code** Kameleoon pour le visiteur actuel. Cette méthode est importante lors de l'utilisation de Kameleoon dans un environnement mixte front-end et back-end, où la précision de l'identification de l'utilisateur doit être garantie. La logique d'implémentation est la suivante :
1. Vérifier la présence d'un cookie **kameleoonVisitorCode** ou d'un paramètre de requête associé à la requête HTTP actuelle. S'il est trouvé, l'utiliser comme identifiant de visiteur.
2. Si aucun cookie ou paramètre n'est trouvé, vérifier l'argument **default\_visitor\_code**. S'il est trouvé, l'utiliser comme identifiant. `default_visitor_code_` permet à nos clients d'utiliser leurs propres identifiants comme visitor codes s'ils le souhaitent, ce qui peut avoir l'avantage supplémentaire de faire correspondre les visiteurs Kameleoon avec leurs propres utilisateurs sans aucune consultation supplémentaire dans une table de correspondance.
3. Si aucun cookie, paramètre ou argument n'est trouvé, générer aléatoirement un identifiant unique.
Dans tous les cas, le cookie **kameleoonVisitorCode** côté serveur (via en-tête HTTP) est défini avec la valeur. Lors des visites ultérieures, l'identifiant que vous définissez est la valeur renvoyée par la méthode.
Pour plus d'informations, consultez [cet article](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/).
Si vous fournissez votre propre `visitor_code`, vous devez en garantir l'unicité - le SDK ne peut pas la vérifier. Notez également que la longueur du `visitor_code` est limitée à **255** caractères. Tout caractère excédentaire entraînera une exception.
La méthode `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 des 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 à l'aide du [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 un fonctionnement correct, la valeur du cookie doit être encodée comme un composant URI à l'aide d'une méthode telle que [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent).
```ruby theme={null}
visitor_code = kameleoon_client.get_visitor_code(cookies)
visitor_code = kameleoon_client.get_visitor_code(cookies, default_visitor_code)
```
##### Arguments
| Nom | Type | Description |
| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cookies | Hash | Les cookies de la requête HTTP actuelle doivent être transmis sous forme d'objet Hash (`{:cookie_name => cookie_value}`). Si vous utilisez Rails, vous pouvez transmettre la variable **cookies**. Ce champ est obligatoire. |
| default\_visitor\_code | String | Ce paramètre sera utilisé comme **visitor\_code** si aucun cookie **kameleoonVisitorCode** existant n'est trouvé dans la requête. Ce champ est optionnel et, par défaut, un **visitor\_code** aléatoire sera généré. |
##### Valeur de retour
| Type | Description |
| ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| String | Un **visitor\_code** qui sera associé à cet utilisateur particulier et qui doit être utilisé avec la plupart des méthodes du SDK. |
#### add\_data()
La méthode `add_data()` ajoute des [données de targeting](#types-de-données) au stockage afin que les autres méthodes puissent utiliser ces données pour décider de cibler ou non le visiteur actuel.
La méthode `add_data()` ne renvoie aucune valeur et n'interagit pas avec les serveurs back-end Kameleoon par elle-même. Au lieu de cela, toutes les données déclarées sont enregistrées pour une transmission future via la méthode [`flush()`](#flush). Cette approche réduit le nombre d'appels serveur effectués, car les données sont généralement regroupées en un seul appel serveur déclenché par `flush()`.
La méthode [`track_conversion()`](#track_conversion) envoie également toutes les données précédemment associées, tout comme `flush()`. Il en va de même pour les méthodes [`get_variation()`](#get_variation) et [`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.
```ruby theme={null}
require "kameleoon"
require "kameleoon/data"
# Add a single data item (tracked by default)
kameleoon_client.add_data(visitor_code, Kameleoon::Browser.new(Kameleoon::BrowserType::CHROME))
# Add multiple data items (tracked by default)
kameleoon_client.add_data(
visitor_code,
Kameleoon::PageView.new("https://url.com", "title", [3]),
Kameleoon::UserAgent("UserAgent")
)
# Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
kameleoon_client.add_data(
visitor_code,
Kameleoon::Data::PageView.new("https://url.com", "title", [3]),
Kameleoon::Data::UserAgent.new("UserAgent"),
track: false
)
```
##### Arguments
| Nom | Type | Description | Valeur par défaut |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| visitor\_code (*requis*) | `String` | Identifiant unique du visiteur. | |
| data (*requis*) | `*Data` | Collection de types de données Kameleoon. | |
| track (*optionnel*) | `Bool` | Spécifie si les données ajoutées sont éligibles au suivi. Lorsqu'il est défini sur `false`, les données sont stockées localement et utilisées uniquement pour l'évaluation du targeting ; elles ne sont pas envoyées à l'API Kameleoon Data. | `true` |
##### Exceptions
| 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. |
#### flush()
* 📨 *Envoie des données de tracking à Kameleoon*
`flush()` prend les données Kameleoon associées au visiteur et toutes les données qui ont été ajoutées précédemment via la méthode `add_data`, qui n'ont pas encore été envoyées lors de l'appel de l'une de [ces méthodes](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics), et envoie une requête de tracking. `flush()` est non bloquante, car l'appel serveur est effectué de manière asynchrone.
`flush()` vous permet de contrôler quand les données associées à un `visitor_code` donné sont envoyées à nos serveurs. Par exemple, si vous appelez `add_data()` une douzaine de fois, il serait inefficace d'envoyer des données au serveur chaque fois que `add_data()` est invoqué, vous n'avez donc qu'à appeler `flush()` une seule fois à la fin.
Si vous spécifiez un `visitor_code`, la méthode `flush()` l'utilise comme identifiant unique du visiteur, ce qui est utile pour l'[expérimentation cross-device](/developer-docs/cross-device-experimentation). Lorsque vous spécifiez un `visitor_code` et définissez le paramètre `is_unique_identifier` sur `true`, le SDK lie les données vidées au visiteur associé à l'identifiant spécifié.
Le paramètre `is_unique_identifier` est obsolète. Veuillez utiliser [`UniqueIdentifier`](#uniqueidentifier) à la place.
Le `is_unique_identifier` peut également être utile dans d'autres scénarios particuliers, par exemple lorsque vous ne pouvez pas accéder au `visitorCode` anonyme qui a été initialement attribué au visiteur, mais vous avez accès à un ID interne qui est connecté au visiteur anonyme grâce aux capacités de fusion de sessions.
```ruby theme={null}
require "kameleoon"
require "kameleoon/data"
visitor_code = kameleoon_client.get_visitor_code(cookies)
kameleoon_client.add_data(visitor_code, Kameleoon::Browser.new(Kameleoon::BrowserType::CHROME))
kameleoon_client.add_data(
visitor_code,
Kameleoon::PageView.new("https://url.com", "title", [3]),
Kameleoon::Interest.new(0)
)
kameleoon_client.add_data(visitor_code, Kameleoon::Conversion.new(32, 10, false))
kameleoon_client.flush(visitor_code) # Interval tracking (most performant way for tracking)
kameleoon_client.flush(visitor_code, instant: true) # Instant tracking
# if you operate with unique ID
kameleoon_client.add_data(Kameleoon::UniqueIdentifier.new(true))
kameleoon_client.flush(visitor_code)
```
##### Arguments
| Nom | Type | Description |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | String | Identifiant unique de l'utilisateur. Ce champ est obligatoire. |
| is\_unique\_identifier | Boolean | Lorsque `true`, le SDK lie les données vidées au visiteur associé à l'identifiant spécifié. |
| instant | Boolean | Indicateur booléen indiquant si les données doivent être envoyées instantanément (`true`) ou selon l'intervalle de tracking planifié (`false`). Ce champ est optionnel. |
#### get\_remote\_data()
Précédemment nommé : `retrieve_data_from_remote_source` - supprimé depuis la version `3.0.0` du SDK.
La méthode `get_remote_data()` vous permet de récupérer des données (selon une **clé** transmise en argument) pour un **siteCode** spécifié (spécifié dans `Kameleoon::KameleoonClientFactory.create()`) stockées sur un serveur distant Kameleoon. Habituellement, les données sont stockées sur nos serveurs distants à l'aide de notre API Data. Cette méthode, ainsi que la disponibilité de nos serveurs hautement évolutifs à cet effet, offre un moyen pratique de stocker des quantités massives de données qui peuvent être récupérées pour chacun de vos visiteurs/utilisateurs.
```ruby theme={null}
kameleoon_client.get_remote_data('test') # default timeout
kameleoon_client.get_remote_data('test', 1000) # 1000 milliseconds timeout
begin
kameleoon_client.get_remote_data('test')
rescue => e
#catch error
end
```
##### Arguments
| Nom | Type | Description |
| ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | String | La clé à laquelle les données que vous essayez de récupérer sont associées. Ce champ est obligatoire. |
| timeout | Integer | Délai d'expiration (en millisecondes). Ce paramètre spécifie le temps maximum pendant lequel la méthode peut bloquer pour attendre un résultat. Ce champ est optionnel ; s'il n'est pas fourni, il utilisera la valeur `default_timeout` du fichier de configuration ou 2000 millisecondes si elle n'est pas spécifiée dans le fichier. |
##### Valeur de retour
| Type | Description |
| ---- | ---------------------------------------------------------------------------- |
| Hash | Objet Hash associé à la récupération de données pour une **clé** spécifique. |
##### Exceptions levées
| Type | Description |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Error | Erreur indiquant que la requête a expiré ou que les données récupérées ne peuvent pas être analysées avec la méthode `JSON.parse()`. |
#### get\_remote\_visitor\_data()
`get_remote_visitor_data()` est une méthode asynchrone pour récupérer les données de visite Kameleoon pour le `visitor_code` depuis l'API Kameleoon Data. La méthode stocke les données pour que d'autres méthodes puissent les utiliser lors de la prise de décisions de targeting.
Les données obtenues à l'aide de cette méthode jouent un rôle important lorsque vous souhaitez :
* utiliser des données collectées sur d'autres appareils.
* accéder à l'historique d'un utilisateur, telles que les pages précédemment visitées lors de visites passées.
* utiliser des données qui ne sont accessibles que côté client, comme les variables de datalayer et les objectifs qui ne convertissent que côté front-end.
Lisez [cet article](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) pour une meilleure compréhension des cas d'utilisation possibles.
Par défaut, `get_remote_visitor_data()` récupère automatiquement les dernières custom data stockées avec `scope=Visitor` et les attache au visiteur sans avoir à appeler la méthode `add_data()`. C'est particulièrement utile pour [synchroniser les custom data entre plusieurs appareils](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices).
Le paramètre `is_unique_identifier` est obsolète. Veuillez utiliser [`UniqueIdentifier`](#uniqueidentifier) à la place.
Le `is_unique_identifier` peut également être utile dans d'autres scénarios particuliers, par exemple lorsque vous ne pouvez pas accéder au `visitorCode` anonyme qui a été initialement attribué au visiteur, mais vous avez accès à un ID interne qui est connecté au visiteur anonyme grâce aux capacités de fusion de sessions.
```ruby theme={null}
visitor_code = 'visitorCode'
# Visitor data will be fetched and automatically added for `visitor_code`
data_array = kameleoon_client.get_remote_visitor_data(visitor_code) # default timeout
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, 1000) # 1 second timeout
# If you only want to fetch data and add it yourself manually, set `add_data` to `false`
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, add_data: false) # default timeout
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, 1000, add_data: false) # 1 second timeout
# If you want to fetch custom list of data types
filter = RemoteVisitorDataFilter(25, customData: false, conversions: true, experiments: true)
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, filter: filter)
# If you want to the SDK to link the extracted data with the visitor associated with the specified identifier
kameleoon_client.add_data(Kameleoon::UniqueIdentifier.new(true))
data_array = kameleoon_client.get_remote_visitor_data(visitor_code)
```
##### Arguments
| Nom | Type | Description |
| --------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | String | Le visitor code pour lequel vous souhaitez récupérer les données attribuées. Ce champ est obligatoire. |
| timeout | Integer | Délai d'expiration (en millisecondes). Ce paramètre spécifie le temps maximum pendant lequel la méthode peut bloquer pour attendre un résultat. Ce champ est optionnel ; s'il n'est pas fourni, il utilise la valeur `default_timeout` du fichier de configuration ou 2000 millisecondes si elle n'est pas spécifiée dans le fichier. |
| add\_data | Boolean | Un booléen indiquant si la méthode doit ajouter automatiquement les données récupérées pour un visiteur. S'il n'est pas spécifié, la valeur par défaut est **true**. Ce champ est optionnel. |
| filter | `Kameleoon::Types::RemoteVisitorDataFilter` | Filtre qui spécifie quelles données doivent être récupérées des visites. Par défaut, seules les `CustomData` sont récupérées de la visite actuelle et de la dernière visite précédente (`RemoteVisitorDataFilter.new(previousVisitAmount: 1, currentVisit: true, customData: true)` ou `RemoteVisitorDataFilter.new`). Les autres paramètres de filtre sont définis sur `false`. Ce champ est optionnel. |
| is\_unique\_identifier (Obsolète) | Boolean | Un paramètre optionnel pour spécifier si le visitorCode est un identifiant unique. S'il n'est pas fourni, la valeur par défaut est `false`. Le champ est optionnel. |
##### Valeur de retour
| Type | Description |
| ----- | --------------------------------------------------- |
| Array | Un tableau de données attribuées au visiteur donné. |
##### Utilisation des paramètres dans get\_remote\_visitor\_data()
La méthode `get_remote_visitor_data()` offre une flexibilité en vous permettant de définir divers paramètres lors de la récupération des données du visiteur. Que vous cibliez en fonction d'objectifs, d'expériences ou de variations, la même approche s'applique à tous les types de données.
Par exemple, supposons que vous souhaitiez récupérer des données sur les visiteurs qui ont complété un objectif "Order transaction". Vous pouvez spécifier des paramètres dans la méthode `get_remote_visitor_data()` pour affiner votre targeting. Par exemple, si vous voulez cibler uniquement les utilisateurs qui ont converti sur l'objectif lors de leurs cinq dernières visites, vous pouvez définir le paramètre `previous_visit_amount` sur 5 et `conversions` sur true.
La flexibilité illustrée dans cet exemple n'est pas limitée aux données d'objectif. Vous pouvez utiliser des paramètres dans la méthode `get_remote_visitor_data()` pour récupérer des données sur une variété de comportements de visiteurs.
Voici la liste des options `Kameleoon::Types::RemoteVisitorDataFilter` disponibles :
| Nom | Type | Description | Par défaut |
| ------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| previous\_visit\_amount (*optionnel*) | `Integer` | Nombre de visites précédentes à partir desquelles récupérer les données. Nombre entre `1` et `25` | `1` |
| current\_visit (*optionnel*) | `Boolean` | Si true, les données de la visite actuelle seront récupérées | `true` |
| custom\_data (*optionnel*) | `Boolean` | Si true, les custom data seront récupérées. | `true` |
| page\_views (*optionnel*) | `Boolean` | Si true, les données de page seront récupérées. | `false` |
| geolocation (*optionnel*) | `Boolean` | Si true, les données de géolocalisation seront récupérées. | `false` |
| device (*optionnel*) | `Boolean` | Si true, les données d'appareil seront récupérées. | `false` |
| browser (*optionnel*) | `Boolean` | Si true, les données du navigateur seront récupérées. | `false` |
| operating\_system (*optionnel*) | `Boolean` | Si true, les données du système d'exploitation seront récupérées. | `false` |
| conversions (*optionnel*) | `Boolean` | Si true, les données de conversion seront récupérées. | `false` |
| experiments (*optionnel*) | `Boolean` | Si true, les données d'expérience seront récupérées. | `false` |
| kcs (*optionnel*) | `Boolean` | Si true, le Kameleoon Conversion Score (KCS) sera récupéré. Nécessite l'[add-on AI Predictive Targeting](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) | `false` |
| visitor\_code (*optionnel*) | `Boolean` | Si true, Kameleoon récupérera le `visitorCode` de la visite la plus récente et l'utilisera pour la visite actuelle. Cela est nécessaire si vous voulez vous assurer que le visiteur, identifié par son `visitorCode`, reçoit toujours la même variation entre les visites pour l'[expérimentation cross-device](/developer-docs/cross-device-experimentation). | `true` |
| personalization (*optionnel*) | `Boolean` | Si true, les données de personnalisation seront récupérées. Cela est requis pour la condition de personnalisation. | `false` |
| cbs (*optionnel*) | `Boolean` | Si true, les données de score Contextual Bandit seront récupérées. | `false` |
#### get\_visitor\_warehouse\_audience()
Récupère toutes les données d'audience associées au visiteur dans votre data warehouse en utilisant le `visitor_code` et le `warehouse_key` spécifiés. Le `warehouse_key` est généralement votre ID utilisateur interne. Le paramètre `custom_data_index` correspond à la custom data Kameleoon que Kameleoon utilise pour cibler vos visiteurs. Vous pouvez vous référer à la [documentation de warehouse targeting](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) pour plus de détails. La méthode renvoie un objet `CustomData`, confirmant que les données ont été ajoutées au visiteur et sont disponibles à des fins de targeting.
```ruby theme={null}
begin
warehouse_audience_data = kameleoon_client.get_visitor_warehouse_audience(visitor_code, custom_data_index) # default timeout
warehouse_audience_data = kameleoon_client.get_visitor_warehouse_audience(visitor_code, custom_data_index, 1000) # 1 second timeout
warehouse_audience_data = kameleoon_client.get_visitor_warehouse_audience(visitor_code, custom_data_index, warehouse_key: warehouse_key) # default timeout
warehouse_audience_data = kameleoon_client.get_visitor_warehouse_audience(visitor_code, custom_data_index, 1000, warehouse_key: warehouse_key) # 1 second timeout
# Your custom code
rescue => e
# Handle exception
end
```
##### Arguments
| Nom | Type | Description |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | String | Une chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères. |
| custom\_data\_index | Integer | Un entier représentant l'index de la custom data que vous voulez utiliser pour cibler vos audiences BigQuery. |
| warehouse\_key | String | Une clé unique pour identifier les données du warehouse (généralement votre ID utilisateur interne). Ce champ est optionnel. |
| timeout | Integer | Délai d'expiration (en millisecondes). Ce paramètre spécifie le temps maximum à attendre pour un résultat. Ce champ est optionnel. S'il n'est pas fourni, la valeur par défaut est de 10000 millisecondes. |
##### Valeur de retour
| Type | Description |
| ----------------------- | ------------------------------------------------------------------------------------- |
| `Kameleoon::CustomData` | Une instance de `CustomData` confirmant que les données ont été ajoutées au visiteur. |
##### Exceptions levées
| Type | Description |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Kameleoon::Exception::VisitorCodeInvalid | Exception indiquant que le visitor code fourni est invalide (soit vide, soit plus long que 255 caractères). |
| StandardError | Exception indiquant que la requête a expiré ou toute autre raison d'échec. |
#### set\_legal\_consent()
Vous devez utiliser cette méthode pour spécifier si le visiteur a donné son consentement légal pour l'utilisation de données personnelles. Définir le paramètre `consent` sur `false` limite les types de données que vous pouvez inclure dans les requêtes de tracking. Cette méthode vous aide à respecter les exigences légales et réglementaires tout en gérant de manière responsable les données des visiteurs. Vous trouverez plus d'informations sur les données personnelles dans la [politique de gestion du consentement](/user-manual/project-management/consent-management-policy).
```ruby theme={null}
visitor_code = kameleoon_client.get_visitor_code(cookies)
kameleoon_client.set_legal_consent(visitor_code, true, cookies)
```
##### Arguments
| Nom | Type | Description |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | String | L'identifiant unique de l'utilisateur. Ce champ est requis. |
| consent | Bool | Une valeur booléenne représentant le statut du consentement légal. `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. Ce champ est requis. |
| cookies | Hash | La réponse HTTP où les valeurs dans les cookies seront ajustées en fonction du statut du consentement légal. Ce champ est optionnel. |
##### Exceptions levées
| Type | Description |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Kameleoon::Exception::VisitorCodeInvalid | Exception indiquant que le visitor code fourni est invalide. Il est soit vide, soit plus long que 255 caractères. |
##### Comportement de révocation du consentement
Lorsque vous appelez `set_legal_consent()` avec `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é exigent la suppression immédiate du fichier cookie lors de l'opt-out, vous devez le supprimer manuellement à l'aide des méthodes natives de gestion des cookies de votre framework. Le SDK ne supprimera pas le fichier automatiquement.
### Objectifs et analytics tiers
#### 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 nécessite `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.
La méthode `track_conversion()` ne renvoie aucune valeur. Cette méthode est non bloquante car l'appel serveur est effectué de manière asynchrone.
Le paramètre `isUniqueIdentifier` est obsolète. Veuillez utiliser [`UniqueIdentifier`](#uniqueidentifier) à la place.
Le `isUniqueIdentifier` peut également être utile dans d'autres scénarios particuliers, par exemple lorsque vous ne pouvez pas accéder au `visitor_code` anonyme qui a été initialement attribué au visiteur, mais vous avez accès à un ID interne qui est connecté au visiteur anonyme grâce aux capacités de fusion de sessions.
```ruby theme={null}
require "kameleoon"
require "kameleoon/data/page_view"
require "kameleoon/data/browser"
require "kameleoon/data/conversion"
visitor_code = kameleoon_client.get_visitor_code(cookies)
goal_id = 83023
kameleoon_client.add_data(visitor_code, Kameleoon::Conversion.new(32, 10, false))
kameleoon_client.track_conversion(visitor_code, goal_id)
# Add metadata
cd = Kameleoon::CustomData.new(1, "metadata");
kameleoon_client.track_conversion(visitorCode, goalId, metadata: [cd])
```
##### Arguments
| Nom | Type | Description | Par défaut |
| ------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| visitor\_code (*requis*) | `String` | Identifiant unique du visiteur. | |
| goal\_id (*requis*) | `Integer` | ID de l'objectif. | |
| revenue (*optionnel*) | `Float` | Revenu de la conversion. | `0` |
| negative (*optionnel*) | `Bool` | Définit si le revenu est positif ou négatif. | `false` |
| metadata (*optionnel*) | `Array` | Vous permet de définir des valeurs spécifiques pour les custom data qui ont été définies comme métadonnées pour l'objectif dans l'application Kameleoon. Exemple : `[CustomData{id: 5, value: "Payment Type"}, CustomData{id: 6, value: "Delivery Method"}]`. Dans cet exemple, `5` et `9` sont les index des custom data (5 = "Payment Type", 9 = "Delivery Method"). | `nil` |
| isUniqueIdentifier *(obsolète)* | `Bool` | Un paramètre optionnel pour spécifier si le visitor\_code est un identifiant unique. | `false` |
Les valeurs de metadata 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 actuelle au lieu de ce qui a été précédemment collecté via la méthode [`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 qui sont explicitement transmises en paramètres à la méthode `track_conversion()`.
Dans l'exemple ci-dessous, Kameleoon n'associera la conversion qu'à la valeur de custom data explicitement fournie en paramètre (ici : index 5 avec la valeur 'Amex Credit Card').
```ruby theme={null}
kameleoon_client.add_data(visitor_code, Kameleoon::CustomData.new(5, "Credit Card"), Kameleoon::CustomData.new(9, "Express Delivery"))
kameleoon_client.track_conversion(visitor_code, 10, metadata: [Kameleoon::CustomData.new(5, "Amex Credit Card")])
```
##### Exceptions
| 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\_engine\_tracking\_code()
Kameleoon s'intègre à plusieurs solutions d'analytics, notamment Mixpanel, Google Analytics 4 et Segment. Pour suivre correctement les expériences côté serveur, appelez la méthode `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'analytics 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.
```ruby theme={null}
engine_tracking_code = kameleoon_client.get_engine_tracking_code(visitor_code)
```
* Pour utiliser cette fonctionnalité, implémentez à la fois le SDK Ruby et Kameleoon [Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation). Comme Engine.js n'est utilisé que pour le tracking dans ce flow, vous pouvez installer le tag asynchrone avant la balise de fermeture ``.
* Si vous voulez uniquement suivre les expériences dans Kameleoon et n'avez pas besoin d'envoyer des événements d'exposition à des outils d'analytics tiers, utilisez le [SDK JavaScript / TypeScript](/developer-docs/sdks/web-sdks/js-sdk). Cette option fonctionne bien pour les [plateformes serverless edge compute](/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), tant que vous ajoutez les attributions d'expérience correspondantes à `window.kameleoonQueue`..
* Vous pouvez insérer le code de tracking renvoyé directement dans une balise HTML `