> ## 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 Python
> Intégrez le SDK Python de Kameleoon pour exécuter des expériences et activer des feature flags sur des serveurs back-end Python, y compris dans des environnements Django.
Avec le SDK Python, vous pouvez exécuter des expériences et activer des feature flags sur votre serveur back-end Python. 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 vous aider à démarrer, consultez le [guide du développeur](#guide-du-développeur).
**Changelog** : Dernière version du SDK Python : 3.18.0 [Changelog](https://github.com/Kameleoon/client-python/blob/main/CHANGELOG.md).
**Méthodes du SDK** : Pour la documentation de référence complète du SDK Python, consultez la section [référence](#référence).
## Guide du développeur
Ce guide est conçu pour vous aider à intégrer notre SDK en quelques minutes et à commencer à exécuter des expériences dans vos applications Python. Ce tutoriel expliquera la configuration d'un simple A/B test pour modifier le nombre de produits recommandés en fonction des différentes variations.
### Pour commencer
#### Installation du client Python
Vous pouvez installer le SDK à l'aide d'un package pip Python. Notre package est hébergé sur le dépôt pip officiel, il vous suffit donc d'exécuter la commande suivante :
```python theme={null}
pip install kameleoon-client-python
```
#### Configuration supplémentaire
Vous devez fournir les identifiants pour le SDK Python via un fichier de configuration, que vous pouvez également utiliser pour personnaliser le comportement du SDK. Un exemple de fichier de configuration [peut être obtenu ici](/assets/developer-docs/sdks/web-sdks/client-configs/client-python.yaml). Nous suggérons d'installer ce fichier dans le chemin par défaut `/etc/kameleoon/client-python.yaml`, mais vous pouvez le placer à un autre emplacement et passer le chemin en argument à la méthode constructrice `KameleoonClient()`. Avec la version actuelle du SDK Python, voici les clés disponibles :
| Clé | Description | Valeur par défaut |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `client_id` (*obligatoire*) | 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` (*obligatoire*) | 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 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 actives et des feature flags. La valeur détermine le temps maximum nécessaire pour propager les changements, tels que 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 pousser automatiquement les nouvelles configurations vers le SDK et appliquer ces 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 provenant du SDK. Définissez la valeur à 30 secondes ou plus si vous n'avez pas de connexion stable. Certaines méthodes disposent d'un paramètre supplémentaire que vous pouvez utiliser pour remplacer le délai d'expiration 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é flushé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 aussi 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 [gestion des environnements](/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 top-level domain actuel de votre site. Utilisez le format : `example.com`. N'incluez pas `https://`, `www`, ni d'autres sous-domaines. Kameleoon utilise cette information pour définir le cookie correspondant sur le top-level domain. | `""` |
| `network_domain` (*optionnel*) | Domaine personnalisé utilisé par les SDK pour les requêtes sortantes, souvent à des fins de proxy. Doit être un domaine valide (par exemple, example.com ou sub.example.com). Les formats invalides reviennent par défaut à la valeur de Kameleoon. | `None` |
| `logger` *(déprécié)* | Permet de remplacer le logger Python par défaut. Ce champ est déprécié et sera supprimé dans la version `4.0.0` du SDK. Utilisez [`KameleoonLogger.set_logger()`](#logging) à la place. | `logging.Logger` |
| `multi_threading` *(déprécié)* | Une option de type `bool` indiquant si les threads peuvent être utilisés pour les requêtes réseau. Par défaut, tout est exécuté dans un seul thread pour éviter les problèmes de performance avec le GIL si l'interpréteur (C)Python est utilisé. Valeurs possibles : `True`, `False`. | `None` |
Vous pouvez également utiliser `configuration_object` de type `KameleoonClientConfig` comme paramètre lors de l'initialisation. Il a la même liste d'arguments qu'un fichier de configuration. `configuration_object` est prioritaire sur le fichier de configuration et écrase ses paramètres.
#### Initialisation du client Kameleoon
Après avoir installé le SDK dans votre application, configuré les bons identifiants (dans `/etc/kameleoon/client-python.yaml`) et configuré une expérience côté serveur dans le back-office Kameleoon, l'étape suivante consiste à créer le client Kameleoon dans le code de votre application.
Le code à droite donne un exemple clair. Un `KameleoonClient` est un objet singleton qui agit comme un pont entre votre application et la plateforme Kameleoon. Il inclut toutes les méthodes et propriétés dont vous aurez besoin pour exécuter une expérience.
Les développeurs sont responsables d'assurer la logique correcte de leur code applicatif lors de la mise en œuvre de l'A/B testing avec Kameleoon. Une bonne pratique consiste à toujours supposer qu'un visiteur peut être exclu de l'expérience si elle n'a pas encore été lancée. Cette pratique est simple à mettre en œuvre, car elle s'aligne sur la logique par défaut ou de référence de variation, qui doit toujours être en place. Les exemples de code de la section suivante illustrent cette approche.
```python theme={null}
from kameleoon import KameleoonClient, KameleoonClientConfig, KameleoonClientFactory
SITE_CODE = 'a8st4f59bj'
# Option 1
kameleoon_client = KameleoonClientFactory.create(SITE_CODE, config_path='/etc/kameleoon/client-python.yaml')
# Option 2
configuration_object = KameleoonClientConfig.read_from_yaml('/etc/kameleoon/client-python.yaml')
configuration_object.set_top_level_domain("example.com")
kameleoon_client = KameleoonClientFactory.create(SITE_CODE, configuration_object)
# Option 3
configuration_object = KameleoonClientConfig(
"client_id", # required
"client_secret", # required
refresh_interval_minute=60, # (in minutes) optional, default: 60 minutes
session_duration_minute=30, # (in minutes) optional, default: 30 minutes
default_timeout_millisecond=10000, # (in milliseconds) optional, default: 10000 milliseconds
tracking_interval_millisecond=1000, # (in milliseconds) optional, default: 1000 milliseconds
environment="production", # optional, possible values: "production" / "staging" / "development" / "staging", default: None
top_level_domain="example.com",
multi_threading=False, # optional, default: False
logger=my_logger, # optional, default: standard kameleoon logger. This field is deprecated and will be removed in SDK version `4.0.0`. Use `KameleoonLogger.set_logger` instead.
network_domain="example.com", # optional
)
kameleoon_client = KameleoonClientFactory.create(SITE_CODE, configuration_object)
```
#### Activation d'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 (à partir du 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` (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 [`get_variation()`](#get_variation) ou [`is_feature_active()`](#is_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 retournant en fonction de la `feature_key` et du `visitor_code`.
La méthode `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 aux feature flags plus complexes avec plusieurs variations ou options de ciblage.
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 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 [`tracking_interval_millisecond`](#configuration-supplémentaire) 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. Ceci est utile si vous préférez ne pas suivre les données via le SDK et plutôt vous fier au 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 `get_variations()`, où vous pourriez avoir besoin des variations pour 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 data points pour cibler un utilisateur ou filtrer / décomposer les visites dans les rapports
Pour cibler un utilisateur, assurez-vous d'avoir ajouté les data points 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 data points au profil de l'utilisateur.
Pour récupérer des data points 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 de manière asynchrone à partir des serveurs. 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 ciblage disponibles, consultez [l'article détaillé sur le sujet](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
De plus, les data points 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 tels que l'appareil et le navigateur. Le mode hybride de Kameleoon collecte automatiquement une variété de data points côté client, facilitant la décomposition de vos résultats sur la base de ces data points pré-collectés. Voir la liste complète [ici](/fr/user-manual/experiment-analytics/analyze-results/results-page/results-page-settings#ventiler-l’audience).
Si vous avez besoin de suivre des data points supplémentaires au-delà de ce qui est automatiquement collecté, 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 [`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 en utilisant le 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 [`track_conversion()`](#track_conversion) et fournissez les paramètres requis `visitor_code` et `goal_id`.
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_millisecond`](#configuration-supplémentaire)). 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 vers des solutions analytics
Pour suivre les conversions et envoyer les é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 nécessaire 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 à la plateforme d'analytics de votre choix.
### Utilisation du SDK Python Kameleoon dans un environnement Django
Si vous utilisez Django, nous vous recommandons d'initialiser le client Kameleoon au démarrage du serveur, dans le fichier `apps.py` de votre application Django.
Lorsque vous utilisez python manage.py runserver, Django démarre deux processus : un pour le serveur de développement réel, et l'autre pour recharger votre application lorsque le code change.
Vous pouvez également démarrer le serveur sans l'option de rechargement, et vous ne verrez qu'un seul processus en cours d'exécution. Le processus n'est exécuté qu'une seule fois :
`python manage.py runserver --noreload`
Vous pouvez également vérifier la variable d'environnement RUN\_MAIN dans la méthode `ready()`.
```python theme={null}
def ready(self):
if os.environ.get('RUN_MAIN', None) == 'true':
configuration_path = os.path.join(ROOT_DIR, 'path_to_config', 'config.yml')
self.kameleoon_client = KameleoonClientFactory.create(SITE_CODE, config_path=configuration_path)
```
Cela ne s'applique qu'au développement local lorsque vous utilisez python manage.py runserver. Dans un environnement de production, le code de la fonction `ready()` ne sera exécuté qu'une seule fois lors de l'initialisation de l'application.
```python theme={null}
from django.apps import apps
my_application = apps.get_app_config('your_app')
client = my_application.kameleoon_client
```
Vous pouvez ensuite accéder au client Kameleoon dans votre application.
Un autre avantage de l'utilisation de Django est que le SDK lira et écrira automatiquement le **visitor\_code** sur la requête/réponse HTTP via un cookie. Si vous utilisez un autre framework dans un environnement web où vous souhaiteriez utiliser un mécanisme de cookies pour persister le **visitor\_code**, vous devez fournir des implémentations des méthodes `read_cookies()` et `write_cookies()`.
### 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 de leurs appareils et la réconciliation de leur historique de visites entre 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 appareils sont disponibles dans l'[article sur l'expérimentation cross-device](/developer-docs/cross-device-experimentation).
#### Synchronisation des custom data entre appareils
Bien que la synchronisation par mapping personnalisé soit utilisée pour aligner les données des visiteurs entre les appareils, elle n'est pas toujours nécessaire. Voici deux scénarios dans lesquels la synchronisation par mapping personnalisé n'est pas requise :
**Même user ID sur tous les appareils**
Si le même user ID est utilisé de manière cohérente sur tous les appareils, la synchronisation est gérée automatiquement sans synchronisation par mapping personnalisé. Il suffit d'appeler la méthode `get_remote_visitor_data()` lorsque vous souhaitez synchroniser les données collectées entre plusieurs appareils.
**Instances multi-serveurs avec ID cohérents**
Dans des configurations complexes impliquant plusieurs serveurs (par exemple, des instances de serveurs distribuées), où le même user ID est disponible entre les serveurs, la synchronisation entre les serveurs (avec `get_remote_visitor_data()`) est suffisante sans synchronisation par mapping personnalisé supplémentaire.
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 souhaitez synchroniser les données collectées en temps réel, vous devez choisir la portée **Visitor** pour votre custom data.
```python 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(VISITOR_SCOPE_CUSTOM_DATA_INDEX, "your data"))
kameleoon_client.flush(visitor_code)
```
```python 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.
```
#### Utilisation des 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 de l'historique). La réconciliation de l'historique permet de fusionner différentes sessions de visiteurs 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 de [`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 des pages 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 [activation de la réconciliation de l'historique cross-device](#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 `UniqueIdentifier(True)` ajouté - pour suivre certaines données pour un visiteur spécifique qui est associé à un autre visiteur.
Comme la custom data que vous utilisez comme identifiant doit être définie sur la portée **Visitor**, vous devez utiliser la [synchronisation cross-device des custom data](/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.
```python 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(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(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 a une page de connexion. Comme l'user ID est inconnu au moment de la connexion, un identifiant anonyme de visiteur généré par la méthode [`get_visitor_code()`](#get_visitor_code) est utilisé. Une fois l'utilisateur connecté, le visiteur anonyme est associé à l'user ID 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 les 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 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 pourriez avoir besoin de vous assurer 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'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 flag, en particulier dans ces situations :
* **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 comme un `account_id`. 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 :
```python theme={null}
from kameleoon.data import CustomData
kameleoon_client.add_data(visitor_code, CustomData(index, "new_visitor_code"))
```
* **Fourniture de 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 votre clé de bucketing personnalisée choisie en tant qu'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 de la création ou de l'édition 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 `add_data()`, tous les calculs de hash 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 analytics :** 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` *original*.** Cette séparation garantit que vos analytics reflètent avec précision les parcours individuels des utilisateurs et les interactions 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 de 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 `str`.
* Elle doit être unique pour l'entité que vous souhaitez bucketer (par exemple, si vous utilisez un `user_id`, 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 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 visites 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).
### Logging
Le SDK génère des logs pour refléter divers processus internes et problèmes.
#### Niveaux de log
Le SDK prend en charge la configuration de la limitation du logging par un niveau de log.
```python theme={null}
from kameleoon.logging.log_level import LogLevel
from kameleoon.logging.kameleoon_logger import KameleoonLogger
# The `NONE` log level does not allow logging.
KameleoonLogger.set_log_level(LogLevel.NONE)
# The `ERROR` log level only allows logging issues that may affect the SDK's main behaviour.
KameleoonLogger.set_log_level(LogLevel.ERROR)
# The `WARNING` log level allows logging issues which may require additional attention.
# It extends the `ERROR` log level.
# The `WARNING` log level is a default log level.
KameleoonLogger.set_log_level(LogLevel.WARNING)
# The `INFO` log level allows logging general information on the SDK's internal processes.
# It extends the `WARNING` log level.
KameleoonLogger.set_log_level(LogLevel.INFO)
# The `DEBUG` level logs additional details about the SDK’s internal processes and extends the `INFO` level
# with more granular. diagnostic output.
# This information is not intended for end-user interpretation but can be sent to our support team
# to assist with internal troubleshooting.
KameleoonLogger.set_log_level(LogLevel.DEBUG)
```
#### Gestion personnalisée des logs
Le SDK écrit ses logs sur la sortie console par défaut. Ce comportement peut être remplacé.
La limitation du logging par un niveau de log est effectuée indépendamment de la logique de gestion des logs.
```python theme={null}
from loguru import logger
from kameleoon.logging.log_level import LogLevel
from kameleoon.logging.logger import Logger
class CustomLogger(Logger):
"""Custom logger implementation using loguru."""
def log(self, level: LogLevel, message: str) -> None:
"""Accepts logs from the SDK"""
if level == LogLevel.ERROR:
logger.error(message)
elif level == LogLevel.WARNING:
logger.warning(message)
elif level == LogLevel.INFO:
logger.info(message)
elif level == LogLevel.DEBUG:
logger.debug(message)
from kameleoon.logging.kameleoon_logger import KameleoonLogger
# Log level filtering is applied separately from log handling logic.
# The custom logger will only accept logs that meet or exceed the specified log level.
# Ensure the log level is set correctly.
KameleoonLogger.set_logger(CustomLogger())
KameleoonLogger.set_log_level(LogLevel.DEBUG) # Optional, defaults to `LogLevel.WARNING`.
```
## Référence
Voici la documentation de référence complète du SDK Python.
#### create()
Pour commencer à utiliser le SDK, vous devez compléter l'initialisation. Toutes les interactions avec le SDK se font via un objet appelé `Kameleoon::KameleoonClient`, la première chose à faire est donc de créer cet objet.
```python theme={null}
kameleoon_config = KameleoonClientConfig("client_id", "client_secret")
kameleoon_client = KameleoonClientFactory.create("a8st4f59bj", kameleoon_config)
kameleoon_client = KameleoonClientFactory.create("a8st4f59bj", config_path="/etc/kameleoon/client-ruby.yaml")
```
##### Arguments
| Nom | Type | Description |
| ------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| site\_code | str | C'est 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. |
| config | KameleoonClientConfig | Objet de configuration du SDK que vous pouvez passer au lieu d'utiliser un fichier de configuration. Ce champ est optionnel. |
| config\_path | str | Chemin vers le fichier de configuration du SDK. Ce champ est optionnel. La valeur par défaut est `/etc/kameleoon/client-ruby.yaml` |
##### Exceptions levées
| Type | Description |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| SiteCodeIsEmpty | Exception indiquant que le site code spécifié est une chaîne vide, ce qui est une valeur invalide. |
| ConfigFileNotFound | Exception indiquant que le fichier de configuration n'a pas été trouvé. |
#### wait\_init\_async()
`wait_init_async` attend de manière asynchrone l'initialisation du client Kameleoon. Cette méthode vous permet de vérifier si le client a été initialisé avec succès avant de poursuivre d'autres opérations.
```python theme={null}
kameleoon_client = KameleoonClientFactory.create('a8st4f59bj')
if await kameleoon_client.wait_init_async():
# The SDK has been initialized; you can fetch a feature flag / experiment configuration here.
```
##### Valeur de retour
| Type | Description |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Coroutine\[Any, Any, bool] | Une coroutine qui retourne `True` si l'instance du client Kameleoon a été initialisée avec succès, sinon `False`. |
#### wait\_init()
`wait_init` attend de manière synchrone l'initialisation du client Kameleoon. Cette méthode vous permet de vérifier si le client a été initialisé avec succès avant de poursuivre d'autres opérations.
```python theme={null}
kameleoon_client = KameleoonClientFactory.create('a8st4f59bj')
if kameleoon_client.wait_init():
# The SDK has been initialized; you can fetch a feature flag / experiment configuration here.
```
##### Valeur de retour
| Type | Description |
| ------ | -------------------------------------------------------------------------------------- |
| `bool` | `True` si l'instance du client Kameleoon a été initialisée avec succès, sinon `False`. |
### Feature flags et variations
#### is\_feature\_active()
* 📨 *Envoie des données de tracking à Kameleoon (selon le paramètre `track`)*
Anciennement appelée `activate_feature` — dépréciée depuis la version `2.1.0` du SDK et sera supprimée dans une future version.
Pour vérifier si le feature flag est actif pour un visiteur, appelez la méthode `is_feature_active()`.
Cette méthode prend un **visitor\_code** et une **feature\_key** comme arguments obligatoires pour vérifier si le feature sera actif pour un utilisateur donné.
Si un tel utilisateur n'a jamais été associé à ce feature flag, le SDK retourne une valeur booléenne de manière aléatoire (**true** si le feature sera actif pour l'utilisateur, ou **false** sinon). 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 **feature flag**.
Vous devez vous assurer qu'une gestion d'erreurs appropriée 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 `is_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 flushées au visiteur associé à l'identifiant spécifié.
Le paramètre `is_unique_identifier` est déprécié. 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 `visitor_code` anonyme initialement attribué au visiteur, mais que vous avez accès à un ID interne qui est connecté au visiteur anonyme via les fonctionnalités de fusion de sessions.
Kameleoon utilise le tracking pour compter les sessions et les visiteurs lorsque vous appelez certaines méthodes, telles que `is_feature_active()`, `get_variation()` ou `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 `get_variations()` pour récupérer toutes les variations avant d'exposer les visiteurs, définissez le paramètre `track` sur `False`. Ce paramétrage empêche Kameleoon de compter prématurément une session. Vous pouvez ensuite déclencher le tracking plus tard lorsque vous exposez explicitement le visiteur.
Kameleoon envoie les données de tracking toutes les secondes par défaut. Vous pouvez configurer cet intervalle jusqu'à cinq secondes en utilisant 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 compte 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.
```python theme={null}
visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)
feature_key = "new_checkout"
has_new_checkout = False
try
has_new_checkout = kameleoon_client.is_feature_active(visitor_code, feature_key)
# disabling tracking
has_new_checkout = kameleoon_client.is_feature_active(visitor_code, feature_key, track=False)
except FeatureNotFound as ex:
# The user will not be counted in the experiment,
# but should see the reference variation.
has_new_checkout = False
except VisitorCodeInvalid as ex:
# The visitor code you passed to the method isn't valid and can't be accepted by SDK.
has_new_checkout = False
if has_new_checkout
# Implement new checkout code here
```
La méthode `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 retourne toujours `false` même lorsque le master feature flag est sur **On**.
##### Arguments
| Nom | Type | Description |
| --------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | Identifiant unique de l'utilisateur. Ce champ est obligatoire. |
| feature\_key | str | ID ou Clé du feature que vous souhaitez exposer à un utilisateur. Ce champ est obligatoire. |
| is\_unique\_identifier (Déprécié) | Optional\[bool] | Lorsqu'il est défini sur `True`, le SDK lie les données flushées au visiteur associé à l'identifiant spécifié. |
| track | bool | Un paramètre optionnel pour activer ou désactiver le tracking de l'évaluation du feature (`True` par défaut). |
##### Valeur de retour
| Type | Description |
| ---- | ---------------------------------------------------------------------- |
| bool | Valeur du feature qui est enregistrée pour un **visitor\_code** donné. |
##### Exceptions levées
| Type | Description |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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é du côté de Kameleoon (mais le code implémentant la fonctionnalité est déjà déployé du côté de l'application web). |
| VisitorCodeInvalid | Exception indiquant que le visitor code fourni n'est pas valide (vide ou supérieur à 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 est `True` par défaut.
Elle retourne la `Variation` attribuée au visiteur. Si le visiteur n'est associé à aucune règle de feature flag, la méthode retourne la `Variation` par défaut pour le feature flag donné.
Assurez-vous qu'une gestion d'erreurs appropriée 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..." de l'interface de gestion.
```python theme={null}
feature_key = "new_checkout"
try:
variation = kameleoon_client.get_variation(visitor_code, feature_key)
# disabling tracking
variation = kameleoon_client.get_variation(visitor_code, feature_key, False)
except FeatureNotFound as ex:
# The error has occurred; the feature flag isn't found in current configuration.
except FeatureEnvironmentDisabled as ex:
# The feature flag is disabled for the environment.
except VisitoCodeNotValid as ex:
# The visitor code you passed to the method is invalid and can't be accepted by SDK.
# Fetch a variable value for the assigned variation
title = variation.variables["title"].value
if variation.key == "on":
# Main variation key is selected for visitorCode
elif variation.key == "alternative_variation":
# Alternative variation key
else:
# Default variation key
```
##### Arguments
| Nom | Type | Description | Par défaut |
| ----------------------------- | ------ | ----------------------------------------------------------------------------------------- | ---------- |
| visitor\_code (*obligatoire*) | `str` | Identifiant unique du visiteur. | |
| feature\_key (*obligatoire*) | `str` | Clé du feature que vous souhaitez exposer à un visiteur. | |
| track (*optionnel*) | `bool` | Un paramètre optionnel pour activer ou désactiver le tracking 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 supérieur à 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 retourne 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()` retournera 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 variation. 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 de feature flag keys comme clés et de leur `Variation` correspondante comme valeurs. Si aucune variation n'est attribuée pour un feature flag, la méthode retourne la `Variation` par défaut pour ce flag.
Une gestion d'erreurs appropriée 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..." de l'interface de gestion.
```python theme={null}
try:
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)
except VisitorCodeInvalid as ex:
# Handle exception
```
##### Arguments
| Nom | Type | Description | Par défaut |
| ----------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- | ---------- |
| visitor\_code (*obligatoire*) | `str` | Identifiant unique du visiteur. | |
| only\_active (*optionnel*) | `bool` | Un paramètre optionnel indiquant s'il faut retourner 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 tracking de l'évaluation du feature. | `True` |
##### Valeur de retour
| Type | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `Dict[str, Variation]` | 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 supérieur à 255 caractères. |
#### 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).
Retourne la configuration actuelle du SDK sous forme d'objet [`DataFile`](#datafile).
```python theme={null}
data_file = kameleoon_client.get_data_file()
date_modified = data_file.date_modified
```
##### Valeur de retour
| Type | Description |
| ---------- | ------------------------------------------------------------ |
| `DataFile` | Le [`DataFile`](#datafile) contenant la configuration du SDK |
#### set\_forced\_variation()
La méthode vous permet d'attribuer programmatiquement une [`Variation`](#variation) spécifique à un utilisateur, en contournant le processus d'évaluation standard. Cela est particulièrement utile pour les expériences contrôlées où la logique d'évaluation habituelle n'est pas nécessaire 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. Des 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 `force_targeting=False` à la place.
Les variations **simulées** prennent 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, assurant la cohérence des rapports.
La méthode peut lever des exceptions sous 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**.
```python theme={null}
experiment_id = 9516
try:
# 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", False)
# Resetting the forced variation for the experiment 9516 for the visitor
kameleoon_client.set_forced_variation(visitor_code, experiment_id, None)
except KameleoonError as e:
# Handling the error
```
##### Arguments
| Nom | Type | Description | Par défaut |
| ------------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| visitor\_code (*obligatoire*) | `str` | Identifiant unique du visiteur. | |
| experiment\_id (*obligatoire*) | `int` | **Experiment Id** qui sera ciblé et sélectionné pendant le processus d'évaluation. | |
| variation\_key (*obligatoire*) | `Optional[str]` | **Variation Key** correspondant à une `Variation` qui doit être forcée comme valeur retournée pour l'expérience. Si la valeur est `None`, la variation forcée sera réinitialisée. | |
| force\_targeting (*optionnel*) | `bool` | Indique si le ciblage 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 supérieur à 255 caractères. |
| `FeatureExperimentNotFound` | Exception indiquant que l'experiment id demandé n'a pas été trouvé dans la configuration interne du SDK. Ceci est généralement normal et signifie que l'expérience correspondante à la règle n'a pas encore été activée du côté de Kameleoon. |
| `FeatureVariationNotFound` | Exception indiquant que la variation key (id) demandée n'a pas été trouvée dans la configuration interne du SDK. Ceci est généralement normal et signifie que l'expérience correspondante à la variation n'a pas encore été activée du côté de Kameleoon. |
Dans la plupart des cas, seule l'erreur de base, `KameleoonError`, doit être gérée, comme illustré dans l'exemple. Cependant, si différents types d'erreurs nécessitent une réponse, gérez chacun séparément en fonction des besoins spécifiques. De plus, pour une fiabilité accrue, les erreurs générales du langage peuvent être gérées en incluant `Exception`.
#### 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 aient é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 actuelles 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.
```python theme={null}
try:
kameleoon_client.evaluate_audiences(visitor_code)
except KameleoonError as e:
# Handling the error
```
##### Arguments
| Nom | Type | Description |
| ----------------------------- | ----- | ------------------------------- |
| visitor\_code (*obligatoire*) | `str` | 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 supérieur à 255 caractères. |
Dans la plupart des cas, seule l'erreur de base, `KameleoonError`, doit être gérée, comme illustré dans l'exemple. Cependant, si différents types d'erreurs nécessitent une réponse, gérez chacun séparément en fonction des besoins spécifiques. De plus, pour une fiabilité accrue, les erreurs générales du langage peuvent être gérées en incluant `Exception`.
### Données visiteur
#### get\_visitor\_code()
Cette méthode s'appelait auparavant `obtain_visitor_code`, qui a été supprimée dans la version `3.0.0` du SDK.
La méthode utilitaire `get_visitor_code()` doit être appelée pour obtenir le **visitor\_code** Kameleoon du visiteur actuel. Cette méthode est particulièrement importante lors de l'utilisation de Kameleoon dans un environnement mixte front-end et back-end, où la cohérence de l'identification de l'utilisateur doit être garantie. La logique d'implémentation est décrite ici :
1. Tout d'abord, nous vérifions si un cookie ou paramètre de requête **kameleoonVisitorCode** associé à la requête HTTP actuelle peut être trouvé. Si oui, nous l'utiliserons comme identifiant du visiteur.
2. Si aucun cookie/paramètre n'est trouvé dans la requête actuelle, nous générons soit un nouvel identifiant aléatoirement, soit utilisons l'argument **default\_visitor\_code** comme identifiant s'il est passé. Cela permet à nos clients d'utiliser leurs propres identifiants comme visitor codes, s'ils le souhaitent, ce qui présente l'avantage supplémentaire de faire correspondre les visiteurs Kameleoon à leurs propres utilisateurs sans aucune recherche supplémentaire dans une table de correspondance.
3. Dans tous les cas, le cookie **kameleoonVisitorCode** côté serveur (via l'en-tête HTTP) est défini avec la valeur. Ensuite, cette valeur d'identifiant est finalement retournée par la méthode.
Si vous fournissez votre propre `visitor_code`, vous devez garantir son unicité. Le SDK ne valide pas la valeur passée en argument. Notez également que la longueur du `visitor_code` est limitée à **255** caractères. Une exception `VisitorCodeInvalid` est levée si cette limite est dépassée.
La méthode `get_visitor_code()` vous permet de définir des variations **simulées** pour un visiteur. Lorsque les cookies (provenant 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 retourne 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 d'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 le cookie `kameleoonSimulationFFData` manuellement.
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 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).
```python theme={null}
### if you use KameleoonWSGIMiddleware service
visitor_code = kameleoon_client.get_visitor_code(cookies_readonly=request.COOKIES)
kameleoon_client.set_legal_consent(visitor_code, True)
### if you want to manage cookies manually
simple_cookies = SimpleCookie()
simple_cookies.load(cookie_header)
visitor_code = kameleoon_client.get_visitor_code(cookies=simple_cookies, default_visitor_code=default_visitor_code)
cookie_header = simple_cookies.output()
```
##### Arguments
| Nom | Type | Description |
| ---------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cookies\_readonly | Optional\[Dict\[str, str]] | Dictionnaire en lecture seule, généralement `request.COOKIES`. Utilisez ce paramètre si vous utilisez également le service `KameleoonWSGIMiddleware`. Ce champ est optionnel. |
| cookies | Optinal\[Dict\[str, http.cookies.Morsel\[str]]] | Passez les cookies sur la requête HTTP actuelle sous forme d'objet `Dict[str, http.cookies.Morsel[str]]` ou `http.cookies.\|SimpleCookie[str]` si vous gérez les cookies manuellement sans le service `KameleoonWSGIMiddleware`. Ce champ est optionnel. |
| default\_visitor\_code | str | 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 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------- |
| str | Un **visitor\_code** qui sera associé à cet utilisateur particulier et qui doit être utilisé avec la plupart de nos méthodes SDK. |
##### Exceptions levées
| Type | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| VisitorCodeInvalid | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit supérieur à 255 caractères. |
#### add\_data()
La méthode `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 de cibler ou non le visiteur actuel.
La méthode `add_data()` ne retourne 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 sauvegardées pour une transmission ultérieure 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 le `flush()`.
La méthode [`track_conversion()`](#track_conversion) envoie également toutes les données précédemment associées, tout comme le `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 associée de `CustomData` par index.
```python theme={null}
require "kameleoon"
require "kameleoon/data"
# Add a single data item (tracked by default)
kameleoon_client.add_data(visitor_code, Browser(BrowserType.CHROME))
# Add multiple data items (tracked by default)
kameleoon_client.add_data(
visitor_code,
PageView("https://url.com", "title", [3]),
UserAgent("UserAgent")
)
# Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
kameleoon_client.add_data(
visitor_code,
PageView("https://url.com", "title", [3]),
UserAgent("UserAgent"),
track=False
)
```
##### Arguments
| Nom | Type | Description | Valeur par défaut |
| ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| visitor\_code (*obligatoire*) | `str` | Identifiant unique du visiteur. | |
| data (*obligatoire*) | `*Data` | Collection de types de données Kameleoon. | |
| track (*optionnel*) | `bool` | Spécifie si les données ajoutées sont éligibles au tracking. Lorsqu'il est défini 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 Kameleoon Data. | `True` |
##### Exceptions
| Type | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit supérieur à 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 bloquant, 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 appel de `add_data()`, 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 flushées au visiteur associé à l'identifiant spécifié.
Le paramètre `is_unique_identifier` est déprécié. 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 `visitor_code` anonyme initialement attribué au visiteur, mais que vous avez accès à un ID interne qui est connecté au visiteur anonyme via les fonctionnalités de fusion de sessions.
```python theme={null}
kameleoon_client.add_data(visitor_code, Browser(BrowserType.CHROME))
kameleoon_client.add_data(
visitor_code,
PageView("https://url.com", "title", [3]),
CustomData(0, "value")
)
kameleoon_client.add_data(visitor_code, Conversion(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(UniqueIdentifier(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 (Déprécié) | Optional\[bool] | Lorsque `True`, le SDK lie les données flushées au visiteur associé à l'identifiant spécifié. |
| instant | bool | Indicateur booléen indiquant si les données doivent être envoyées instantanément (`True`) ou selon l'intervalle de tracking planifié (`False`). S'il n'est pas fourni, la valeur par défaut est `False`. Ce champ est optionnel. |
#### get\_remote\_data()
* Anciennement appelée `retrieve_data_from_remote_source`, qui a été supprimée dans la version `3.0.0` du SDK.
* Si vous souhaitez récupérer des données de manière asynchrone, utilisez plutôt la méthode `get_remote_data_async` (disponible depuis la version 2.3.0).
La méthode `get_remote_data` récupère des données de manière synchrone (selon une **clé** passée en argument) pour un **site\_code** spécifié (spécifié avec `KameleoonClient.__init__`) stocké sur un serveur Kameleoon distant. Les données sont généralement stockées sur nos serveurs distants via notre Data API. Cette méthode, associée à la disponibilité de nos serveurs hautement évolutifs à cet effet, fournit une méthode pratique pour stocker des quantités massives de données qui peuvent être récupérées pour chacun de vos visiteurs/utilisateurs.
```python theme={null}
kameleoon_client.get_remote_data('key1') # default timeout
kameleoon_client.get_remote_data('key2', 1.0) # 1 second timeout
```
##### Arguments
| Nom | Type | Description |
| ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | str | La clé à laquelle les données sont associées. Ce champ est obligatoire. |
| timeout | Optional\[float] | Délai d'expiration (en secondes). Ce paramètre spécifie le temps maximum pendant lequel la méthode peut bloquer en attendant un résultat. Ce champ est optionnel ; s'il n'est pas fourni, il utilisera la valeur `default_timeout_millisecond` du fichier de configuration, ou deux secondes si elle n'est pas spécifiée dans le fichier. |
##### Valeur de retour
| Type | Description |
| ----------- | ----------------------------------------------------------------------------- |
| JSON object | Objet JSON associé à la récupération des données pour une **clé** spécifique. |
#### get\_remote\_data\_async()
La méthode `get_remote_data_async` vous permet de récupérer des données de manière asynchrone (selon une **clé** passée en argument) pour un **site\_code** spécifié (spécifié avec `KameleoonClient.__init__`) stocké sur un serveur Kameleoon distant. Les données sont généralement stockées sur nos serveurs distants via notre Data API. Cette méthode, associée à la disponibilité de nos serveurs hautement évolutifs à cet effet, fournit une méthode pratique pour stocker des quantités massives de données qui peuvent être récupérées pour chacun de vos visiteurs/utilisateurs.
```python theme={null}
await kameleoon_client.get_remote_data_async('key1') # default timeout
await kameleoon_client.get_remote_data_async('key2', 1.0) # 1 second timeout
```
##### Arguments
| Nom | Type | Description |
| ------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | str | La clé à laquelle les données sont associées. Ce champ est obligatoire. |
| timeout | Optional\[float] | Délai d'expiration (en secondes). Ce paramètre spécifie le temps maximum pendant lequel la méthode peut bloquer en attendant un résultat. Ce champ est optionnel ; s'il n'est pas fourni, il utilisera la valeur `default_timeout_millisecond` du fichier de configuration ou deux secondes si elle n'est pas spécifiée dans le fichier. |
##### Valeur de retour
| Type | Description |
| ----------- | ----------------------------------------------------------------------------- |
| JSON object | Objet JSON associé à la récupération des données pour une **clé** spécifique. |
#### get\_remote\_visitor\_data()
`get_remote_visitor_data()` est une méthode asynchrone pour récupérer les Kameleoon Visits Data pour le `visitor_code` depuis l'API Kameleoon Data. La méthode ajoute les données au stockage pour que d'autres méthodes puissent les utiliser lors des décisions de ciblage.
Les données obtenues à l'aide de cette méthode jouent un rôle important lorsque vous souhaitez :
* utiliser des données collectées depuis d'autres appareils.
* accéder à l'historique d'un utilisateur, comme les pages visitées lors de visites passées.
* utiliser des données qui ne sont accessibles que côté client, comme les variables du datalayer et les objectifs qui ne convertissent qu'en front-end.
Lisez [cet article](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) pour mieux comprendre les cas d'usage 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 besoin d'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 déprécié. 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 `visitor_code` anonyme initialement attribué au visiteur, mais que vous avez accès à un ID interne qui est connecté au visiteur anonyme via les fonctionnalités de fusion de sessions.
```python theme={null}
visitor_code = 'visitorCode'
# Visitor data will be fetched and automatically added for `visitor_code`
data_list = kameleoon_client.get_remote_visitor_data(visitor_code) # default timeout
data_list = kameleoon_client.get_remote_visitor_data(visitor_code, timeout=1.0) # 1 second timeout
# If you only want to fetch data and add it yourself manually, set `add_data` to `False`
data_list = kameleoon_client.get_remote_visitor_data(visitor_code, False) # default timeout
data_list = kameleoon_client.get_remote_visitor_data(visitor_code, False, 1.0) # 1 second timeout
# If you want to fetch custom list of data types
data_filter = RemoteVisitorDataFilter(25, customData=False, conversions=True, experiments=True)
data_list = kameleoon_client.get_remote_visitor_data(visitor_code, data_filter=data_filter)
# If you want the SDK to link the extracted data with the visitor associated with the specified identifier.
kameleoon_client.add_data(UniqueIdentifier(True))
data_list = kameleoon_client.get_remote_visitor_data(visitor_code)
```
##### Arguments
| Nom | Type | Description |
| --------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| visitor\_code | str | Le visitor code pour lequel vous souhaitez récupérer les données attribuées. Ce champ est obligatoire. |
| add\_data | bool | 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. |
| data\_filter | 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(previousVisitAmount=1, currentVisit=True, customData=True)` ou `RemoteVisitorDataFilter()`). Les autres paramètres de filtres sont définis sur `False`. Ce champ est optionnel. |
| is\_unique\_identifier (Déprécié) | Optional\[bool] | 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`. Ce champ est optionnel. |
| timeout | Optional\[float] | Délai d'expiration (en secondes). Ce paramètre spécifie le temps maximum pendant lequel la méthode peut bloquer en attendant un résultat. Ce champ est optionnel ; s'il n'est pas fourni, il utilisera la valeur `default_timeout_millisecond` du fichier de configuration ou deux secondes si elle n'est pas spécifiée dans le fichier. |
##### Utilisation des paramètres dans get\_remote\_visitor\_data()
La méthode `get_remote_visitor_data()` offre de la flexibilité en vous permettant de définir divers paramètres lors de la récupération de données sur les visiteurs. Que vous cibliez en fonction des objectifs, des expériences ou des 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é l'objectif "Order transaction". Vous pouvez spécifier des paramètres dans la méthode `get_remote_visitor_data()` pour affiner votre ciblage. Par exemple, si vous souhaitez 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` à 5 et `conversions` à true.
La flexibilité montrée dans cet exemple ne se limite pas 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.
##### Valeur de retour
| Type | Description |
| ----------- | -------------------------------------------------- |
| List\[Data] | Une liste de données attribuées au visiteur donné. |
Voici la liste des options `Kameleoon::Configuration::RemoteVisitorDataFilter` disponibles :
| Nom | Type | Description | Par défaut |
| ------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| previous\_visit\_amount (*optionnel*) | `int` | Nombre de visites précédentes pour lesquelles récupérer les données. Nombre entre `1` et `25` | `1` |
| current\_visit (*optionnel*) | `bool` | Si True, les données de la visite actuelle seront récupérées | `True` |
| custom\_data (*optionnel*) | `bool` | Si True, les custom data seront récupérées. | `True` |
| page\_views (*optionnel*) | `bool` | Si True, les données de page seront récupérées. | `False` |
| geolocation (*optionnel*) | `bool` | Si True, les données de géolocalisation seront récupérées. | `False` |
| device (*optionnel*) | `bool` | Si True, les données d'appareil seront récupérées. | `False` |
| browser (*optionnel*) | `bool` | Si True, les données de navigateur seront récupérées. | `False` |
| operating\_system (*optionnel*) | `bool` | Si True, les données du système d'exploitation seront récupérées. | `False` |
| conversions (*optionnel*) | `bool` | Si True, les données de conversion seront récupérées. | `False` |
| experiments (*optionnel*) | `bool` | Si True, les données d'expérience seront récupérées. | `False` |
| kcs (*optionnel*) | `bool` | 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*) | `bool` | Si true, Kameleoon récupérera le `visitorCode` de la visite la plus récente et l'utilisera pour la visite actuelle. Ceci est nécessaire si vous souhaitez 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` |
| cbs (*optionnel*) | `bool` | Si true, les données de Contextual Bandit score seront récupérées. | `False` |
| personalization (*optionnel*) | `bool` | Si True, les données de personnalisation seront récupérées. Ceci est requis pour la condition de personnalisation. | `False` |
#### get\_remote\_visitor\_data\_async()
La méthode `get_remote_visitor_data_async` récupère de manière asynchrone les custom data stockées dans les serveurs Kameleoon distants pour un visiteur (spécifié à l'aide de l'argument **visitor\_code**). Si **add\_data** est **True**, cette méthode ajoute automatiquement les données récupérées à un visiteur sans nécessiter d'appel `add_data` séparé.
Vous devez avoir préalablement stocké des données sur nos serveurs distants, que vous pouvez ajouter avec l'un des appels de tracking suivants dans le SDK :
* `flush`
* `get_feature_variation_key`
* `get_feature_variable`
* `is_feature_active`
L'utilisation de la méthode `get_remote_visitor_data` associée à la disponibilité de nos serveurs hautement évolutifs fournit une méthode pratique pour accéder et synchroniser de grandes quantités de données sur tous les appareils du visiteur.
Si vous spécifiez un `visitor_code`, la méthode `get_remote_visitor_data_async` 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 flushées au visiteur associé à l'identifiant spécifié.
Le paramètre `is_unique_identifier` est déprécié. 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 `visitor_code` anonyme initialement attribué au visiteur, mais que vous avez accès à un ID interne qui est connecté au visiteur anonyme via les fonctionnalités de fusion de sessions.
```python theme={null}
visitor_code = 'visitorCode'
# Visitor data will be fetched and automatically added for `visitor_code`
data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code) # default timeout
data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code, timeout=1.0) # 1 second timeout
# If you only want to fetch data and add it yourself manually, set `add_data` to `False`
data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code, False) # default timeout
data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code, False, 1.0) # 1 second timeout
# If you want to fetch custom list of data types
data_filter = RemoteVisitorDataFilter(25, customData=False, conversions=True, experiments=True)
data_list = kameleoon_client.get_remote_visitor_data(visitor_code, data_filter=data_filter)
# If you want the SDK to link the extracted data with the visitor associated with the specified identifier.
kameleoon_client.add_data(UniqueIdentifier(True))
data_list = kameleoon_client.get_remote_visitor_data(visitor_code)
```
##### Arguments
| Nom | Type | Description |
| --------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| visitor\_code | str | Le visitor code pour lequel vous souhaitez récupérer les données attribuées. Ce champ est obligatoire. |
| add\_data | bool | 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. |
| data\_filter | 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(previousVisitAmount=1, currentVisit=True, customData=True)` ou `RemoteVisitorDataFilter()`). Les autres paramètres de filtres sont définis sur `False`. Ce champ est optionnel. |
| is\_unique\_identifier (Déprécié) | Optional\[bool] | 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. |
| timeout | Optional\[float] | Délai d'expiration (en secondes). Ce paramètre spécifie le temps maximum pendant lequel la méthode peut bloquer en attendant un résultat. Ce champ est optionnel ; s'il n'est pas fourni, il utilisera la valeur `default_timeout_millisecond` du fichier de configuration ou deux secondes si elle n'est pas spécifiée dans le fichier. |
##### Valeur de retour
| Type | Description |
| ----------- | -------------------------------------------- |
| List\[Data] | Une liste de données attribuées au visiteur. |
##### Utilisation des paramètres dans get\_remote\_visitor\_data\_async()
La méthode `get_remote_visitor_data_async()` offre de la flexibilité en vous permettant de définir divers paramètres lors de la récupération de données sur les visiteurs. Que vous cibliez en fonction des objectifs, des expériences ou des 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é l'objectif "Order transaction". Vous pouvez spécifier des paramètres dans la méthode `get_remote_visitor_data_async()` pour affiner votre ciblage. Par exemple, si vous souhaitez 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` à 5 et `conversions` à true.
La flexibilité montrée dans cet exemple ne se limite pas aux données d'objectif. Vous pouvez utiliser des paramètres dans la méthode `get_remote_visitor_data_async()` pour récupérer des données sur une variété de comportements de visiteurs.
Voici la liste des options `Kameleoon::Configuration::RemoteVisitorDataFilter` disponibles :
| Nom | Type | Description | Par défaut |
| ------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| previous\_visit\_amount (*optionnel*) | `int` | Nombre de visites précédentes pour lesquelles récupérer les données. Nombre entre `1` et `25` | `1` |
| current\_visit (*optionnel*) | `bool` | Si True, les données de la visite actuelle seront récupérées | `True` |
| custom\_data (*optionnel*) | `bool` | Si True, les custom data seront récupérées. | `True` |
| page\_views (*optionnel*) | `bool` | Si True, les données de page seront récupérées. | `False` |
| geolocation (*optionnel*) | `bool` | Si True, les données de géolocalisation seront récupérées. | `False` |
| device (*optionnel*) | `bool` | Si True, les données d'appareil seront récupérées. | `False` |
| browser (*optionnel*) | `bool` | Si True, les données de navigateur seront récupérées. | `False` |
| operating\_system (*optionnel*) | `bool` | Si True, les données du système d'exploitation seront récupérées. | `False` |
| conversions (*optionnel*) | `bool` | Si True, les données de conversion seront récupérées. | `False` |
| experiments (*optionnel*) | `bool` | Si True, les données d'expérience seront récupérées. | `False` |
| kcs (*optionnel*) | `bool` | 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*) | `bool` | Si true, Kameleoon récupérera le `visitorCode` de la visite la plus récente et l'utilisera pour la visite actuelle. Ceci est nécessaire si vous souhaitez 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` |
| cbs (*optionnel*) | `bool` | Si true, les données de Contextual Bandit score seront récupérées. | `False` |
#### get\_visitor\_warehouse\_audience()
Récupère de manière synchrone toutes les données d'audience associées au visiteur dans votre data warehouse en utilisant le **visitor\_code** et la **warehouse\_key** spécifiés. La **warehouse\_key** est généralement votre user ID 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 ciblage warehouse](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) pour plus de détails. La méthode retourne un objet `CustomData`, confirmant que les données ont été ajoutées au visiteur et sont disponibles à des fins de ciblage.
Si vous souhaitez récupérer les données de manière asynchrone, utilisez plutôt la méthode `get_visitor_warehouse_audience_async`.
```python theme={null}
try:
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, timeout=1.0) # 1 second timeout
warehouse_audience_data = kameleoon_client.\
get_visitor_warehouse_audience(visitor_code, custom_data_index, warehouse_key) # default timeout
warehouse_audience_data = kameleoon_client.\
get_visitor_warehouse_audience(visitor_code, custom_data_index, warehouse_key, 1.0) # 1 second timeout
# Your custom code
except VisitorCodeInvalid as e:
# Handle exception
```
##### Arguments
| Nom | Type | Description |
| ------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | Une chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères. Ce champ est obligatoire. |
| custom\_data\_index | int | Un entier représentant l'index de la custom data que vous souhaitez utiliser pour cibler vos BigQuery Audiences. Ce champ est obligatoire. |
| warehouse\_key | Optional\[str] | Une clé unique identifiant les données du warehouse (généralement votre user ID interne). Ce champ est optionnel. |
| timeout | Optional\[float] | Délai d'expiration (en secondes). Ce paramètre spécifie le temps maximum d'attente d'un résultat. Ce champ est optionnel. S'il n'est pas fourni, la valeur par défaut est de 10 secondes. |
##### Valeur de retour
| Type | Description |
| --------------------- | ---------------------------------------------------------------------------------- |
| Optional\[CustomData] | Une instance `CustomData` confirmant que les données ont été ajoutées au visiteur. |
##### Exceptions levées
| Type | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| VisitorCodeInvalid | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit supérieur à 255 caractères. |
#### get\_visitor\_warehouse\_audience\_async()
Récupère de manière asynchrone toutes les données d'audience associées au visiteur dans votre data warehouse en utilisant le **visitor\_code** et la **warehouse\_key** spécifiés. La **warehouse\_key** est généralement votre user ID 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 ciblage warehouse](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) pour plus de détails. La méthode retourne un objet `CustomData`, confirmant que les données ont été ajoutées au visiteur et sont disponibles à des fins de ciblage.
```python theme={null}
try:
warehouse_audience_data = await kameleoon_client.\
get_visitor_warehouse_audience_async(visitor_code, custom_data_index) # default timeout
warehouse_audience_data = await kameleoon_client.\
get_visitor_warehouse_audience_async(visitor_code, custom_data_index, timeout=1.0) # 1 second timeout
warehouse_audience_data = await kameleoon_client.\
get_visitor_warehouse_audience_async(visitor_code, custom_data_index, warehouse_key) # default timeout
warehouse_audience_data = await kameleoon_client.\
get_visitor_warehouse_audience_async(visitor_code, custom_data_index, warehouse_key, 1.0) # 1 second timeout
# Your custom code
except VisitorCodeInvalid as e:
# Handle exception
```
##### Arguments
| Nom | Type | Description |
| ------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | Une chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères. Ce champ est obligatoire. |
| custom\_data\_index | int | Un entier représentant l'index de la custom data que vous souhaitez utiliser pour cibler vos BigQuery Audiences. Ce champ est obligatoire. |
| warehouse\_key | Optional\[str] | Une clé unique identifiant les données du warehouse (généralement votre user ID interne). Ce champ est optionnel. |
| timeout | Optional\[float] | Délai d'expiration (en secondes). Ce paramètre spécifie le temps maximum d'attente d'un résultat. Ce champ est optionnel. S'il n'est pas fourni, la valeur par défaut est de 10 secondes. |
##### Valeur de retour
| Type | Description |
| --------------------- | ---------------------------------------------------------------------------------- |
| Optional\[CustomData] | Une instance `CustomData` confirmant que les données ont été ajoutées au visiteur. |
##### Exceptions levées
| Type | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| VisitorCodeInvalid | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit supérieur à 255 caractères. |
#### 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 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 pouvez trouver plus d'informations sur les données personnelles dans notre [politique de gestion des consentements](/user-manual/project-management/consent-management-policy).
```python theme={null}
### if you use KameleoonWSGIMiddleware service
visitor_code = kameleoon_client.get_visitor_code(cookies_readonly=request.COOKIES)
kameleoon_client.set_legal_consent(visitor_code, True)
### if you want to manage cookies manually
cookies = http.cookies.SimpleCookie()
cookies.load(cookie_header)
visitor_code = kameleoon_client.get_visitor_code(cookies=cookies)
kameleoon_client.set_legal_consent(visitor_code, True, cookies)
cookie_header = cookies.output()
```
##### 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 en utilisant les méthodes natives de gestion des cookies de votre framework. Le SDK ne supprimera pas le fichier automatiquement.
##### Arguments
| Nom | Type | Description |
| ------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | L'identifiant unique de l'utilisateur. Ce champ est obligatoire. |
| consent | bool | Une valeur booléenne représentant le statut de 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 obligatoire. |
| cookies | Optional\[Dict\[str, http.cookies.Morsel\[str]]] | Les cookies à ajuster en fonction du statut de consentement légal sous forme d'objet `Dict[str, http.cookies.Morsel[str]]` ou `http.cookies.SimpleCookie[str]`. Ce champ est optionnel. |
##### Exceptions levées
| Type | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| VisitorCodeInvalid | Exception indiquant que le visitor code fourni n'est pas valide. Il est soit vide, soit supérieur à 255 caractères. |
#### forget()
La méthode `forget` supprime une instance de `KameleoonClient` du `KameleoonClientFactory` avec le **site\_code** spécifié et libère les ressources utilisées par l'instance de `KameleoonClient`. L'instance de `KameleoonClient` ne doit pas être utilisée après l'appel de la méthode `forget`.
Si vous spécifiez un `visitor_code`, la méthode `track_conversion` 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 flushées au visiteur associé à l'identifiant spécifié.
Le `is_unique_identifier` peut également être utile dans d'autres scénarios particuliers, par exemple lorsque vous ne pouvez pas accéder au `visitor_code` anonyme initialement attribué au visiteur, mais que vous avez accès à un ID interne qui est connecté au visiteur anonyme via les fonctionnalités de fusion de sessions.
```python theme={null}
require "kameleoon"
require "kameleoon/data"
visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)
goal_id = 83023
kameleoon_client.add_data(visitor_code, Browser(BrowserType.CHROME))
kameleoon_client.add_data(
visitor_code,
PageView("https://url.com", "title", [3]),
CustomData(2, "value")
)
kameleoon_client.add_data(visitor_code, Conversion(32, 10, false))
kameleoon_client.track_conversion(visitor_code, goal_id)
```
##### Arguments
| Nom | Type | Description |
| ---------------------- | ------ | --------------------------------------------------------------------------------------------- |
| visitor\_code | String | Identifiant unique de l'utilisateur. Ce champ est obligatoire. |
| goal\_id | int | ID de l'objectif. Ce champ est obligatoire. |
| revenue | float | Revenu de la conversion. Ce champ est optionnel. |
| is\_unique\_identifier | bool | Lorsque `True`, le SDK lie les données flushées au visiteur associé à l'identifiant spécifié. |
### Objectifs et analytics tiers
#### 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 retourne des commandes de queue 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 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.
```python theme={null}
engine_tracking_code = kameleoon_client.get_engine_tracking_code(visitor_code)
```
* Pour utiliser cette fonctionnalité, implémentez à la fois le SDK Python 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 d'événements d'exposition aux 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 retourné directement dans une balise HTML `