> ## 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 JavaScript / TypeScript > Intégrez le SDK JavaScript/TypeScript de Kameleoon pour exécuter des expériences et activer des feature flags dans des applications web côté client. Avec le SDK JavaScript de Kameleoon, vous pouvez exécuter des expériences et activer des feature flags. L'intégration de notre SDK dans votre application web est simple, et son empreinte (utilisation de la mémoire et du réseau) est faible. **Premiers pas** : pour obtenir de l'aide pour démarrer, consultez le [guide du développeur](#guide-du-développeur). **Changelog** : les détails sur la dernière version du SDK JavaScript / TypeScript sont disponibles dans le [changelog](https://github.com/Kameleoon/client-js/blob/main/CHANGELOG.md). **Méthodes du SDK** : pour la documentation de référence complète du SDK JavaScript, consultez la section [référence](#référence). ## Guide du développeur Cette section vous aidera à démarrer et vous présentera certains des concepts les plus avancés. ### Premiers pas #### Installation L'outil d'installation du SDK Kameleoon est la meilleure méthode pour installer rapidement le SDK. L'**installateur de SDK** vous aide à installer le SDK de votre choix, à générer un exemple de code de base et à configurer les [dépendances externes](#dépendances-externes) si nécessaire. Pour utiliser l'outil d'installation du SDK, installez-le et exécutez-le globalement : ```bash theme={null} npm install --global @kameleoon/sdk-installer kameleoon-sdk ``` Ou exécutez-le directement avec `npx` : ```bash theme={null} npx @kameleoon/sdk-installer ``` Vous pouvez également injecter le SDK JavaScript dans votre application sous forme de fichier unique en utilisant la balise `

Hello, World!

``` ```js title="app.js" theme={null} const { KameleoonClient, CustomData } = KameleoonSDK; ``` Pour toujours utiliser la dernière version d'une version majeure, utilisez le script suivant, où `4` est la [version majeure actuelle](/developer-docs/sdks/versions) : ```html theme={null} https://static.kameleoon.com/kameleoonSDK-4-latest.js ``` Pour rester sur une version spécifique, indiquez à la place le numéro de version complet. Par exemple, pour la version `4.24.0`, qui est la version la plus ancienne disponible sous forme de script statique, utilisez ce qui suit : ```html theme={null} https://static.kameleoon.com/kameleoonSDK-4.24.0.js ``` Les versions peuvent être référencées sur la [page des releases](https://github.com/Kameleoon/client-js/releases). Par défaut, le script statique utilise le bundle SDK optimisé, dans lequel les messages de log [`INFO`](#logging) et `DEBUG` sont supprimés pour réduire la taille du bundle. Si vous utilisez `KameleoonLogger.setLogLevel(LogLevel.DEBUG)` ou `KameleoonLogger.setLogLevel(LogLevel.INFO)`, utilisez à la place le script statique `full`. ```html theme={null} https://static.kameleoon.com/kameleoonSDK-4-latest-full.js https://static.kameleoon.com/kameleoonSDK-4.24.0-full.js ``` #### Initialiser le client Kameleoon Voici un guide étape par étape pour configurer le SDK JavaScript pour votre application. ```ts theme={null} import { Environment, KameleoonClient, SDKConfigurationType, } from '@kameleoon/javascript-sdk'; // -- Optional configuration const configuration: Partial = { updateInterval: 20, environment: Environment.Production, cookieDomain: '.example.com', }; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration }); // -- Waiting for the client initialization using `async/await` async function init(): Promise { await client.initialize(); } init(); // -- Waiting for the client initialization using `Promise.then()` client .initialize() .then(() => {}) .catch((error) => {}); ``` ```js theme={null} import { Environment, KameleoonClient } from '@kameleoon/javascript-sdk'; // -- Optional configuration const configuration = { updateInterval: 20, environment: Environment.Production, cookieDomain: '.example.com', }; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration }); // -- Waiting for the client initialization using `async/await` async function init() { await client.initialize(); } init(); // -- Waiting for the client initialization using `Promise.then()` client .initialize() .then(() => {}) .catch((error) => {}); ``` Pour commencer, les développeurs doivent créer un point d'entrée pour le SDK JavaScript en créant une nouvelle instance de Kameleoon Client. Utilisez `KameleoonClient` pour exécuter des expériences de feature et récupérer l'état des feature flags et de leurs variations. L'initialisation de `KameleoonClient` est effectuée de manière asynchrone afin de s'assurer que l'appel à l'API Kameleoon a réussi. Pour l'initialisation, utilisez la méthode [`initialize()`](#initialize). Utilisez `async/await`, `Promise.then()` ou toute autre méthode pour gérer l'initialisation asynchrone du client. ##### Arguments | Name | Type | Description | | -------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | siteCode (*required*) | `string` | Il s'agit d'une [clé unique](/user-manual/faq#how-do-i-find-my-sitecode) du projet Kameleoon que vous utilisez avec le SDK. Ce champ est obligatoire. | | configuration (*optional*) | `Partial` | Configuration du client | | externals (*optional*) | `ExternalsType` | Implémentation externe des dépendances du SDK ([Dépendances externes](#dépendances-externes)) | | stubMode (*optional*) | `boolean` | Lorsqu'il vaut true, le client fonctionne en mode stub et n'effectue aucune opération. Dans ce mode, tous les appels de méthode n'exécutent aucune action, garantissant qu'aucune action externe ni effet de bord ne se produit. | ##### Paramètres de configuration | Name | Type | Description | Default Value | | ----------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | | updateInterval (*optional*) | `number` | Spécifie l'intervalle de rafraîchissement, en minutes, auquel le SDK récupère la configuration des expériences et feature flags actifs. La valeur détermine le temps maximal nécessaire pour propager les changements, tels que l'activation ou la désactivation des feature flags ou le lancement des expériences, vers vos serveurs de production. S'il n'est pas spécifié, l'intervalle par défaut est de 60 minutes. 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 les nouvelles configurations en temps réel, sans délai. | `60` | | environment (*optional*) | `Environment` | environnement du feature flag | `Environment.Production` | | targetingDataCleanupInterval (*optional*) | `number` | intervalle en *minutes* pour le nettoyage des données de ciblage, la valeur minimale est de 1 minute | `undefined` (no cleanup will be performed) | | domain (*optional*) | `string` | [domaine](#informations-sur-le-domaine) auquel appartient le cookie. Obsolète, utilisez plutôt `cookieDomain` | `undefined` | | cookieDomain (*optional*) | `string` | [domaine](#informations-sur-le-domaine) auquel appartient le cookie. | `undefined` | | networkDomain (*optional*) | `string` | domaine personnalisé que les SDK utilisent pour toutes les requêtes réseau sortantes. Couramment utilisé pour le proxying. Le format est `second_level_domain.top_level_domain` (par exemple, `example.com`). Si un format invalide est spécifié, le SDK utilise la valeur Kameleoon par défaut. | `undefined` | | requestTimeout (*optional*) | `number` | délai d'expiration en *millisecondes* pour toutes les requêtes réseau du SDK ; si le délai est dépassé, la requête échoue. | `10_000` (10 seconds) | | trackingInterval (*optional*) | `number` | Spécifie l'intervalle des requêtes de tracking en millisecondes. Tous les visiteurs qui ont été évalués pour un feature flag ou qui avaient des données associées sont inclus dans cette requête de tracking, qui est effectuée une fois par intervalle. La valeur minimale est `100` ms et la valeur maximale est `1_000` ms | `1_000` (1 second) | Le paramètre `domain` est obsolète et sera supprimé dans une prochaine version. Utilisez plutôt `cookieDomain`. | Name | Type | Description | Default Value | | ----------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | updateInterval (*optional*) | `number` | Spécifie l'intervalle de rafraîchissement, en minutes, auquel le SDK récupère la configuration des expériences et feature flags actifs. La valeur détermine le temps maximal nécessaire pour propager les changements, tels que l'activation ou la désactivation des feature flags ou le lancement des expériences, vers vos serveurs de production. S'il n'est pas spécifié, l'intervalle par défaut est de 60 minutes. 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 les nouvelles configurations en temps réel, sans délai. | `60` | | environment (*optional*) | `Environment \| string` | environnement du feature flag | `Environment.Production` | | targetingDataCleanupInterval (*optional*) | `number` | intervalle en *minutes* pour le nettoyage des données de ciblage, la valeur minimale est de 1 minute | `undefined` (no cleanup will be performed) | | cookieDomain (*optional*) | `string` | [domaine](#informations-sur-le-domaine) auquel appartient le cookie. | `undefined` | | networkDomain (*optional*) | `string` | domaine personnalisé que les SDK utilisent pour toutes les requêtes réseau sortantes. Couramment utilisé pour le proxying. Le format est `second_level_domain.top_level_domain` (par exemple, `example.com`). Si un format invalide est spécifié, le SDK utilise la valeur Kameleoon par défaut. | `undefined` | | requestTimeout (*optional*) | `number` | délai d'expiration en *millisecondes* pour toutes les requêtes réseau du SDK ; si le délai est dépassé, la requête échoue immédiatement | `10_000` (10 seconds) | | trackingInterval (*optional*) | `number` | Spécifie l'intervalle des requêtes de tracking en millisecondes. Tous les visiteurs qui ont été évalués pour un feature flag ou qui avaient des données associées sont inclus dans cette requête de tracking, qui est effectuée une fois par intervalle. La valeur minimale est `1_000` ms et la valeur maximale est `5_000` ms | `1_000` (1 second) | | defaultDataFile (*optional*) | `string` | La fonctionnalité `defaultDataFile` garantit que le SDK Kameleoon est toujours **READY** en fournissant une configuration de fallback lorsqu'aucun fichier de données en cache n'existe. Les développeurs peuvent précharger une configuration valide en la récupérant depuis `https://sdk-config.kameleoon.eu/v3/` et en la transmettant comme `defaultDataFile` lors de l'initialisation. Lorsqu'un timestamp `dateModified` (en millisecondes) est fourni et qu'il est plus récent que la version en cache, le SDK utilisera le defaultDataFile au lieu de la version en cache. **Si `dateModified` est omis, le defaultDataFile n'est appliqué que lorsqu'aucune version en cache n'existe**. Cela garantit que le SDK dispose toujours d'une configuration valide, qu'elle soit par défaut, en cache ou mise à jour. | `undefined` | **Option 1 (recommandée) :** utilisez `JSON.stringify()` ```js theme={null} const dataFileJson = {"configuration":{"consentType":....., {"key":"show_car","type":"JSON","value":"{\"make\":\"Porsche\",\"model\":\"911\"}"}}, "dateModified":1752209266000}; const dataFileString = JSON.stringify(dataFileJson); const configuration = { updateInterval: 20, defaultDataFile: dataFileString }; ``` **Option 2 :** chaîne JSON brute (échapper les caractères spéciaux) ```js theme={null} const configuration = { updateInterval: 20, defaultDataFile: `{"configuration":{"consentType":....., {"key":"show_car","type":"JSON","value":"{\\"make\\":\\"Porsche\\",\\"model\\":\\"911\\"}"}, "dateModified":1752209266000}` }; ``` N'utilisez pas plusieurs instances de client dans une même application, car ce n'est pas encore totalement pris en charge. Plusieurs instances de client peuvent entraîner l'écrasement de la configuration du stockage local et provoquer des bugs. #### 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 [`getVisitorCode()`](#getvisitorcode). Si un **visitor code** n'existe pas (depuis le cookie des en-têtes de requête), la méthode génère un ID unique aléatoire ou utilise un `defaultVisitorCode` 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), l'appel à la méthode `getVisitorCode()` 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 l'état ou la variation d'un feature flag pour un utilisateur spécifique, vous devez utiliser la méthode [`getVariation()`](#getvariation) ou [`isFeatureFlagActive()`](#isfeatureflagactive) afin de récupérer la configuration basée sur la `featureKey`. La méthode `getVariation()` 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 de la feature, en attribuant la variation, et en la renvoyant en fonction de la `featureKey` et du `visitorCode`. La méthode `isFeatureFlagActive()` peut être utilisée si vous souhaitez récupérer la configuration d'un feature flag simple n'ayant qu'un état ON ou OFF, par opposition aux feature flags plus complexes avec plusieurs variations ou options de ciblage. If your feature flag has associated variables (such as specific behaviors tied to each variation) `getVariation()` also enables you to access the [`Variation`](#variation) object, which provides details about the assigned variation and its associated experiment. This method checks whether the user is targeted, finds the visitor’s assigned variation, and saves it to storage. When `track=true`, the SDK will send the exposure event to the specified experiment on the next tracking request, which is automatically triggered based on the SDK’s [`tracking_interval_millisecond`](#configuration-parameters). By default, this interval is set to 1000 milliseconds (1 second). The `getVariation()` method allows you to control whether tracking is done. If `track=false`, no exposure events will be sent by the SDK. This is useful if you prefer not to track data through the SDK and instead rely on client-side tracking managed by the Kameleoon engine, for example. Additionally, setting `track=false` is helpful when using the `getVariations()` method, where you might only need the variations for all flags without triggering any tracking events. If you want to know more about how tracking works, view [this 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é à son profil les data points pertinents avant de récupérer la variation de la feature ou de vérifier si le flag est actif. Utilisez la méthode [`addData()`](#adddata) pour ajouter ces data points au profil de l'utilisateur. Pour récupérer les data points collectés sur d'autres appareils ou pour accéder aux données utilisateur passées (collectées côté client lorsque vous utilisez Kameleoon en mode hybride), utilisez la méthode [`getRemoteVisitorData()`](#getremotevisitordata). Cette méthode récupère les données depuis les serveurs de manière asynchrone. Il est important d'appeler `getRemoteVisitorData()` *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 visiteur seront disponibles lors de l'analyse de vos expériences, vous permettant de filtrer et de décomposer vos résultats selon des 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 ainsi la décomposition de vos résultats sur la base de ces data points pré-collectés. Consultez la liste complète [ici](/fr/user-manual/experiment-analytics/analyze-results/results-page/results-page-settings#ventiler-l’audience). Si vous devez suivre des data points supplémentaires au-delà de ceux collectés automatiquement, vous pouvez utiliser la [fonctionnalité Custom Data](#customdata) de Kameleoon. Les Custom Data vous permettent de capturer et d'analyser des informations spécifiques pertinentes pour vos expériences. N'oubliez pas d'appeler la méthode [`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 (comme un achat), celle-ci est enregistrée comme une conversion. Pour suivre les conversions, utilisez la méthode [`trackConversion()`](#trackconversion) et fournissez les paramètres requis `visitorCode` et `goalId`. La requête de tracking de conversion sera envoyée avec la prochaine requête de tracking planifiée, que le SDK envoie à intervalles réguliers (défini par [`tracking_interval_millisecond`](#configuration-parameters)). 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 [`getEngineTrackingCode()`](#getenginetrackingcode). La méthode `getEngineTrackingCode()` récupère le code de tracking unique nécessaire pour envoyer les événements d'exposition à votre solution d'analytics. L'utilisation de cette méthode vous permet d'enregistrer les événements et de les envoyer vers la plateforme d'analytics de votre choix. ### Utilisation d'une clé de bucketing personnalisée Par défaut, Kameleoon utilise un ID visiteur unique et anonyme (`visitorCode`) 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 pouvez avoir besoin de garantir que tous les utilisateurs d'une même organisation voient la même variante d'un feature flag. L'option **clé de bucketing personnalisée** vous permet de remplacer ce comportement par défaut en fournissant votre propre identifiant personnalisé pour le bucketing. Ce remplacement garantit que la logique d'attribution de Kameleoon utilise la clé que vous avez spécifiée à la place du `visitorCode` 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 les situations suivantes : * **Expériences au niveau du compte ou organisationnelles :** pour les produits B2B ou les scénarios dans lesquels vous souhaitez attribuer tous les utilisateurs d'une même organisation à la même variation, vous pouvez utiliser un identifiant comme un `accountId`. Les clés de bucketing personnalisées sont essentielles pour les fonctionnalités d'A/B test qui impactent une équipe ou une entreprise entière. En implémentant une clé de bucketing personnalisée, vous garantissez une meilleure cohérence et exactitude de 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 : ```js theme={null} client.addData(visitorCode, new CustomData(index, 'newVisitorCode')); ``` [Plus d'informations dans addData()](#adddata) * **Fourniture de la clé personnalisée :** vous fournissez votre identifiant personnalisé au SDK Kameleoon en utilisant la méthode [`addData()`](#adddata). Dans cette méthode, vous transmettrez votre clé de bucketing personnalisée choisie sous forme d'objet [`CustomData`](#customdata). Ici, `newVisitorCode` fait référence à l'identifiant que vous souhaitez utiliser pour votre bucketing (par exemple, le nouvel `userId` ou `accountId`). Pour que la clé de bucketing personnalisée fonctionne correctement, elle doit également être définie et configurée pour le feature flag lors du processus de création ou de modification du flag. Sans cette configuration correspondante, le bucketing du SDK n'appliquera pas votre clé personnalisée. Pour des instructions détaillées sur la façon de configurer cela dans Kameleoon, consultez cet [article](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag#Advanced_Flag_Settings). * **Logique de bucketing :** une fois qu'une clé de bucketing personnalisée est fournie via la méthode `addData()`, tous les calculs de hash pour attribuer les utilisateurs aux variations utiliseront ce `newVisitorCode` (votre clé personnalisée) à la place du `visitorCode` par défaut. L'utilisation de `newVisitorCode` signifie que la décision de bucketing est liée à votre identifiant personnalisé, garantissant des attributions cohérentes dans les différents contextes où cet identifiant est présent. * **Tracking des données et analytics :** il est crucial de noter que, bien que `newVisitorCode` (votre clé personnalisée) soit utilisé pour les décisions de bucketing, **toutes les données ultérieures (événements de tracking et conversions, par exemple) sont envoyées et associées au `visitorCode` *original*.** Cette séparation garantit que votre analytics reflète fidèlement les parcours et les interactions individuels des utilisateurs dans le contexte plus large de votre expérience, même lorsque le bucketing est effectué à un niveau supérieur (comme un compte) ou sur plusieurs appareils/sessions. Vos données visiteur d'origine restent intactes pour un reporting complet. #### Exigences techniques Pour utiliser efficacement une clé de bucketing personnalisée : * La clé doit être une `string`. * Elle doit être unique pour l'entité que vous souhaitez bucketer (par exemple, si vous utilisez un `userId`, l'ID de chaque utilisateur doit être unique). * La clé doit être disponible pour le SDK au moment exact où la décision du feature flag est évaluée pour cet utilisateur ou cette requête. ### Conditions de ciblage Les SDK Kameleoon prennent en charge diverses 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 des 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/feature-experimentation/targeting-and-segmentation\use-external-data-to-target-users). ### Logging Le SDK génère des logs pour refléter divers processus et problèmes internes. #### Niveaux de log Le SDK permet de configurer la limitation du logging par niveau de log. ```ts theme={null} import { KameleoonClient, KameleoonLogger, LogLevel } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration }); // The `NONE` log level does not allow logging. client.setLogLevel(LogLevel.NONE); // Or use directly KameleoonLogger KameleoonLogger.setLogLevel(LogLevel.NONE); // The `ERROR` log level only allows logging issues that may affect the SDK's primary behavior. client.setLogLevel(LogLevel.ERROR); // Or use directly KameleoonLogger KameleoonLogger.setLogLevel(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. client.setLogLevel(LogLevel.WARNING); // Or use KameleoonLogger KameleoonLogger.setLogLevel(LogLevel.WARNING); ``` ```ts theme={null} import { KameleoonClient, KameleoonLogger, LogLevel } from ‘@kameleoon/javascript-sdk/full’; // The `INFO` log level allows logging general information on the SDK’s internal processes. // It extends the `WARNING` log level. client.setLogLevel(LogLevel.INFO); // Or use KameleoonLogger KameleoonLogger.setLogLevel(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. client.setLogLevel(LogLevel.DEBUG); // Or use KameleoonLogger KameleoonLogger.setLogLevel(LogLevel.DEBUG); ``` ```js theme={null} import { KameleoonClient, KameleoonLogger, LogLevel } from ‘@kameleoon/javascript-sdk’; const client = new KameleoonClient({ siteCode: ‘my_site_code’, configuration }); // The `NONE` log level does not allow logging. client.setLogLevel(LogLevel.NONE); // Or use KameleoonLogger KameleoonLogger.setLogLevel(LogLevel.NONE); // The `ERROR` log level only allows logging issues that may affect the SDK’s primary behavior. client.setLogLevel(LogLevel.ERROR); // Or use KameleoonLogger KameleoonLogger.setLogLevel(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. client.setLogLevel(LogLevel.WARNING); // Or use KameleoonLogger KameleoonLogger.setLogLevel(LogLevel.WARNING); ``` ```js theme={null} import { KameleoonClient, KameleoonLogger, LogLevel } from ‘@kameleoon/javascript-sdk’; // The `INFO` log level allows logging general information on the SDK’s internal processes. // It extends the `WARNING` log level. client.setLogLevel(LogLevel.INFO); // Or use KameleoonLogger KameleoonLogger.setLogLevel(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. client.setLogLevel(LogLevel.DEBUG); // Or use KameleoonLogger KameleoonLogger.setLogLevel(LogLevel.DEBUG); ``` #### Gestion personnalisée des logs Par défaut, le SDK écrit ses logs vers la sortie console. Ce comportement peut être remplacé. La limitation du logging par niveau de log est effectuée séparément de la logique de gestion des logs. ```ts theme={null} import { KameleoonClient, KameleoonLogger, IExternalLogger, LogLevel } from '@kameleoon/javascript-sdk'; export class CustomLogger implements IExternalLogger { // `log` method accepts logs from the SDK public log(level: LogLevel, message: string): void { // Custom log handling logic here. For example: switch (level) { case LogLevel.DEBUG: console.debug(message); break; case LogLevel.INFO: console.info(message); break; case LogLevel.WARNING: console.warn(message); break; case LogLevel.ERROR: console.error(message); break; } } } const client = new KameleoonClient({ siteCode: 'my_site_code', externals: { logger: new CustomLogger(), }, }); // 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. client.setLogLevel(LogLevel.DEBUG); // Or use KameleoonLogger KameleoonLogger.setLogLevel(LogLevel.DEBUG); ``` ```js theme={null} import { KameleoonClient, KameleoonLogger, LogLevel } from '@kameleoon/javascript-sdk'; export class CustomLogger { // `log` method accepts logs from the SDK log(level, message) { // Custom log handling logic here. For example: switch (level) { case 'DEBUG': console.debug(message); break; case 'INFO': console.info(message); break; case 'WARNING': console.warn(message); break; case 'ERROR': console.error(message); break; } } } const client = new KameleoonClient({ siteCode: 'my_site_code', externals: { logger: new CustomLogger(), }, }); // 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. client.setLogLevel(LogLevel.DEBUG); // Or use KameleoonLogger KameleoonLogger.setLogLevel(LogLevel.DEBUG); ``` ### Informations sur le domaine Vous fournissez un domaine comme `domain` dans la configuration de `KameleoonClient`, qui est utilisé pour stocker le visitor code Kameleoon dans les cookies. Les domaines sont importants lorsque vous travaillez avec les méthodes [`getVisitorCode`](#getvisitorcode) et [`setLegalConsent`](#setlegalconsent). Le domaine que vous fournissez est stocké dans le cookie sous la clé `Domain=`. ### Configuration du domaine Le domaine que vous fournissez indique si l'adresse URL peut utiliser le cookie. Par exemple, si votre domaine est `www.example.com`, le cookie n'est disponible que depuis une URL `www.example.com`. Cela signifie que les pages avec le domaine `app.example.com` ne peuvent pas utiliser le cookie. Pour plus de flexibilité avec les sous-domaines, vous pouvez spécifier le domaine avec un point (`.`). Par exemple, le domaine `.example.com` permet au cookie de fonctionner à la fois sur `app.example.com` et `login.example.com`. Vous ne pouvez pas utiliser d'expressions régulières, de symboles spéciaux, de protocole ou de numéros de port dans le `domain`. De plus, une [liste spécifique de sous-domaines](https://publicsuffix.org/list/public_suffix_list.dat) ne peut pas être utilisée avec le préfixe `.`. Voici un petit aide-mémoire des domaines : | Domaine | URL autorisées | URL non autorisées | | ------------------------------ | --------------------- | -------------------- | | `www.example.com` | ✅`www.example.com` | ❌ `app.example.com` | | | ✅ `example.com` | ❌ `.com` | | | | | | `.example.com` = `example.com` | ✅ `example.com` | ❌ `otherexample.com` | | | ✅ `www.example.com` | | | | ✅ `app.example.com` | | | | ✅ `login.example.com` | | | `https://www.example.com` | ⛔ bad domain | ⛔ bad domain | | `www.example.com:4408` | ⛔ bad domain | ⛔ bad domain | | `.localhost.com` = `localhost` | ⛔ bad domain | ⛔ bad domain | #### Développement sur localhost `localhost` est toujours considéré comme un mauvais domaine, ce qui rend difficile le test du domaine lors du développement sur `localhost`. Il existe deux façons d'éviter ce problème : * Ne spécifiez pas le champ `domain` dans le client SDK pendant les tests. * Créez un domaine local pour `localhost`. Par exemple : * Accédez à `/etc/hosts` sur *Linux* ou à `c:\Windows\System32\Drivers\etc\hosts` sur *Windows*. * Ouvrez `hosts` avec les droits de super utilisateur ou d'administrateur. * Ajoutez un domaine au port `localhost`, par exemple : `127.0.0.1 app.com` * Vous pouvez maintenant exécuter votre application localement sur `app.com:{my_port}` et spécifier `.app.com` comme domaine ### Dépendances externes Les dépendances externes du SDK utilisent le pattern d'*injection de dépendances* pour vous donner la possibilité de fournir vos propres implémentations pour certaines parties d'un SDK. Dans le SDK JavaScript, toutes les dépendances externes ont des implémentations par défaut, qui utilisent une API native du navigateur, il n'est donc pas nécessaire de les fournir, sauf si une autre API est requise pour des cas d'usage spécifiques. Voici la liste des dépendances externes disponibles : | Dependency | Interface | Required/Optional | API Used | Description | | -------------------- | ----------------------------- | ----------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `storage` | `IExternalStorage` | *Optional* | Browser `localStorage` | Utilisé pour stocker toutes les données existantes et collectées du SDK. | | `requester` | `IExternalRequester` | *Optional* | Browser `fetch` | Utilisé pour effectuer toutes les requêtes réseau. | | `eventSource` | `IExternalEventSource` | *Optional* | Browser `EventSource` | Utilisé pour recevoir les Server Sent Events pour les capacités de [mise à jour en temps réel](/fr/developer-docs/feature-experimentation/technical-reference/technical-considerations#streaming-option-premium). | | `visitorCodeManager` | `IExternalVisitorCodeManager` | *Optional* | Browser cookie | Utilisé pour stocker et synchroniser les visitor codes. | | `logger` | `ILogger` | *Optional* | Custom implementation | Utilisé pour la gestion personnalisée des logs du SDK. Vous permet de définir comment les logs sont traités et leur sortie. | L'exemple suivant implémente des dépendances externes. Pour importer une interface depuis un SDK, créez une classe qui implémente l'interface et transmettez la classe instanciée au SDK. #### Storage ```ts theme={null} import { IExternalStorage, KameleoonClient } from '@kameleoon/javascript-sdk'; // --- External Storage implementation --- // - JavaScript `Map` is used as an example storage const storage = new Map(); class MyStorage implements IExternalStorage { public read(key: string): T | null { // - Read data using `key` const data = storage.get(key); // - Return `null` if there's no data if (!data) { return null; } // - Return obtained data return data; } public write(key: string, data: T): void { // - Write data using `key` storage.set(key, data); } } // --- Create KameleoonClient --- const client = new KameleoonClient({ siteCode: 'my_site_code', externals: { storage: new MyStorage(), }, }); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; // --- External Storage implementation --- // - JavaScript `Map` is used as an example storage const storage = new Map(); class MyStorage { read(key) { // - Read data using `key` const data = storage.get(key); // - Return `null` if there's no data if (!data) { return null; } // - Return obtained data return data; } write(key, data) { // - Write data using `key` storage.set(key, data); } } // --- Create KameleoonClient --- const client = new KameleoonClient({ siteCode: 'my_site_code', externals: { storage: new MyStorage(), }, }); ``` #### EventSource ```ts theme={null} import { IExternalEventSource, KameleoonClient, EventSourceOpenParametersType, } from '@kameleoon/javascript-sdk'; // --- External EventSource implementation --- // - Example uses native browser `EventSource` class MyEventSource implements IExternalEventSource { private eventSource?: EventSource; public open({ eventType, onEvent, url, }: EventSourceOpenParametersType): void { // - Initialize `EventSource` const eventSource = new EventSource(url); this.eventSource = eventSource; // - Add event listener with provided event type and event callback this.eventSource.addEventListener(eventType, onEvent); } public close(): void { // - Cleanup open event source if (this.eventSource) { this.eventSource.close(); } } public onError(callback: (error: Event) => void): void { // - Set error callback if (this.eventSource) { this.eventSource.onerror = callback; } } } // --- Create KameleoonClient --- const client = new KameleoonClient({ siteCode: 'my_site_code', externals: { eventSource: new MyEventSource(), }, }); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; // --- External EventSource implementation --- // - Example uses native browser `EventSource` class MyEventSource { eventSource; open({ eventType, onEvent, url }) { // - Initialize `EventSource` const eventSource = new EventSource(url); this.eventSource = eventSource; // - Add event listener with provided event type and event callback this.eventSource.addEventListener(eventType, onEvent); } close() { // - Cleanup open event source if (this.eventSource) { this.eventSource.close(); } } public onError(callback) { // - Set error callback if (this.eventSource) { this.eventSource.onerror = callback; } } } // --- Create KameleoonClient --- const client = new KameleoonClient({ siteCode: 'my_site_code', externals: { eventSource: new MyEventSource(), }, }); ``` #### VisitorCodeManager ```ts theme={null} import { IExternalVisitorCodeManager, SetDataParametersType, KameleoonClient, KameleoonUtils, } from '@kameleoon/javascript-sdk'; // --- External Visitor Code Manager implementation --- // - Example uses browser `document.cookie` API class MyVisitorCodeManager implements IExternalVisitorCodeManager { public getData(key: string): string | null { const cookieString = document.cookie; // - Return `null` if no cookie was found if (!cookieString) { return null; } // - Parse cookie using the provided `key` return KameleoonUtils.getCookieValue(cookieString, key); } public setData({ visitorCode, domain, maxAge, key, path, }: SetDataParametersType): void { // - Set cookie with provided parameters let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`; if (domain) { resultCookie += `; Domain=${domain}`; } document.cookie = resultCookie; } } // --- Create KameleoonClient --- const client = new KameleoonClient({ siteCode: 'my_site_code', externals: { visitorCodeManager: new MyVisitorCodeManager(), }, }); ``` ```js theme={null} import { KameleoonClient, KameleoonUtils } from '@kameleoon/javascript-sdk'; // --- External Visitor Code Manager implementation --- // - Example uses browser `document.cookie` API class MyVisitorCodeManager { getData(key) { const cookieString = document.cookie; // - Return `null` if no cookie was found if (!cookieString) { return null; } // - Parse cookie using provided `key` return KameleoonUtils.getCookieValue(cookieString, key); } setData({ visitorCode, domain, maxAge, key, path }) { // - Set cookie with provided parameters let resultCookie = `${key}=${visitorCode}; Max-Age=${maxAge}; Path=${path}`; if (domain) { resultCookie += `; Domain=${domain}`; } document.cookie = resultCookie; } } // --- Create KameleoonClient --- const client = new KameleoonClient({ siteCode: 'my_site_code', externals: { visitorCodeManager: new MyVisitorCodeManager(), }, }); ``` #### Requester ```ts theme={null} import { RequestType, IExternalRequester, KameleoonResponseType, SendRequestParametersType, KameleoonClient, } from '@kameleoon/javascript-sdk'; // --- External Requester Implementation export class MyRequester implements IExternalRequester { public async sendRequest({ url, parameters, }: SendRequestParametersType): Promise { // - Using native browser `fetch` return await fetch(url, parameters); } } // --- Create KameleoonClient --- const client = new KameleoonClient({ siteCode: 'my_site_code', externals: { requester: new MyRequester(), }, }); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; // --- External Requester Implementation export class MyRequester { async sendRequest({ url, parameters }) { // - Using native browser `fetch` return await fetch(url, parameters); } } // --- Create KameleoonClient --- const client = new KameleoonClient({ siteCode: 'my_site_code', externals: { requester: new MyRequester(), }, }); ``` [Retourner un résultat simulé](#simulatesuccessrequest) ### Gestion des erreurs Presque chaque méthode `KameleoonClient` peut occasionnellement lever une erreur. Ces erreurs sont des `KameleoonError` délibérément prédéfinies qui étendent la classe native JavaScript `Error`, fournissant des messages utiles et des champs `type` spéciaux de type `KameleoonException`. `KameleoonException` est un enum contenant tous les types d'erreurs possibles. Pour savoir exactement quel type de `KameleoonException` la méthode peut lever, consultez la section `Throws` dans la description de la méthode sur cette page, ou survolez la méthode dans votre IDE pour voir la description jsdocs. La gestion des erreurs rend votre application plus stable et évite les problèmes techniques. ```ts theme={null} import { KameleoonError, KameleoonClient, KameleoonException, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { try { await client.initialize(); const customData = new CustomData(0, 'my_data'); client.addData(visitorCode, customData); } catch (error) { // -- Type guard for inferring error type, as native JavaScript `catch` // only infers `unknown` if (error instanceof KameleoonError) { switch (error.type) { case KameleoonException.VisitorCodeMaxLength: // -- Handle an error break; case KameleoonException.StorageWrite: // -- Handle an error break; case KameleoonException.Initialization: // -- Handle an error break; default: break; } } } } init(); ``` ```js theme={null} import { KameleoonClient, KameleoonException } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { try { await client.initialize(); const customData = new CustomData(0, 'my_data'); client.addData(visitorCode, customData); } catch (error) { switch (error.type) { case KameleoonException.VisitorCodeMaxLength: // -- Handle an error break; case KameleoonException.StorageWrite: // -- Handle an error break; case KameleoonException.Initialization: // -- Handle an error break; default: break; } } } init(); ``` ### 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 visiteur précédemment collectées sur chacun des appareils du visiteur ainsi que la réconciliation de leur historique de visite entre les appareils grâce à l'expérimentation cross-device. Des études de cas et des informations détaillées sur la façon dont Kameleoon gère les données entre les appareils sont disponibles dans l'[article sur l'expérimentation cross-device](/developer-docs/cross-device-experimentation). #### Synchronisation des custom data entre appareils Bien que la synchronisation du mapping personnalisé soit utilisée pour aligner les données visiteur entre les appareils, elle n'est pas toujours nécessaire. Voici deux scénarios où la synchronisation du mapping personnalisé n'est pas requise : **Même 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 de mapping personnalisé. Il suffit d'appeler la méthode `getRemoteVisitorData()` lorsque vous souhaitez synchroniser les données collectées entre plusieurs appareils. **Instances multi-serveurs avec des ID cohérents** Dans des configurations complexes impliquant plusieurs serveurs (par exemple, des instances de serveur distribuées), où le même user ID est disponible sur les serveurs, la synchronisation entre serveurs (avec `getRemoteVisitorData()`) est suffisante sans synchronisation de mapping personnalisé supplémentaire. Les clients qui ont besoin de données supplémentaires peuvent se reporter à la description de la méthode [`getRemoteVisitorData()`](#getremotevisitordata) pour plus d'informations. Dans le code ci-dessous, on suppose que le même identifiant unique (dans ce cas, le `visitorCode`, 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 le scope **Visitor** pour vos custom data. ```ts title="Device One" theme={null} import { KameleoonClient, CustomData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Custom Data with index `0` was set to `Visitor` scope // in Kameleoon. const customDataIndex = 0; const customData = new CustomData(customDataIndex, 'my_data'); client.addData('my_visitor', customData); client.flush(); } init(); ``` ```ts title="Device Two" theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Before working with data, make `getRemoteVisitorData` call await getRemoteVisitorData({ visitorCode: 'my_visitor_code' }); // -- New SDK code will have access to CustomData with `Visitor` scope // defined on Device One. // So, "my_data" is now available for targeting and tracking "my_visitor". } init(); ``` ```ts title="Device One" theme={null} import { KameleoonClient, CustomData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Custom Data with index `0` was set to `Visitor` scope // in Kameleoon. const customDataIndex = 0; const customData = new CustomData(customDataIndex, 'my_data'); client.addData('my_visitor', customData); client.flush(); } init(); ``` ```ts title="Device Two" theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Before working with data, make `getRemoteVisitorData` call. await getRemoteVisitorData({ visitorCode: 'my_visitor_code' }); // -- New SDK code will have access to CustomData with `Visitor` scope // defined on Device One. // So, "my_data" is now available for targeting and tracking "my_visitor" } init(); ``` #### Utilisation des custom data pour la fusion de sessions L'expérimentation cross-device vous permet de combiner l'historique d'un visiteur sur chacun de ses appareils (réconciliation d'historique). La réconciliation d'historique vous permet de fusionner les sessions de différents visiteurs en une seule session. Pour réconcilier l'historique de visite, utilisez [`CustomData`](#customdata) afin de fournir un identifiant unique pour le visiteur. Suivez le guide [activation de la réconciliation d'historique cross-device](#expérimentation-cross-device) pour configurer vos custom data dans Kameleoon. Une fois vos custom data configurées, vous pouvez les utiliser dans votre code pour fusionner les sessions d'un visiteur. Les sessions avec le même identifiant verront toujours la même variation d'expérience, et sont affichées comme un visiteur unique dans la vue `Visitor` de la page de résultats de votre expérience. La configuration du SDK garantit que les sessions associées voient toujours la même variation de l'expérience. Ensuite, vous pouvez utiliser le SDK normalement. Les méthodes suivantes peuvent être utiles pour la fusion de sessions : * [`getRemoteVisitorData`](#getremotevisitordata) avec `isUniqueIdentifier=true` - pour récupérer les données de tous les visiteurs liés * [`trackConversion`](#trackconversion) ou [`flush`](#flush) avec `isUniqueIdentifier=true` - pour tracker les données d'un visiteur spécifique associé à un autre visiteur. Puisque la custom data que vous utilisez comme identifiant doit être définie sur le scope `Visitor`, vous devez utiliser la [synchronisation des custom data cross-device](/developer-docs/cross-device-experimentation) pour récupérer l'identifiant avec la méthode [`getRemoteVisitorData`](#getremotevisitordata) sur chaque appareil. Voici un exemple d'utilisation des custom data pour la fusion de sessions. Dans cet exemple, nous avons une application avec une page de connexion. Comme nous ne connaissons pas l'user ID au moment de la connexion, nous utilisons un identifiant de visiteur anonyme généré par la méthode [`getVisitorCode`](#getvisitorcode). Une fois l'utilisateur connecté, nous pouvons associer le visiteur anonyme à l'user ID et l'utiliser comme identifiant unique du visiteur. ```ts title="Login Page" theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', }); async function init(): Promise { await client.initialize(); const anonymousVisitor = getVisitorCode(); // -- Saving `visitorCode` in `window` to re-use it later window.anonymousVisitor = anonymousVisitor; // -- Getting a variation—assume it's variation `A` const variation = client.getVariation({ visitorCode: anonymousVisitor, featureKey: 'my_feature_key', }); } init(); ``` ```ts title="Application Page" theme={null} import { CustomData } from '@kameleoon/javascript-sdk'; async function init(): Promise { // -- At this point, the anonymous visitor has logged in, // and we have a user ID to use as a visitor identifier. // -- Associating both visitors with an identifier Custom Data, // where index `1` is the Custom Data's index, configured // as a unique identifier in Kameleoon. const userIdentifierData = new CustomData(1, 'my_user_id'); // -- Taking `visitorCode` from `window` object client.addData(window.anonymousVisitor, userIdentifierData); // -- Retrieving the variation for the user ID ensures // consistency with the anonymous visitor's variation. // Both the anonymous visitor and the user ID will be // assigned variation `A`. const variation = client.getVariation({ visitorCode: 'my_user_id', featureKey: 'my_feature_key', }); // -- `my_user_id` and `anonymousVisitor` are now linked. // They can be tracked as a single visitor. client.trackConversion({ visitorCode: 'my_user_id', goalId: 123, revenue: 100, // -- Informing the SDK that the visitor is a unique identifier isUniqueIdentifier: true, }); // -- Additionally, linked visitors share previously // collected remote data const data = await client.getRemoteVisitorData({ visitorCode: 'my_user_id', // -- Informing the SDK that the visitor is a unique identifier isUniqueIdentifier: true, }); } init(); ``` ```js title="Login Page" theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', }); async function init() { await client.initialize(); const anonymousVisitor = getVisitorCode(); // -- Saving `visitorCode` in `window` to re-use it later. window.anonymousVisitor = anonymousVisitor; // -- Getting a variation—assume it's variation `A` const variation = client.getVariation({ visitorCode: anonymousVisitor, featureKey: 'my_feature_key', }); } init(); ``` ```js title="Application Page" theme={null} import { CustomData } from '@kameleoon/javascript-sdk'; async function init() { // -- At this point anonymous visitor has logged in, // and we have a user ID to use as a visitor identifier // -- Associating both visitors with an identifier Custom Data, // where index `1` is the Custom Data's index, configured // as a unique identifier in Kameleoon. const userIdentifierData = new CustomData(1, 'my_user_id'); // -- Taking `visitorCode` from `window` object client.addData(window.anonymousVisitor, userIdentifierData); // -- Retrieving the variation for the user ID ensures // consistency with the anonymous visitor's variation. // Both the anonymous visitor and the user ID will be // assigned variation `A`. const variation = client.getVariation({ visitorCode: 'my_user_id', featureKey: 'my_feature_key', }); // -- `my_user_id` and `anonymousVisitor` are now linked. // They can be tracked as a single visitor. client.trackConversion({ visitorCode: 'my_user_id', goalId: 123, revenue: 100, // -- Informing the SDK that the visitor is a unique identifier. isUniqueIdentifier: true, }); // -- Additionally, linked visitors share previously // collected remote data. const data = await client.getRemoteVisitorData({ visitorCode: 'my_user_id', // -- Informing the SDK that the visitor is a unique identifier. isUniqueIdentifier: true, }); } init(); ``` L'[expérimentation cross-device](/developer-docs/cross-device-experimentation) permet de combiner l'historique d'un visiteur sur chacun de ses appareils (réconciliation d'historique). La réconciliation d'historique permet de fusionner les sessions de différents visiteurs en une seule. Pour réconcilier l'historique de visite, utilisez [`CustomData`](#customdata) afin de fournir un identifiant unique pour le visiteur. Pour plus d'informations, consultez la [documentation dédiée](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation). Une fois la réconciliation cross-device activée, appeler [`getRemoteVisitorData()`](#getremotevisitordata) 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 visiteur unique. La configuration du SDK garantit que les sessions associées voient toujours la même variation de l'expérience. However, there are some limitations regarding cross-device variation allocation. These limitations are outlined [here](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights). Suivez le guide [activation de la réconciliation d'historique cross-device](#expérimentation-cross-device) pour configurer vos 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 : * `getRemoteVisitorData()` avec `UniqueIdentifier(true)` ajouté - pour récupérer les données de tous les visiteurs liés. * [`trackConversion()`](#trackconversion) ou [`flush()`](#flush) avec une donnée `UniqueIdentifier(true)` ajoutée - pour tracker des données pour un visiteur spécifique associé à un autre visiteur. Puisque la custom data que vous utilisez comme identifiant doit être définie sur le **scope Visitor**, vous devez utiliser la [synchronisation des custom data cross-device](/developer-docs/cross-device-experimentation) pour récupérer l'identifiant avec la méthode [`getRemoteVisitorData()`](#getremotevisitordata) sur chaque appareil. Voici un exemple d'utilisation des custom data pour la fusion de sessions. ```ts title="Login Page" theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', }); async function init(): Promise { await client.initialize(); const anonymousVisitor = getVisitorCode(); // -- Saving `visitorCode` in `window` to re-use it later. window.anonymousVisitor = anonymousVisitor; // -- Getting a variation, assume it's variation `A` const variation = client.getVariation({ visitorCode: anonymousVisitor, featureKey: 'my_feature_key', }); } init(); ``` ```ts title="Application Page" theme={null} import { CustomData, UniqueIdentifier } from '@kameleoon/javascript-sdk'; async function init(): Promise { // -- At this point anonymous visitor has logged in, // and we have a user ID to use as a visitor identifier // -- Associating both visitors with an identifier Custom Data, // where index `1` is the Custom Data's index, configured // as a unique identifier in Kameleoon. const userIdentifierData = new CustomData(1, 'my_user_id'); // -- Taking `visitorCode` from `window` object client.addData(window.anonymousVisitor, userIdentifierData); // -- Flushing data for the anonymous `visitorCode` client.flush(window.anonymousVisitor); // -- Informing the SDK that the visitor is a unique identifier client.addData('my_user_id', new UniqueIdentifier(true)); // -- Retrieving the variation for the user ID ensures // consistency with the anonymous visitor's variation. // Both the anonymous visitor and the user ID will be // assigned variation `A`. const variation = client.getVariation({ visitorCode: 'my_user_id', featureKey: 'my_feature_key', }); // -- `my_user_id` and `anonymousVisitor` are now linked. // They can be tracked as a single visitor. client.trackConversion({ visitorCode: 'my_user_id', goalId: 123, revenue: 100, }); // -- Additionally, linked visitors share previously // collected remote data. const data = await client.getRemoteVisitorData({ visitorCode: 'my_user_id', }); } init(); ``` ```js title="Login Page" theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', }); async function init() { await client.initialize(); const anonymousVisitor = getVisitorCode(); // -- Saving `visitorCode` in `window` to re-use it later. window.anonymousVisitor = anonymousVisitor; // -- Getting a variation, assume it's variation `A` const variation = client.getVariation({ visitorCode: anonymousVisitor, featureKey: 'my_feature_key', }); } init(); ``` ```js title="Application Page" theme={null} import { CustomData, UniqueIdentifier } from '@kameleoon/javascript-sdk'; async function init() { // -- At this point anonymous visitor has logged in, // and we have a user ID to use as a visitor identifier // -- Associating both visitors with an identifier Custom Data, // where index `1` is the Custom Data's index, configured // as a unique identifier in Kameleoon. const userIdentifierData = new CustomData(1, 'my_user_id'); // -- Taking `visitorCode` from `window` object client.addData(window.anonymousVisitor, userIdentifierData); // -- Flushing data for the anonymous `visitorCode` client.flush(window.anonymousVisitor); // -- Informing the SDK that the visitor is a unique identifier. client.addData('my_user_id', new UniqueIdentifier(true)); // -- Retrieving the variation for the user ID ensures // consistency with the anonymous visitor's variation. // Both the anonymous visitor and the user ID will be // assigned variation `A`. const variation = client.getVariation({ visitorCode: 'my_user_id', featureKey: 'my_feature_key', }); // -- `my_user_id` and `anonymousVisitor` are now linked. // They can be tracked as a single visitor. client.trackConversion({ visitorCode: 'my_user_id', goalId: 123, revenue: 100, }); // -- Additionally, linked visitors share previously // collected remote data. const data = await client.getRemoteVisitorData({ visitorCode: 'my_user_id', }); } init(); ``` ### Utilitaires Le SDK dispose d'un ensemble de méthodes utilitaires que vous pouvez utiliser pour simplifier votre processus de développement. Toutes les méthodes sont représentées en tant que membres statiques de la classe `KameleoonUtils`. #### simulateSuccessRequest Utilisez la méthode `simulateSuccessRequest` pour simuler une requête réussie vers le serveur Kameleoon. Cela peut être utile pour les implémentations personnalisées de [Requester](#requester), lorsqu'un développeur a besoin de simuler une requête réussie (par exemple, pour désactiver le tracking). ```ts theme={null} import { KameleoonUtils, IExternalRequester, SendRequestParametersType, RequestType, KameleoonResponseType, } from '@kameleoon/javascript-sdk'; // - Example of `Requester` with disabled tracking class Requester implements IExternalRequester { public async sendRequest({ url, parameters, requestType, }: SendRequestParametersType): Promise { if (requestType === RequestType.Tracking) { return KameleoonUtils.simulateSuccessRequest( requestType, null, ); } return await fetch(url, parameters); } } ``` ```js theme={null} import { KameleoonUtils } from '@kameleoon/javascript-sdk'; // - Example of `Requester` with disabled tracking class Requester { async sendRequest({ url, parameters, requestType }) { if (requestType === RequestType.Tracking) { return KameleoonUtils.simulateSuccessRequest(requestType, null); } return await fetch(url, parameters); } } ``` ##### Arguments | Name | Type | Description | | ------------------------ | -------------------------------------- | ----------------------------------------------------------- | | requestType (*required*) | `RequestType` | Type de requête | | data (*required*) | `SimulateRequestDataType[RequestType]` | Type de données de requête, qui diffère selon `RequestType` | Le type de données `SimulateRequestDataType` est défini comme suit : * `RequestType.Tracking` - `null` * `RequestType.ClientConfiguration` - `ClientConfigurationDataType` * `RequestType.RemoteData` - `JSONType` ##### Valeur de retour | Type | Description | | -------------------------------- | -------------------------------------------------- | | `Promise` | renvoie une promesse avec la réponse de la requête | #### getCookieValue Utilisez la méthode `getCookieValue` pour analyser une chaîne de cookie standard (`key_1=value_1; key_2=value_2; ...`) et obtenir la valeur d'une clé de cookie spécifique. Cette méthode est utile lorsque vous travaillez avec une implémentation personnalisée de [`VisitorCodeManager`](#visitorcodemanager). ```ts theme={null} import { KameleoonUtils } from '@kameleoon/javascript-sdk'; const cookies = 'key_1=value_1; key_2=value_2'; const key = 'key_1'; const value = KameleoonUtils.getCookieValue(cookies, key); // = `value_1` ``` ```js theme={null} import { KameleoonUtils } from '@kameleoon/javascript-sdk'; const cookies = 'key_1=value_1; key_2=value_2'; const key = 'key_1'; const value = KameleoonUtils.getCookieValue(cookies, key); // = `value_1` ``` ##### Arguments | Name | Type | Description | | ------------------- | -------- | ---------------------------------------------------------- | | cookie (*required*) | `string` | Chaîne de cookie au format `key_1=value_1; key_2=value_2` | | key (*required*) | `string` | Représentation sous forme de chaîne de la clé à rechercher | ##### Valeur de retour | Type | Description | | | -------- | ----------- | ----------------------------------------------------------------------------------- | | \`string | null\` | renvoie une chaîne avec la valeur du cookie ou `null` si la clé n'a pas été trouvée | ## Référence Voici la documentation de référence complète du SDK JavaScript de Kameleoon. ### Initialisation #### initialize() `initialize()` est une méthode asynchrone pour l'initialisation de `KameleoonClient`. La méthode récupère les données du SDK Kameleoon depuis nos serveurs ou récupère les données depuis une source locale si elles sont à jour ou si l'intervalle de mise à jour n'a pas été atteint. * Si la configuration du SDK n'a pas pu être récupérée mais qu'une configuration plus ancienne est disponible dans le stockage du SDK, le SDK utilise la configuration plus ancienne en tant que fallback et `initialize` ne lève pas d'erreur. * L'initialisation du client dispose d'un *mode offline* optionnel. Il est activé en définissant le paramètre optionnel `useCache` à `true`. En *mode offline*, si les requêtes de tracking de l'une des méthodes suivantes échouent en raison de problèmes de connectivité Internet, le SDK renvoie automatiquement la requête lorsque la connexion Internet est rétablie : * [flush](/developer-docs/sdks/web-sdks/js-sdk#flush) * [trackConversion](/developer-docs/sdks/web-sdks/js-sdk#trackconversion) * [getFeatureFlagVariationKey](/developer-docs/sdks/web-sdks/js-sdk#getfeatureflagvariationkey) * [getFeatureFlagVariable](/developer-docs/sdks/web-sdks/js-sdk#getfeatureflagvariable) * [isFeatureFlagActive](/developer-docs/sdks/web-sdks/js-sdk#isfeatureflagactive) ```ts theme={null} import { KameleoonClient, KameleoonError, KameleoonException, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { try { await client.initialize(); } catch (err) { if (err instanceof KameleoonError) { switch (err.type) { case KameleoonException.StorageWrite: // -- Handle error case case KameleoonException.ClientConfiguration: // -- Handle error case default: break; } } } } init(); ``` ```js theme={null} import { KameleoonClient, KameleoonException } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { try { await client.initialize(); } catch (err) { switch (err.type) { case KameleoonException.StorageWrite: // -- Handle error case case KameleoonException.ClientConfiguration: // -- Handle error case default: break; } } } init(); ``` ##### Arguments | Name | Type | Description | Default Value | | --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | useCache (*optional*) | `boolean` | paramètre pour activer le mode offline du SDK. Si `true`, les polls échoués ne renverront pas d'erreur et utiliseront les données en cache si elles sont disponibles. | `false` | ##### Valeur de retour | Type | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Promise` | Une promesse qui se résout en un booléen indiquant si le SDK a été initialisé avec succès. Généralement, si un problème non résoluble survient, la méthode `initialize` lèvera une erreur au lieu de résoudre la promesse. Par conséquent, la valeur `boolean` vaut presque toujours `true` et n'apporte généralement pas beaucoup d'informations supplémentaires. | ##### Exceptions levées | Type | Description | | ------------------------------------------ | ------------------------------------------------------------------------- | | `KameleoonException.StorageWrite` | Impossible de mettre à jour les données du stockage | | `KameleoonException.ClientConfiguration` | Impossible de récupérer la configuration du client depuis l'API Kameleoon | | `KameleoonException.MaximumRetriesReached` | Nombre maximum de tentatives atteint, la requête a échoué | Méthode asynchrone pour l'initialisation de `KameleoonClient` en récupérant les données liées au SDK Kameleoon depuis le serveur ou en récupérant les données depuis une source locale si elles sont à jour ou si l'intervalle de mise à jour n'a pas été atteint. * Si la configuration du SDK n'a pas pu être récupérée mais qu'une configuration plus ancienne est disponible dans le stockage du SDK, le SDK utilise la configuration plus ancienne en tant que fallback et `initialize` ne lève pas d'erreur. * Le SDK prend en charge un *mode offline*. En *mode offline*, si les requêtes de tracking de l'une des méthodes suivantes échouent en raison de problèmes de connectivité Internet, le SDK renvoie automatiquement la requête dès qu'il détecte que la connexion Internet a été rétablie : * [flush](/developer-docs/sdks/web-sdks/js-sdk#flush) * [trackConversion](/developer-docs/sdks/web-sdks/js-sdk#trackconversion) * [getFeatureFlagVariationKey](/developer-docs/sdks/web-sdks/js-sdk#getfeatureflagvariationkey) * [getFeatureFlagVariable](/developer-docs/sdks/web-sdks/js-sdk#getfeatureflagvariable) * [isFeatureFlagActive](/developer-docs/sdks/web-sdks/js-sdk#isfeatureflagactive) ```ts theme={null} import { KameleoonClient, KameleoonError, KameleoonException, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { try { await client.initialize(); } catch (err) { if (err instanceof KameleoonError) { switch (err.type) { case KameleoonException.StorageWrite: // -- Handle error case case KameleoonException.ClientConfiguration: // -- Handle error case default: break; } } } } init(); ``` ```js theme={null} import { KameleoonClient, KameleoonException } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { try { await client.initialize(); } catch (err) { switch (err.type) { case KameleoonException.StorageWrite: // -- Handle error case case KameleoonException.ClientConfiguration: // -- Handle error case default: break; } } } init(); ``` ##### Valeur de retour | Type | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Promise` | Une promesse qui se résout en un booléen indiquant si le SDK a été initialisé avec succès. Généralement, si un problème non résoluble survient, la méthode `initialize` lèvera une erreur au lieu de résoudre la promesse. Par conséquent, la valeur `boolean` vaut presque toujours `true` et n'apporte généralement pas beaucoup d'informations supplémentaires. | ##### Exceptions levées | Type | Description | | ------------------------------------------ | ------------------------------------------------------------------------- | | `KameleoonException.StorageWrite` | Impossible de mettre à jour les données du stockage | | `KameleoonException.ClientConfiguration` | Impossible de récupérer la configuration du client depuis l'API Kameleoon | | `KameleoonException.MaximumRetriesReached` | Nombre maximum de tentatives atteint, la requête a échoué | ### Feature flags et variations #### getVariation() * 📨 *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 `featureKey` comme argument obligatoire et `track` comme argument optionnel. L'argument `track` est optionnel et vaut `true` par défaut. Elle renvoie la `Variation` attribuée pour le visiteur. Si le visiteur n'est associé à aucune règle de feature flag, la méthode renvoie la `Variation` par défaut pour le feature flag donné. Assurez-vous qu'une gestion d'erreurs appropriée est implémentée dans votre code pour gérer les éventuelles exceptions. 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 fallback 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..." d'une interface de gestion. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get variation with tracking const variation = client.getVariation({ visitorCode, featureKey: 'my_feature_key', }); // -- Get variation without tracking const variation = client.getVariation({ visitorCode, featureKey: 'my_feature_key', track: false, }); // -- An Example variation: // { // key: 'variation_key', // id: 123, // experimentId: 456, // variables: Map { // 'variable_key' => { // key: 'variable_key', // type: VariableType.BOOLEAN, // value: true, // } // }, // } } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get variation with tracking const variation = client.getVariation({ visitorCode, featureKey: 'my_feature_key', }); // -- Get variation without tracking const variation = client.getVariation({ visitorCode, featureKey: 'my_feature_key', track: false, }); // -- An Example variation: // { // key: 'variation_key', // id: 123, // experimentId: 456, // variables: Map { // 'variable_key' => { // key: 'variable_key', // type: VariableType.BOOLEAN, // value: true, // } // }, // } } init(); ``` ##### Arguments Un objet de type `GetVariationParamsType` avec les propriétés suivantes : | Name | Type | Description | Default | | ------------------------ | --------- | ----------------------------------------------------------------------------------------- | ------- | | visitorCode (*required*) | `string` | Identifiant unique du visiteur. | | | featureKey (*required*) | `string` | Clé de la feature que vous souhaitez exposer à un visiteur. | | | track (*optional*) | `boolean` | Paramètre optionnel pour activer ou désactiver le tracking de l'évaluation de la 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 | | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à [`initialize`](#initialize). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.FeatureFlagConfigurationNotFound` | 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 que le code implémentant la feature est déjà déployé dans l'application). | | `KameleoonException.FeatureFlagEnvironmentDisabled` | Exception indiquant que le feature flag est désactivé pour l'environnement actuel du visiteur (par exemple, production, staging ou development). | #### getVariations() * 📨 *Envoie des données de tracking à Kameleoon (selon le paramètre `track`)* * 🎯 *Événements :* [`EventType.Evaluation`](#events-1) Récupère une map d'objets [`Variation`](#variation) attribués à un visiteur donné pour tous les feature flags. Cette méthode itère sur tous les feature flags disponibles et renvoie la `Variation` attribuée pour chaque flag associé au visiteur spécifié. Elle prend `visitorCode` comme argument obligatoire, tandis que `onlyActive` et `track` sont optionnels. * Si `onlyActive` est défini à `true`, la méthode `getVariations()` renverra les variations de feature flag à condition que l'utilisateur ne soit pas bucketé avec la variation `off`. * Le paramètre `track` contrôle si la méthode doit ou non tracker les attributions de variation. Par défaut, il est défini à `true`. S'il est défini à `false`, le tracking sera désactivé. La map renvoyée a pour clés les clés des feature flags et pour valeurs leur `Variation` correspondante. Si aucune variation n'est attribuée pour un feature flag, la méthode renvoie la `Variation` par défaut de ce flag. Une gestion d'erreurs appropriée doit être implémentée pour gérer les éventuelles exceptions. 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 fallback 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..." d'une interface de gestion. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get all feature flag variations with tracking const variations = client.getVariations({ visitorCode, }); // -- Get active feature flag variations with tracking const variations = client.getVariations({ visitorCode, onlyActive: true, }); // -- Get active feature flag variations without tracking const variations = client.getVariations({ visitorCode, onlyActive: true, track: false, }); // -- An Example variations: // Map { // 'feature_key' => { // key: 'variation_key', // id: 123, // experimentId: 456, // variables: Map { // 'variable_key' => { // key: 'variable_key', // type: VariableType.BOOLEAN, // value: true, // } // }, // } // } } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get all feature flag variations with tracking const variations = client.getVariations({ visitorCode, }); // -- Get active feature flag variations with tracking const variations = client.getVariations({ visitorCode, onlyActive: true, }); // -- Get active feature flag variations without tracking const variations = client.getVariations({ visitorCode, onlyActive: true, track: false, }); // -- An Example variations: // Map { // 'feature_key' => { // key: 'variation_key', // id: 123, // experimentId: 456, // variables: Map { // 'variable_key' => { // key: 'variable_key', // type: VariableType.BOOLEAN, // value: true, // } // }, // } // } } init(); ``` ##### Arguments Un objet de type `GetVariationParamsType` avec les propriétés suivantes : | Name | Type | Description | Default | | ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------- | | visitorCode (*required*) | `string` | Identifiant unique du visiteur. | | | onlyActive (*optional*) | `boolean` | Paramètre optionnel indiquant s'il faut renvoyer les variations des feature flags actifs (`true`) ou de tous les feature flags (`false`). | `false` | | track (*optional*) | `boolean` | Paramètre optionnel pour activer ou désactiver le tracking de l'évaluation de la feature. | `true` | ##### Valeur de retour | Type | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `Map` | Map qui contient les objets [`Variation`](#variation) attribués des feature flags en utilisant les clés des features correspondantes. | ##### Exceptions levées | Type | Description | | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à [`initialize`](#initialize). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | #### isFeatureFlagActive() * 📨 *Envoie des données de tracking à Kameleoon (selon le paramètre `track`)* * 🎯 *Événements :* [`EventType.Evaluation`](#events-1) La méthode `isFeatureFlagActive()` renvoie une valeur booléenne indiquant si le visiteur identifié par `visitorCode` a la `featureKey` spécifiée active. Cette méthode vérifie le ciblage, détermine la variation pour le visiteur et enregistre cette information dans le stockage. De plus, elle envoie une requête de tracking. Il existe également une surcharge de cette méthode qui vous permet de passer un paramètre `track`, que vous pouvez utiliser pour désactiver le tracking de l'évaluation de la feature. Seuls les visiteurs avec un feature flag actif doivent être ciblés. Kameleoon utilise le tracking pour comptabiliser les sessions et les visiteurs lorsque vous appelez certaines méthodes, telles que `isFeatureFlagActive()`, `getVariation()` ou `getVariations()`. Utilisez la valeur par défaut `true` pour le paramètre `track` lorsque vous exposez des visiteurs à une variation et que vous devez les comptabiliser. Définissez le paramètre `track` à `false` uniquement si vous appelez ces méthodes avant d'exposer les visiteurs. Par exemple, si vous appelez `getVariations()` pour récupérer toutes les variations avant d'exposer les visiteurs, définissez le paramètre `track` à `false`. Ce réglage empêche Kameleoon de comptabiliser prématurément une session. Vous pouvez alors 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 via l'option de configuration de l'intervalle de tracking. Kameleoon regroupe les événements de tracking en une seule session tant que l'intervalle entre les événements est inférieur à 30 minutes. Si plus de 30 minutes s'écoulent entre les événements de tracking, Kameleoon comptabilise les événements comme des sessions distinctes. Une visite apparaît dans vos rapports 30 minutes après le dernier événement enregistré dans la session. ```ts theme={null} import { KameleoonClient, CustomData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Add CustomData with index `0` containing visitor id to check the targeting client.addData(visitorCode, new CustomData(0, 'visitor_id')); // -- Check if the feature flag is active for visitor const isActive = client.isFeatureFlagActive(visitorCode, 'my_feature_key'); // -- Check if the feature flag is active for visitor without tracking const isActive = client.isFeatureFlagActive({ visitorCode, featureKey: 'my_feature_key', track: false}); } init(); ``` ```js theme={null} import { KameleoonClient, CustomData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Add CustomData with index `0` containing visitor id to check the targeting client.addData(visitorCode, new CustomData(0, 'visitor_id')); // -- Check if the feature flag is active for visitor const isActive = client.isFeatureFlagActive(visitorCode, 'my_feature_key'); // -- Check if the feature flag is active for visitor without tracking const isActive = client.isFeatureFlagActive({ visitorCode, featureKey: 'my_feature_key', track: false}); } init(); ``` La méthode `isFeatureFlagActive()` évalue la variante servie, et non l'état du master flag. Si vous excluez des règles, la méthode utilise l'état par défaut **Then, for everyone else serve**. Si vous sélectionnez **Off** pour cet état par défaut, la méthode renvoie toujours `false` même lorsque le master feature flag est **On**. ##### Arguments Deux surcharges sont disponibles pour cette méthode : 1. Surcharge à deux paramètres : Cette surcharge est obsolète et sera supprimée lors de la prochaine mise à jour majeure. Veuillez utiliser la nouvelle surcharge avec un paramètre objet. | Name | Type | Description | | ------------------------ | -------- | ------------------------------------------------------------------------------- | | visitorCode (*required*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères | | featureKey (*required*) | `string` | une clé unique pour le feature flag | 2. Surcharge avec paramètre objet de type `IsFeatureFlagActiveParamsType` : | Name | Type | Description | Default | | ------------------------ | --------- | ------------------------------------------------------------------------------- | ------- | | visitorCode (*required*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères | - | | featureKey (*required*) | `string` | une clé unique pour le feature flag | - | | track (*optional*) | `boolean` | un indicateur booléen précisant s'il faut tracker l'évaluation de la feature | `true` | ##### Valeur de retour | Type | Description | | --------- | ------------------------------------------------------------------------------------------------------- | | `boolean` | un booléen indiquant si le feature flag avec `featureKey` est actif pour le visiteur avec `visitorCode` | ##### Exceptions levées | Type | Description | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à `initialize`. | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.FeatureFlagConfigurationNotFound` | Aucun feature flag n'a été trouvé pour la `featureKey` fournie. | | `KameleoonException.DataInconsistency` | Une variation allouée a été trouvée, mais il n'y a pas de feature flag avec la `featureKey` correspondante | #### setForcedVariation() 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 requise ou doit être ignorée. Cela peut également être utile dans des scénarios comme le debug ou les tests personnalisés. Lorsqu'une variation **forcée** est définie, elle remplace la logique d'évaluation en temps réel de Kameleoon. Les processus tels que la segmentation, les conditions de ciblage et les calculs algorithmiques sont ignorés. Pour préserver la segmentation et les conditions de ciblage pendant une expérience, définissez plutôt `forceTargeting=false`. Les variations **simulées** ont toujours la priorité dans l'ordre d'exécution. Si un calcul de variation **simulée** est déclenché, il sera entièrement traité et terminé en premier. Une variation forcée est traitée de la même manière qu'une variation évaluée. Elle est trackée dans les analytics et stockée dans le contexte utilisateur comme toute variation évaluée standard, garantissant la cohérence des rapports. La méthode peut lever des exceptions dans certaines conditions (par exemple, paramètres invalides, contexte utilisateur ou problèmes internes). Une gestion appropriée des exceptions est essentielle pour garantir la stabilité et la résilience de votre application. Il est important de distinguer les variations **forcées** des variations **[simulées](#getvisitorcode)** : * **Variations forcées** : sont spécifiques à une expérience individuelle. * **Variations simulées** : affectent le résultat global du **feature flag**. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Forcing the variation "on" for the "featureKey1" feature flag for the visitor client.setForcedVariation({ visitorCode: visitorCode, experimentId: 9516, variationKey: 'on', forceTargeting: false, }); // -- Resetting the forced variation for the "featureKey1" feature flag for the visitor client.setForcedVariation({ visitorCode: visitorCode, experimentId: 9516, variationKey: null, }); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Forcing the variation "on" for the "featureKey1" feature flag for the visitor client.setForcedVariation({ visitorCode: visitorCode, experimentId: 9516, variationKey: 'on', forceTargeting: false, }); // -- Resetting the forced variation for the "featureKey1" feature flag for the visitor client.setForcedVariation({ visitorCode: visitorCode, experimentId: 9516, variationKey: null, }); } init(); ``` ##### Arguments Un objet de type `SetForcedVariationParametersType` avec les propriétés suivantes : | Name | Type | Description | Default | | | --------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | visitorCode (*required*) | `string` | Identifiant unique du visiteur. | | | | experimentId (*required*) | `number` | **Experiment Id** qui sera ciblé et sélectionné lors du processus d'évaluation. | | | | variationKey (*required*) | \`string | null\` | **Variation Key** correspondant à une `Variation` qui doit être forcée comme valeur renvoyée pour l'expérience. Si la valeur est `null`, la variation forcée sera réinitialisée. | | | forceTargeting (*optional*) | `boolean` | Indique si le ciblage de l'expérience doit être forcé et ignoré (`true`) ou appliqué comme dans le processus d'évaluation standard (`false`). | `true` | | ##### Exceptions levées | Type | Description | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.Initialization` | Indique que le SDK n'est pas encore totalement initialisé. | | `KameleoonException.FeatureFlagExperimentNotFound` | Exception indiquant que l'experiment id demandé n'a pas été trouvé dans la configuration interne du SDK. Cela est généralement normal et signifie que l'expérience correspondante de la règle n'a pas encore été activée côté Kameleoon. | | `KameleoonException.FeatureFlagVariationNotFound` | Exception indiquant que la variation key(id) demandée n'a pas été trouvée dans la configuration interne du SDK. Cela est généralement normal et signifie que l'expérience correspondante de la variation n'a pas encore été activée côté Kameleoon. | | `KameleoonException.StorageRead` | Impossible de lire les données du stockage. | | `KameleoonException.StorageWrite` | Impossible de mettre à jour les données du stockage. | Dans la plupart des cas, seule l'erreur de base, `KameleoonException`, doit être gérée, comme le montre l'exemple. Cependant, si différents types d'erreurs nécessitent une réponse, gérez-les séparément en fonction des exigences spécifiques. De plus, pour une fiabilité accrue, les erreurs générales du langage peuvent être gérées en incluant `Error`. #### evaluateAudiences() * 📨 *Envoie des données de tracking à Kameleoon* Cette méthode évalue les visiteurs par rapport à tous les segments d'Audiences Explorer disponibles et tracke ceux qui correspondent. `evaluateAudiences()` doit être appelée **après que toutes les données pertinentes du visiteur ont été définies ou mises à jour**, et **juste avant** de récupérer une variation de feature ou de vérifier un feature flag. Cette approche garantit que le visiteur est évalué par rapport aux données les plus récentes disponibles, permettant une attribution d'audience précise basée sur tous les critères. Après avoir appelé cette méthode, vous pouvez effectuer une analyse détaillée des performances des segments dans Audiences Explorer. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); client.evaluateAudiences(visitorCode); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); client.evaluateAudiences(visitorCode); } init(); ``` ##### Arguments | Name | Type | Description | | ------------------------ | -------- | ------------------------------- | | visitorCode (*required*) | `string` | Identifiant unique du visiteur. | ##### Exceptions levées | Type | Description | | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à [`initialize`](#initialize). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | Dans la plupart des cas, seule l'erreur de base, `KameleoonException`, doit être gérée, comme le montre l'exemple. Cependant, si différents types d'erreurs nécessitent une réponse, gérez-les séparément en fonction des exigences spécifiques. De plus, pour une fiabilité accrue, les erreurs générales du langage peuvent être gérées en incluant `Error`. #### getDataFile() Pour évaluer tous les feature flags, utilisez [`getVariations()`](#getvariations). Cette méthode est plus efficace que d'appeler `DataFile` et de parcourir les flags avec [`getVariation()`](#getvariation). Renvoie la configuration actuelle du SDK sous forme d'objet [`DataFile`](#datafile). ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); const dataFile = client.getDataFile(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); const dataFile = client.getDataFile(); ``` ##### Valeur de retour | Type | Description | | ---------- | ------------------------------------------------------------ | | `DataFile` | Le [`DataFile`](#datafile) contenant la configuration du SDK | ### Données visiteur #### getVisitorCode() La méthode `getVisitorCode()` obtient un visitor code depuis le cookie du navigateur. Si le visitor code n'existe pas, la méthode génère un visitor code aléatoire (ou utilise la valeur `defaultVisitorCode` si vous en avez fourni une) et définit le nouveau visitor code dans un cookie. La méthode `getVisitorCode()` vous permet de définir des variations **simulées** pour un visiteur. Lorsque les cookies (d'une **requête** ou d'un **document**) contiennent la clé `kameleoonSimulationFFData`, le processus d'évaluation standard est contourné. À la place, la méthode renvoie directement une [`Variation`](#variation) basée sur les données fournies. Vous pouvez appliquer des simulations de deux manières : * **Automatiquement (recommandé) :** si vous utilisez Kameleoon Web Experimentation ou le SDK en [mode hybride](/developer-docs/feature-experimentation/get-started/hybrid-experimentation#linking-feature-experiments-with-front-end-tracking-code), le cookie est créé automatiquement lors de la simulation de l'affichage d'une variante 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](#setforcedvariation)** : * **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` respecte ce format : * `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}` : simule la variation avec `varId` de l'expérience `expId` pour la `featureKey` donnée. * `kameleoonSimulationFFData={"featureKey":{"expId":0}}` : simule la variation par défaut (définie dans la section **Then, for everyone else in Production, serve**) pour la `featureKey` donnée. ⚠️ Pour garantir le bon fonctionnement, la valeur du cookie doit être encodée en tant que composant URI à l'aide d'une méthode telle que [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent). ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get visitor code with default value const visitorCode = client.getVisitorCode('my_default_visitor_code'); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get visitor code with default value const visitorCode = client.getVisitorCode('my_default_visitor_code'); } init(); ``` ##### Arguments | Name | Type | Description | | --------------------------------- | -------- | -------------------------------------------------------------------- | | `defaultVisitorCode` (*optional*) | `string` | visitor code utilisé s'il n'y a pas de visitor code dans les cookies | Si vous ne fournissez pas de `defaultVisitorCode` et qu'aucun visitor code n'est stocké dans un cookie, le visitor code sera généré aléatoirement. ##### Valeur de retour | Type | Description | | -------- | ---------------------- | | `string` | visitor code résultant | ##### Exceptions levées | Type | Description | | ----------------------------------------- | ------------------------------------------ | | `KameleoonException.VisitorCodeMaxLength` | La longueur du visitor code a été dépassée | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide | #### addData() La méthode `addData()` ajoute des [données de ciblage](#types-de-données) au stockage afin que d'autres méthodes puissent utiliser ces données pour décider de cibler ou non le visiteur actuel. La méthode `addData()` ne renvoie aucune valeur et n'interagit pas elle-même avec les serveurs back-end de Kameleoon. À la place, toutes les données déclarées sont enregistrées en vue d'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. Notez que la méthode [trackConversion](#trackconversion) envoie également toutes les données précédemment associées, tout comme la méthode flush. Il en va de même pour les méthodes [getFeatureFlagVariationKey](/developer-docs/sdks/web-sdks/js-sdk#getfeatureflagvariationkey) et [getFeatureFlagVariable](/developer-docs/sdks/web-sdks/js-sdk#getfeatureflagvariable), 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` fait exception. Les visiteurs peuvent avoir une instance de `CustomData` associée par `customDataIndex`. * Les données `userAgent` ne seront pas stockées comme les autres données, et elles seront envoyées avec chaque requête de tracking pour le filtrage des bots. * Pour les types de données que vous pouvez utiliser pour le ciblage, consultez les [conditions de ciblage prises en charge](#conditions-de-ciblage). ```ts theme={null} import { KameleoonClient, BrowserType, CustomData, Browser, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Create Kameleoon Data Types const browserData = new Browser(BrowserType.Chrome); const customData = new CustomData(0, 'my_data'); // -- Add a single data item (tracked by default) client.addData('my_visitor_code', browserData); // -- Add multiple data items (tracked by default) client.addData('my_visitor_code', browserData, customData); // -- Add multiple data items from array (tracked by default) const dataArr = [browserData, customData]; client.addData('my_visitor_code', ...dataArr); // -- Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API) client.addData({visitorCode: 'my_visitor_code', track: false, data: dataArr}); } init(); ``` ```js theme={null} import { KameleoonClient, CustomData, Browser, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Create Kameleoon Data Types const browserData = new Browser(BrowserType.Chrome); const customData = new CustomData(0, 'my_data'); // -- Add a single data item (tracked by default) client.addData('my_visitor_code', browserData); // -- Add multiple data items (tracked by default) client.addData('my_visitor_code', browserData, customData); // -- Add multiple data items from array (tracked by default) const dataArr = [browserData, customData]; client.addData('my_visitor_code', ...dataArr); // -- Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API) client.addData({visitorCode: 'my_visitor_code', track: false, data: dataArr}); } init(); ``` ##### Arguments | Name | Type | Description | Default value | | -------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | visitorCode (*required*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères. | | | track (*optional*) | `boolean` | Précise si les données ajoutées sont éligibles au tracking. Si défini à `false`, les données sont stockées localement et utilisées uniquement pour l'évaluation du ciblage ; elles ne sont pas envoyées à l'API Data Kameleoon. | `true` | | kameleoonData (*optional*) | `KameleoonDataType[]` | nombre d'instances de n'importe quel type de `KameleoonData`, peut être ajouté uniquement dans un tableau ou en tant qu'arguments séquentiels | | * `kameleoonData` est un argument variadique. Il peut être passé en tant qu'un ou plusieurs arguments (voir l'exemple). * L'index ou l'ID de la [custom data](/user-manual/assets/custom-data/create-custom-data) se trouve dans votre compte Kameleoon. Notez que cet index commence à `0`, ce qui signifie que la première custom data que vous créez pour un site donné aura `0` comme ID, et non `1`. ##### Exceptions levées | Type | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------------------ | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale de 255 caractères. | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.StorageWrite` | Impossible de mettre à jour les données du stockage. | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à `initialize`. | Consultez la référence [Types de données](#types-de-données) pour plus de détails sur la façon de gérer les différents types de données. #### flush() La méthode `flush()` collecte les données Kameleoon associées au visiteur. Elle envoie ensuite une requête de tracking, accompagnée de toutes les données ajoutées via la méthode `addData`, qui n'ont pas encore été envoyées via l'une de [ces méthodes](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics). Si vous ne spécifiez pas de `visitorCode`, le SDK envoie toutes ses données stockées vers les serveurs Kameleoon distants. Si des requêtes de tracking précédemment échouées ont été stockées localement en [mode offline](#initialize), le SDK tente d'envoyer les requêtes stockées avant d'exécuter la dernière requête. `isUniqueIdentifier` peut être utile dans des situations particulières ; par exemple, si vous ne pouvez pas accéder au `visitorCode` anonyme attribué à un visiteur, mais que vous pouvez utiliser un ID interne lié à ce visiteur via la fusion de sessions. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); const customData = new CustomData(0, 'my_data'); client.addData(visitorCode, customData); // -- Flush added custom data for visitor client.flush(visitorCode); // -- Flush data for all the visitors client.flush(); // -- Flush data with unique visitor identifier flag const internalUserId = 'my_user_id'; client.flush(internalUserId, true); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); const customData = new CustomData(0, 'my_data'); client.addData(visitorCode, customData); // -- Flush added custom data for visitor client.flush(visitorCode); // -- Flush data for all the visitors client.flush(); // -- Flush data with unique visitor identifier flag const internalUserId = 'my_user_id'; client.flush(internalUserId, true); } init(); ``` ##### Arguments | Name | Type | Description | Default | | ------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | visitorCode (*optional*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères ; si non fourni, toutes les données seront envoyées (vers les serveurs Kameleoon distants). | - | | isUniqueIdentifier (*optional*) | `boolean` | un paramètre optionnel pour spécifier si le `visitorCode` est un identifiant unique. | `false` | ##### Exceptions levées | Type | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------------------ | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à `initialize`. | `flush()` prend les données Kameleoon associées à un visiteur et programme l'envoi de ces données dans la prochaine requête de tracking. Le moment de la prochaine requête de tracking est défini par le paramètre [`trackingInterval`](#configuration-parameters) de la configuration du SDK. Les données du visiteur peuvent être ajoutées via les méthodes [addData](#adddata) et [getRemoteVisitorData](#getremotevisitordata). Si vous ne spécifiez pas de `visitorCode`, le SDK envoie toutes ses données stockées vers les serveurs Kameleoon distants. Si des requêtes de tracking précédemment échouées ont été stockées localement en [mode offline](#initialize), le SDK tente d'envoyer les requêtes stockées avant d'exécuter la dernière requête. Si vous devez envoyer des requêtes de tracking immédiatement, utilisez `flushInstant()` — la version asynchrone de `flush` qui renvoie `Promise`. Vous pouvez utiliser `await` lorsque vous avez besoin de garanties de livraison (par exemple, avant la navigation/le déchargement de la page), ou l'appeler sans `await` en mode fire-and-forget : * `await client.flushInstant(visitorCode)` envoie immédiatement les requêtes de tracking pour un visiteur spécifique et attend la fin * `await client.flushInstant()` envoie immédiatement les requêtes de tracking pour tous les visiteurs et attend la fin ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); const customData = new CustomData(0, 'my_data'); client.addData(visitorCode, customData); // -- Flush added custom data for visitor client.flush(visitorCode); // -- Instantly flush added custom data for visitor (fire-and-forget) client.flushInstant(visitorCode); // -- Instantly flush added custom data for visitor and wait for completion await client.flushInstant(visitorCode); // -- Flush data for all the visitors client.flush(); // -- Instantly flush data for all the visitors (fire-and-forget) client.flushInstant(); // -- Instantly flush data for all the visitors and wait for complention await client.flushInstant(); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); const customData = new CustomData(0, 'my_data'); client.addData(visitorCode, customData); // -- Flush added custom data for visitor client.flush(visitorCode); // -- Instantly flush added custom data for visitor client.flush({ visitorCode, instant: true }); // -- Flush data for all the visitors client.flush(); // -- Instantly flush data for all the visitors client.flush({ instant: true }); } init(); ``` ##### Arguments | Name | Type | Description | Default | | ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | visitorCode (*optional*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères ; si non fourni, toutes les données seront envoyées (vers les serveurs Kameleoon distants). | - | Ou un objet de type FlushParamsType contenant : | Name | Type | Description | Default | | ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | visitorCode (*optional*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères ; si non fourni, toutes les données seront envoyées (vers les serveurs Kameleoon distants). | - | | instant (*optional*) | `boolean` | Indicateur booléen précisant si les données doivent être envoyées immédiatement (`true`) ou selon l'intervalle de tracking planifié (`false`). | - | ##### Exceptions levées | Type | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------------------ | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à `initialize`. | #### getRemoteData() La méthode `getRemoteData()` renvoie les données stockées pour un site code spécifié sur un serveur Kameleoon distant. Vous pouvez utiliser cette méthode pour récupérer les préférences utilisateur, des données historiques ou toute autre donnée pertinente pour la logique de votre application. En stockant ces données sur nos serveurs hautement évolutifs via notre API Data, vous pouvez gérer efficacement de grandes quantités de données et les récupérer pour chacun de vos visiteurs ou utilisateurs. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Get remote data const jsonData = await getRemoteData('my_data_key'); const data = JSON.parse(jsonData); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Get remote data const jsonData = await getRemoteData('my_data_key'); const data = JSON.parse(jsonData); } init(); ``` ##### Arguments | Name | Type | Description | | ---------------- | -------- | ------------------------------------------------- | | key (*required*) | `string` | clé unique à laquelle les données sont associées. | ##### Valeur de retour | Type | Description | | ---------- | ------------------------------------------------------------ | | `JSONType` | promesse avec les données récupérées pour une clé spécifique | ##### Exceptions levées | Type | Description | | ------------------------------- | ---------------------------------------------------------------- | | `KameleoonException.RemoteData` | Impossible de récupérer les données depuis le serveur Kameleoon. | #### getRemoteVisitorData() `getRemoteVisitorData()` est une méthode asynchrone utilisée pour récupérer les données de visites Kameleoon pour le `visitorCode` depuis l'API Data Kameleoon. Cette méthode stocke les données pour prendre des décisions de ciblage. Les données obtenues par cette méthode sont importantes lorsque vous souhaitez : * utiliser des données collectées depuis d'autres appareils. * accéder à l'historique d'un utilisateur, comme les pages précédemment visitées lors des visites passées. * utiliser des données accessibles uniquement côté client, comme les variables du datalayer et les objectifs qui ne convertissent que sur le 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, `getRemoteVisitorData()` récupère automatiquement les dernières custom data stockées avec `scope=Visitor` et les attache au visiteur sans qu'il soit nécessaire d'appeler la méthode `addData()`. 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). `isUniqueIdentifier` peut être utile dans des situations particulières ; par exemple, si vous ne pouvez pas accéder au `visitorCode` anonyme attribué à un visiteur, mais que vous pouvez utiliser un ID interne lié à ce visiteur via la fusion de sessions. ```ts theme={null} import { KameleoonClient, KameleoonDataType, VisitorDataFiltersType, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Get remote visitor data and add it to storage const kameleoonDataList: KameleoonDataType[] = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', }); // -- Get remote visitor data without adding it to storage const kameleoonDataList: KameleoonDataType[] = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', shouldAddData: false, }); // -- Get remote visitor data without adding it to storage, // and customizing filters for retrieving visits data const filters: VisitorDataFiltersType = { currentVisit: true, previousVisitAmount: 10, customData: true, geolocation: true, conversions: true, }; const kameleoonDataList: KameleoonDataType[] = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', shouldAddData: false, filters, }); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Get remote visitor data and add it to storage const kameleoonDataList = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', }); // -- Get remote visitor data without adding it to storage const kameleoonDataList = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', shouldAddData: false, }); // -- Get remote visitor data without adding it to storage, // and customizing filters for retrieving visits data const filters = { currentVisit: true, previousVisitAmount: 10, customData: true, geolocation: true, conversions: true, }; const kameleoonDataList = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', shouldAddData: false, filters, }); } init(); ``` ##### Arguments Un objet de type `RemoteVisitorDataParamsType` contenant : | Name | Type | Description | Default Value | | ------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | visitorCode (*required*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères. | - | | shouldAddData (*optional*) | `boolean` | indicateur booléen précisant si les custom data récupérées doivent être ajoutées automatiquement au stockage (sans avoir à appeler la méthode `addData` ensuite). | `true` | | filters (*optional*) | `VisitorDataFiltersType` | filtres précisant quelles données doivent être récupérées depuis les visites ; par défaut, seules les `customData` sont récupérées depuis la visite actuelle et la dernière visite précédente. | `{ previousVisitAmount: 1, currentVisit: true customData: true }`, les autres paramètres de filtres sont définis à `false` | | isUniqueIdentifier (*optional*) | `boolean` | paramètre optionnel qui, lorsqu'il vaut `true`, indique que le `visitorCode` est un identifiant unique. | `false` | ##### Valeur de retour | Type | Description | | --------------------- | ---------------------------------------------------- | | `KameleoonDataType[]` | promesse avec la liste des Kameleoon Data récupérées | ##### Exceptions levées | Type | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------------ | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères) | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide | | `KameleoonException.RemoteData` | Impossible de récupérer les données depuis le serveur Kameleoon | | `KameleoonException.VisitAmount` | Le nombre de visites doit être un nombre entre 1 et 25 | | `KameleoonException.Initialization` | La méthode a été exécutée avant que `initialize` n'ait été effectué pour `kameleoonClient` | ##### Utilisation des paramètres dans getRemoteVisitorData() La méthode `getRemoteVisitorData()` offre de la flexibilité en vous permettant de définir divers paramètres lors de la récupération des données sur les visiteurs. Que vous cibliez en fonction d'objectifs, d'expériences ou de variations, la même approche s'applique à tous les types de données. Par exemple, si vous souhaitez récupérer les données sur les visiteurs ayant atteint l'objectif "Order transaction", vous pouvez spécifier des paramètres dans la méthode `getRemoteVisitorData()` pour affiner votre ciblage. Par exemple, si vous voulez cibler uniquement les utilisateurs qui ont converti sur l'objectif lors de leurs cinq dernières visites, vous pouvez définir le paramètre `previousVisitAmount` à 5 et `conversions` à true. La flexibilité illustrée dans cet exemple ne se limite pas aux données d'objectifs. Vous pouvez utiliser les paramètres de la méthode `getRemoteVisitorData()` pour récupérer des données sur une variété de comportements de visiteurs. Voici la liste des filtres `VisitorDataFiltersType` disponibles : | Name | Type | Description | Default | | -------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | | previousVisitAmount (*optional*) | `number` | Nombre de visites précédentes desquelles récupérer les données. Nombre entre `1` et `25` | `1` | | currentVisit (*optional*) | `boolean` | Si true, les données de la visite actuelle seront récupérées | `true` | | customData (*optional*) | `boolean` | Si true, les custom data seront récupérées. | `true` | | pageViews (*optional*) | `boolean` | Si true, les données de page seront récupérées. | `false` | | geolocation (*optional*) | `boolean` | Si true, les données de géolocalisation seront récupérées. | `false` | | device (*optional*) | `boolean` | Si true, les données de device seront récupérées. | `false` | | browser (*optional*) | `boolean` | Si true, les données de navigateur seront récupérées. | `false` | | operatingSystem (*optional*) | `boolean` | Si true, les données du système d'exploitation seront récupérées. | `false` | | conversions (*optional*) | `boolean` | Si true, les données de conversion seront récupérées. | `false` | | experiments (*optional*) | `boolean` | Si true, les données d'expérience seront récupérées. | `false` | | kcs (*optional*) | `boolean` | Si true, le Kameleoon Conversion Score (KCS) sera récupéré. Nécessite l'[add-on AI Predictive Targeting](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) | `false` | `getRemoteVisitorData()` est une méthode asynchrone pour récupérer les données de visites Kameleoon pour le `visitorCode` depuis l'API Data Kameleoon. La méthode ajoute des données au stockage pour que d'autres méthodes les utilisent lors de la prise de décisions de ciblage. Les données obtenues par cette méthode sont importantes lorsque vous souhaitez : * utiliser des données collectées depuis d'autres appareils. * accéder à l'historique d'un utilisateur, comme les pages précédemment visitées lors des visites passées. * utiliser des données accessibles uniquement côté client, comme les variables du datalayer et les objectifs qui ne convertissent que sur le 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, `getRemoteVisitorData()` récupère automatiquement les dernières custom data stockées avec `scope=Visitor` et les attache au visiteur sans qu'il soit nécessaire d'appeler la méthode `addData()`. 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). ```ts theme={null} import { KameleoonClient, KameleoonDataType, VisitorDataFiltersType, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Get remote visitor data and add it to storage const kameleoonDataList: KameleoonDataType[] = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', }); // -- Get remote visitor data without adding it to storage const kameleoonDataList: KameleoonDataType[] = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', shouldAddData: false, }); // -- Get remote visitor data without adding it to storage, // and customizing filters for retrieving visits data const filters: VisitorDataFiltersType = { currentVisit: true, previousVisitAmount: 10, customData: true, geolocation: true, conversions: true, }; const kameleoonDataList: KameleoonDataType[] = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', shouldAddData: false, filters, }); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Get remote visitor data and add it to storage const kameleoonDataList = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', }); // -- Get remote visitor data without adding it to storage const kameleoonDataList = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', shouldAddData: false, }); // -- Get remote visitor data without adding it to storage, // and customizing filters for retrieving visits data const filters = { currentVisit: true, previousVisitAmount: 10, customData: true, geolocation: true, conversions: true, }; const kameleoonDataList = await getRemoteVisitorData({ visitorCode: 'my_visitor_code', shouldAddData: false, filters, }); } init(); ``` ##### Arguments Un objet de type `RemoteVisitorDataParamsType` contenant : | Name | Type | Description | Default Value | | -------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | visitorCode (*required*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères | - | | shouldAddData (*optional*) | `boolean` | indicateur booléen précisant si les custom data récupérées doivent être ajoutées automatiquement au stockage (sans avoir à appeler la méthode `addData` ensuite) | `true` | | filters (*optional*) | `VisitorDataFiltersType` | filtres précisant quelles données doivent être récupérées depuis les visites ; par défaut, seules les `customData` sont récupérées depuis la visite actuelle et la dernière visite précédente | `{ previousVisitAmount: 1, currentVisit: true customData: true }`, les autres paramètres de filtres sont définis à `false` | ##### Valeur de retour | Type | Description | | --------------------- | ---------------------------------------------------- | | `KameleoonDataType[]` | promesse avec la liste des Kameleoon Data récupérées | ##### Exceptions levées | Type | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------------ | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères) | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide | | `KameleoonException.RemoteData` | Impossible de récupérer les données depuis le serveur Kameleoon | | `KameleoonException.VisitAmount` | Le nombre de visites doit être un nombre entre 1 et 25 | | `KameleoonException.Initialization` | La méthode a été exécutée avant que `initialize` n'ait été effectué pour `kameleoonClient` | ##### Utilisation des paramètres dans getRemoteVisitorData() The `getRemoteVisitorData()` method offers flexibility, allowing you to define various parameters when retrieving data on visitors. Whether you're targeting based on goals, experiments, or variations, the same approach applies across all data types. Par exemple, si vous souhaitez récupérer les données sur les visiteurs ayant atteint l'objectif "Order transaction", vous pouvez spécifier des paramètres dans la méthode `getRemoteVisitorData()` pour affiner votre ciblage. Par exemple, si vous voulez cibler uniquement les utilisateurs qui ont converti sur l'objectif lors de leurs cinq dernières visites, vous pouvez définir le paramètre `previousVisitAmount` à 5 et `conversions` à true. La flexibilité illustrée dans cet exemple ne se limite pas aux données d'objectifs. Vous pouvez utiliser les paramètres de la méthode `getRemoteVisitorData()` pour récupérer des données sur une variété de comportements de visiteurs. Voici la liste des filtres `VisitorDataFiltersType` disponibles : | Name | Type | Description | Default | | -------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | previousVisitAmount (*optional*) | `number` | Nombre de visites précédentes desquelles récupérer les données. Nombre entre `1` et `25` | `1` | | currentVisit (*optional*) | `boolean` | Si true, les données de la visite actuelle seront récupérées | `true` | | customData (*optional*) | `boolean` | Si true, les custom data seront récupérées. | `true` | | pageViews (*optional*) | `boolean` | Si true, les données de page seront récupérées. | `false` | | geolocation (*optional*) | `boolean` | Si true, les données de géolocalisation seront récupérées. | `false` | | device (*optional*) | `boolean` | Si true, les données de device seront récupérées. | `false` | | browser (*optional*) | `boolean` | Si true, les données de navigateur seront récupérées. | `false` | | operatingSystem (*optional*) | `boolean` | Si true, les données du système d'exploitation seront récupérées. | `false` | | conversions (*optional*) | `boolean` | Si true, les données de conversion seront récupérées. | `false` | | experiments (*optional*) | `boolean` | Si true, les données d'expérience seront récupérées. | `false` | | kcs (*optional*) | `boolean` | Si true, le Kameleoon Conversion Score (KCS) sera récupéré. Nécessite l'[add-on AI Predictive Targeting](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) | `false` | | visitorCode (*optional*) | `boolean` | Si true, Kameleoon récupérera le `visitorCode` de la visite la plus récente et l'utilisera pour la visite actuelle. Cela est nécessaire si vous voulez vous assurer que le visiteur, identifié par son `visitorCode`, reçoit toujours la même variation entre les visites pour l'[expérimentation cross-device](/developer-docs/cross-device-experimentation). | `true` | | personalization (*optional*) | `boolean` | Si true, les données de personnalisation seront récupérées. Ceci est requis pour la condition de personnalisation | `false` | | cbs (*optional*) | `boolean` | Si true, les données du score Contextual Bandit seront récupérées. | `false` | #### getVisitorWarehouseAudience() `getVisitorWarehouseAudience` est une méthode asynchrone qui récupère toutes les données d'audience associées au visiteur dans votre data warehouse en utilisant les `visitorCode` et `warehouseKey` spécifiés. Le `warehouseKey` est généralement votre user ID interne. Le paramètre `customDataIndex` correspond à la custom data Kameleoon que Kameleoon utilise pour cibler vos visiteurs. Reportez-vous à la [documentation sur le ciblage warehouse](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) pour plus de détails. ```ts theme={null} import { KameleoonClient, KameleoonDataType, CustomData, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Get visitor warehouse audience data using `warehouseKey` // and add it to storage const customData: CustomData = await getVisitorWarehouseAudience({ visitorCode: 'my_visitor', customDataIndex: 10, warehouseKey: 'my_key', }); // -- Get visitor warehouse audience data using `visitorCode` // and add it to storage const customData: CustomData = await getVisitorWarehouseAudience({ visitorCode: 'my_visitor', customDataIndex: 10, }); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Get visitor warehouse audience data using `warehouseKey` // and add it to storage const customData = await getVisitorWarehouseAudience({ visitorCode: 'my_visitor', customDataIndex: 10, warehouseKey: 'my_key', }); // -- Get visitor warehouse audience data using `visitorCode` // and add it to storage const customData = await getVisitorWarehouseAudience({ visitorCode: 'my_visitor', customDataIndex: 10, }); } init(); ``` ##### Arguments Objet de paramètres composé de : | Name | Type | Description | | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- | | visitorCode (*required*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères | | customDataIndex (*required*) | `number` | nombre représentant l'index de la custom data que vous souhaitez utiliser pour cibler vos Warehouse Audiences | | warehouseKey (*optional*) | `string` | clé unique pour identifier les données du warehouse (généralement, votre user ID interne) | ##### Valeur de retour | Type | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------- | | `Promise` | promesse contenant CustomData avec les données warehouse associées ou `null` s'il n'y avait pas de données | ##### Exceptions levées | Type | Description | | ----------------------------------------- | --------------------------------------------------------------- | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères) | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide | | `KameleoonException.RemoteData` | Impossible de récupérer les données depuis le serveur Kameleoon | #### setLegalConsent() Les informations de consentement sont synchronisées entre l'Engine Kameleoon (fichier d'application `engine.js`) et le SDK JS. Cette synchronisation signifie qu'une fois que le consentement est défini sur l'Engine ou sur le SDK, il est automatiquement défini pour les deux. Cette fonctionnalité élimine le besoin de gestion manuelle du consentement et garantit que les SDK fonctionnent en conformité avec les préférences de l'utilisateur. Si vous utilisez Kameleoon en mode hybride, nous vous recommandons de lire la section sur le consentement dans notre [article sur l'expérimentation hybride](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/#managing-consent-in-hybrid-mode) Lors de la gestion du consentement légal, il est important d'utiliser la méthode [`getVisitorCode`](#getvisitorcode) de `KameleoonClient`, et non la méthode obsolète de `KameleoonUtils`. De plus, cette méthode n'accepte pas `domain` comme argument. À la place, transmettez-le au constructeur de `KameleoonClient`. Reportez-vous à l'exemple ci-dessus. La méthode `setLegalConsent` spécifie si le visiteur a donné son consentement légal pour l'utilisation de données personnelles. Définir le paramètre `legalConsent` à `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 les données des visiteurs de manière responsable. Vous trouverez plus d'informations sur les données personnelles dans la [politique de gestion du consentement](/user-manual/project-management/consent-management-policy). ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); const visitorCode = client.getVisitorCode(); client.setLegalConsent(visitorCode, true); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); const visitorCode = client.getVisitorCode(); client.setLegalConsent(visitorCode, true); } init(); ``` ##### Arguments | Name | Type | Description | | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | visitorCode (*required*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères. length | | consent (*required*) | `boolean` | une valeur booléenne représentant l'état du consentement légal. `true` indique que le visiteur a donné son consentement légal. `false` indique que le visiteur n'a jamais fourni ou a retiré son consentement légal. | ##### Exceptions levées | Type | Description | | ----------------------------------------- | --------------------------------------------------------------------------- | | `KameleoonException.VisitorCodeMaxLength` | La longueur du visitor code a dépassé la longueur maximale (255 caractères) | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide | ##### Comportement lors de la révocation du consentement Lorsque vous appelez `setLegalConsent()` avec `consent=false`, le SDK ne supprime pas le cookie `kameleoonVisitorCode`. À la place, il cesse de prolonger la date d'expiration du cookie, laissant le cookie persister jusqu'à son expiration naturelle. Si vos exigences de conformité nécessitent la suppression immédiate du fichier cookie lors de l'opt-out, vous devez le supprimer manuellement en utilisant les méthodes de gestion des cookies natives de votre framework. Le SDK ne supprimera pas le fichier automatiquement. ### Objectifs et analytics tierces #### trackConversion() * 📨 *Envoie des données de tracking à Kameleoon* Utilisez cette méthode pour suivre une conversion pour un [objectif](/user-manual//assets/goals/create-a-goal) et un utilisateur spécifiques. Cette méthode nécessite `visitorCode` et `goalId`. De plus, cette méthode accepte également un argument optionnel `revenue`. Le `visitorCode` est généralement identique à celui qui a été utilisé lors du déclenchement de l'expérience. La méthode `trackConversion()` ne renvoie aucune valeur. Cette méthode est non bloquante car l'appel serveur est effectué de manière asynchrone. Si vous spécifiez un `visitorCode` et définissez `isUniqueIdentifier` à `true`, la méthode `trackConversion()` l'utilise comme identifiant unique du visiteur, ce qui est utile pour l'[expérimentation cross-device](#expérimentation-cross-device) car le SDK lie les données envoyées au visiteur associé à l'identifiant spécifié. `isUniqueIdentifier` peut également être utile dans d'autres scénarios particuliers, par exemple lorsque vous ne pouvez pas accéder au `visitorCode` anonyme initialement attribué au visiteur, mais que vous avez accès à un ID interne connecté au visiteur anonyme via les fonctionnalités de fusion de sessions. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { const experimentId = 123; await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Track conversion client.trackConversion({ visitorCode, revenue: 20000, goalId: 123 }); // -- Track conversion with unique visitor identifier flag const internalUserId = 'my_user_id'; client.trackConversion({ visitorCode: internalUserId, revenue: 20000, goalId: 123, isUniqueIdentifier: true, }); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { const experimentId = 123; await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Track conversion client.trackConversion({ visitorCode, revenue: 20000, goalId: 123 }); // -- Track conversion with unique visitor identifier flag const internalUserId = 'my_user_id'; client.trackConversion({ visitorCode: internalUserId, revenue: 20000, goalId: 123, isUniqueIdentifier: true, }); } init(); ``` ##### Arguments Objet de paramètres composé de : | Name | Type | Description | Default | | ------------------------------- | --------- | ---------------------------------------------------------------------------------- | ------- | | visitorCode (*required*) | `string` | Identifiant unique du visiteur. | | | goalId (*required*) | `number` | ID de l'objectif. | | | revenue (*optional*) | `number` | Revenu de la conversion. | `0` | | isUniqueIdentifier (*optional*) | `boolean` | Un paramètre optionnel pour spécifier si le visitorCode est un identifiant unique. | `false` | ##### Exceptions levées | Type | Description | | ----------------------------------------- | ---------------------------------------------------------------- | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.StorageWrite` | Impossible de mettre à jour les données du stockage. | * 📨 *Envoie des données de tracking à Kameleoon* Utilisez cette méthode pour suivre une conversion pour un [objectif](/user-manual//assets/goals/create-a-goal) et un utilisateur spécifiques. Cette méthode nécessite `visitorCode` et `goalId`. De plus, cette méthode accepte également des arguments optionnels `revenue`, `negative` et `metadata`. Le `visitorCode` est généralement identique à celui qui a été utilisé lors du déclenchement de l'expérience. La méthode `trackConversion()` ne renvoie aucune valeur. Cette méthode est non bloquante car l'appel serveur est effectué de manière asynchrone. ```ts theme={null} import { KameleoonClient, CustomData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { const experimentId = 123; await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Track conversion client.trackConversion({ visitorCode, revenue: 20000, goalId: 123, metadata: [new CustomData(0, 'value')], negative: true, }); } init(); ``` ```js theme={null} import { KameleoonClient, CustomData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { const experimentId = 123; await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Track conversion client.trackConversion({ visitorCode, revenue: 20000, goalId: 123, metadata: [new CustomData(0, 'value')], negative: true, }); } init(); ``` ##### Arguments Objet de paramètres composé de : | Name | Type | Description | Default | | ------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | visitorCode (*required*) | `string` | Identifiant unique du visiteur. | | | goalId (*required*) | `number` | ID de l'objectif. | | | negative (*optional*) | `boolean` | Définit si le revenu est positif ou négatif. | `false` | | revenue (*optional*) | `number` | Revenu de la conversion. | `0` | | metadata (*optional*) | `CustomData[]` | Metadata de la conversion. [Doit être défini au préalable dans l'application Kameleoon](/fr/user-manual/assets/goals/create-a-goal#métadonnées). | `undefined` | Les valeurs de metadata sont accessibles via les [exports de données brutes](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export) et [la page de résultats](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata). Si le paramètre `metadata` est fourni, Kameleoon utilisera ces valeurs spécifiées pour la conversion actuelle au lieu de ce qui avait été précédemment collecté via la méthode [`addData()`](#adddata). Si le paramètre est omis, Kameleoon utilisera les dernières valeurs trackées pour ces [`CustomData`](#customdata) avant la conversion et au cours de la même visite. Kameleoon ne prendra en compte que les valeurs de metadata explicitement transmises comme paramètres à la méthode `trackConversion()`. Dans l'exemple ci-dessous, Kameleoon n'associera la conversion qu'à la valeur de custom data explicitement fournie en paramètre (ici : index 5 avec la valeur 'Amex Credit Card'). ```ts theme={null} kameleoonClient.addData(visitorCode, new CustomData(5, 'Credit Card'), new CustomData(9, 'Express Delivery')); kameleoonClient.trackConversion({ visitorCode, goalId: 1000, metadata: [new CustomData(5, 'Amex Credit Card')] }); ``` ```js theme={null} kameleoonClient.addData(visitorCode, new CustomData(5, 'Credit Card'), new CustomData(9, 'Express Delivery')); kameleoonClient.trackConversion({ visitorCode, goalId: 1000, metadata: [new CustomData(5, 'Amex Credit Card')] }); ``` ##### Exceptions levées | Type | Description | | ----------------------------------------- | ---------------------------------------------------------------- | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.StorageWrite` | Impossible de mettre à jour les données du stockage. | *** #### getEngineTrackingCode() Kameleoon s'intègre à plusieurs solutions d'analytics, notamment Mixpanel, Google Analytics 4 et Segment. Pour tracker correctement les expériences côté serveur, appelez la méthode `getEngineTrackingCode()` après que le visiteur a déclenché une expérience. Le SDK renvoie 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 d'analytics active. Reportez-vous à l'[expérimentation hybride](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) pour plus d'informations sur l'implémentation de cette méthode. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Trigger feature experiment // -- E.g., result `variationKey` id is `200`, and implicit experiment id is `100`. client.getVariation({ visitorCode: 'visitor_code', featureKey: 'my_feature_key' }); // -- Get tracking code const engineCode = client.getEngineTrackingCode('visitor_code'); // -- Result engine code will look like this // ` // window.kameleoonQueue = window.kameleoonQueue || []; // window.kameleoonQueue.push(['Experiments.assignVariation', 100, 200, true]); // window.kameleoonQueue.push(['Experiments.trigger', 100, true]); // ` // -- Insert tracking code into the page const script = document.createElement('script'); script.textContent = engineCode; document.body.appendChild(script); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Trigger feature experiment // -- E.g., result `variationKey` id is `200`, and implicit experiment id is `100` client.getVariation({ visitorCode: 'visitor_code', featureKey: 'my_feature_key' }); // -- Get tracking code const engineCode = client.getEngineTrackingCode('visitor_code'); // -- Result engine code will look like this // ` // window.kameleoonQueue = window.kameleoonQueue || []; // window.kameleoonQueue.push(['Experiments.assignVariation', 100, 200, true]); // window.kameleoonQueue.push(['Experiments.trigger', 100, true]); // ` // -- Insert tracking code into the page const script = document.createElement('script'); script.textContent = engineCode; document.body.appendChild(script); } init(); ``` * Pour utiliser cette fonctionnalité, implémentez à la fois le SDK JavaScript et l'[Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation) de Kameleoon. É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. * Vous pouvez insérer le code de tracking renvoyé directement dans une balise HTML ` ``` Dans cet exemple, `123456` et `234567` sont des IDs d'expérience, et `7890` et `8901` sont des IDs de variation. Dans votre implémentation, le SDK génère ces valeurs dans le code de tracking renvoyé. ##### Arguments | Name | Type | Description | | ------------------------ | -------- | ------------------------------- | | visitorCode (*required*) | `string` | Identifiant unique du visiteur. | ##### Valeur de retour | Type | Description | | -------- | --------------------------------------- | | `string` | Code JavaScript à insérer dans la page. | ##### Exceptions levées | Type | Description | | ----------------------------------------- | ---------------------------------------------------------------------------- | | `KameleoonException.VisitorCodeMaxLength` | La longueur du visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | ### Événements #### Envoi d'événements d'exposition vers des outils externes Kameleoon propose des intégrations natives avec diverses solutions d'analytics et de CDP, telles que [Mixpanel, Google Analytics 4, Segment...](/user-manual/integrations/integrations-overview). Pour vous permettre de tracker et d'analyser vos expériences côté serveur, Kameleoon fournit une méthode, `getEngineTrackingCode()`, qui renvoie le code JavaScript à insérer dans votre page. Le code envoie automatiquement les événements d'exposition à votre solution d'analytics. Le SDK construit un code de tracking pour votre solution d'analytics active à partir des expériences que le visiteur a déclenchées au cours des cinq dernières secondes. Pour plus d'informations sur l'expérimentation hybride, veuillez consulter cet [article](/developer-docs/feature-experimentation/get-started/hybrid-experimentation). La méthode `getEngineTrackingCode()` renvoie le code de tracking Kameleoon pour le visiteur actuel. Le code de tracking est basé sur les expériences qui ont été déclenchées au cours des cinq dernières secondes. Pour bénéficier de cette fonctionnalité, vous devrez implémenter à la fois le SDK JavaScript et notre tag JavaScript Kameleoon. Nous vous recommandons d'implémenter le tag asynchrone Kameleoon, que vous pouvez installer avant la balise `` de fermeture dans votre page HTML, car il ne sera utilisé qu'à des fins de tracking. #### onEvent() La méthode `onEvent()` déclenche un callback lorsqu'un événement spécifique est déclenché. La fonction callback peut accéder aux données associées à l'événement. Les méthodes du SDK dans cette documentation indiquent quels types d'événements elles déclenchent, le cas échéant. Vous ne pouvez attribuer qu'un seul callback à chaque `EventType`. ```ts theme={null} import { KameleoonClient, EventType, EvaluationEventDataType, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Define logic to be executed on SDK event client.onEvent(EventType.Evaluation, (eventData: EvaluationEventDataType) => { // -- My Logic }); } init(); ``` ```js theme={null} import { KameleoonClient, EventType } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Define logic to be executed on SDK event client.onEvent(EventType.Evaluation, (eventData) => { // -- My Logic }); } init(); ``` ##### Événements Les événements sont définis dans l'enum `EventType`. Selon le type d'événement, le paramètre `eventData` aura un type différent. | Type | `eventData` type | Description | | ------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `EventType.Evaluation` | `EvaluationEventDataType` | Déclenché lorsque le SDK évalue n'importe quelle variation pour un feature flag. Il est déclenché quel que soit le résultat de la variation. | | `EventType.ConfigurationUpdate` | `ConfigurationUpdateEventDataType` | Déclenché lorsque le SDK reçoit une mise à jour de configuration depuis le serveur (lors de l'utilisation du streaming en temps réel). | ##### Arguments | Name | Type | Description | | --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | event (*required*) | `EventType` | un type d'événement à associer au callback. | | callback (*required*) | `(eventData: EventDataType) => void` | une fonction callback avec le paramètre `eventData` qui est appelée lors d'une mise à jour de configuration. | ##### Exceptions levées | Type | Description | | ----------------------------------- | ---------------------------------------------------------------------------------------------- | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé l'appel à `initialize`. | *** ##### Envoi d'événements d'exposition vers des outils externes Kameleoon propose des intégrations natives avec diverses solutions d'analytics et de CDP, telles que [Mixpanel, Google Analytics 4, Segment...](/user-manual/integrations/integrations-overview). Pour vous permettre de tracker et d'analyser vos expériences côté serveur, Kameleoon fournit une méthode, `getEngineTrackingCode()`, qui renvoie le code JavaScript à insérer dans votre page. Le code envoie automatiquement les événements d'exposition à votre solution d'analytics. Le SDK construit un code de tracking pour votre solution d'analytics active à partir des expériences que le visiteur a déclenchées au cours des cinq dernières secondes. Pour plus d'informations sur l'expérimentation hybride, veuillez consulter cet [article](/developer-docs/feature-experimentation/get-started/hybrid-experimentation). La méthode `getEngineTrackingCode()` renvoie le code de tracking Kameleoon pour le visiteur actuel. Le code de tracking est basé sur les expériences qui ont été déclenchées au cours des cinq dernières secondes. Pour bénéficier de cette fonctionnalité, vous devrez implémenter à la fois le SDK JavaScript et notre tag JavaScript Kameleoon. Nous vous recommandons d'implémenter le tag asynchrone Kameleoon, que vous pouvez installer avant la balise `` de fermeture dans votre page HTML, car il ne sera utilisé qu'à des fins de tracking. *** ### Types de données Les types Kameleoon Data sont des classes utilitaires utilisées pour stocker des données dans le stockage sous des formes prédéfinies. Lors de l'exécution de [flush](#flush), le SDK collecte toutes les données et les envoie avec la requête de tracking. Les données disponibles dans le SDK ne sont pas disponibles pour le ciblage et le reporting dans l'application Kameleoon tant que vous ne les ajoutez pas (par exemple, en utilisant la méthode `addData()`). Consultez [utiliser l'historique des visites pour cibler les utilisateurs](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) pour plus d'informations. Si vous utilisez le mode hybride, appelez `getRemoteVisitorData()` pour remplir automatiquement toutes les données que Kameleoon a précédemment collectées. #### Browser Depuis le SDK JavaScript `4.10.0`, `Browser` est automatiquement détecté à partir de la chaîne `User-Agent`. Cependant, vous pouvez toujours le remplacer manuellement si nécessaire. `Browser` contient des informations sur le navigateur. Chaque visiteur ne peut avoir qu'un seul `Browser`. Ajouter un second `Browser` remplace le premier. | Name | Type | Description | | -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------ | | browser (*required*) | `BrowserType` | type de navigateur prédéfini (`Chrome`, `InternetExplorer`, `Firefox`, `Safari`, `Opera`, `Other`). | | version (*optional*) | `number` | version du navigateur, le nombre à virgule flottante représente la version majeure et mineure du navigateur. | ```ts theme={null} import { KameleoonClient, BrowserType, Browser, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Add new browser data to client const browser = new Browser(BrowserType.Chrome, 86.1); client.addData('my_visitor_code', browser); } init(); ``` ```js theme={null} import { KameleoonClient, BrowserType, Browser, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Add new browser data to client const browser = new Browser(BrowserType.Chrome, 86.1); client.addData('my_visitor_code', browser); } init(); ``` *** #### UniqueIdentifier Les données `UniqueIdentifier` sont utilisées comme marqueur pour l'identification unique du visiteur. Si vous ajoutez `UniqueIdentifier` pour un visiteur, `visitorCode` est utilisé comme identifiant unique du visiteur, ce qui est utile pour l'[expérimentation cross-device](/developer-docs/cross-device-experimentation). Associer un `UniqueIdentifier` à un visiteur notifie le SDK que le visiteur est lié à un autre visiteur. `isUniqueIdentifier` peut être utile dans des situations particulières ; par exemple, si vous ne pouvez pas accéder au `visitorCode` anonyme attribué à un visiteur, mais que vous pouvez utiliser un ID interne lié à ce visiteur via la fusion de sessions. Chaque visiteur ne peut avoir qu'un seul `UniqueIdentifier`. Ajouter un autre `UniqueIdentifier` remplace le premier. | Name | Type | Description | | ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------- | | value (*required*) | `boolean` | valeur indiquant si le visiteur est associé à un autre visiteur, `false` implique que le visiteur n'est associé à aucun autre visiteur. | ```ts theme={null} import { KameleoonClient, UniqueIdentifier } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Add unique identifier to a visitor client.addData('my_visitor_code', new UniqueIdentifier(true)); } init(); ``` ```js theme={null} import { KameleoonClient, UniqueIdentifier } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Add unique identifier to a visitor client.addData('my_visitor_code', new UniqueIdentifier(true)); } init(); ``` *** #### Conversion Le jeu de données `Conversion` stocké ici peut être utilisé pour filtrer les rapports d'expérience et de personnalisation par n'importe quel objectif qui y est associé. * Chaque visiteur peut avoir plusieurs objets `Conversion`. * Vous pouvez trouver le `goalId` dans l'application Kameleoon. `ConversionParametersType` conversionParameters - un objet avec les paramètres de conversion décrits ci-dessous | Name | Type | Description | Default | | --------------------- | -------------- | -------------------------------------------- | ----------- | | goalId (*required*) | `number` | ID de l'objectif. | | | revenue (*optional*) | `float` | Revenu de la conversion | `0` | | negative (*optional*) | `boolean` | Définit si le revenu est positif ou négatif. | `false` | | metadata (*optional*) | `CustomData[]` | Metadata de la conversion. | `undefined` | ```ts theme={null} import { KameleoonClient, ConversionParametersType, Conversion, CustomData, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Defined conversion parameters const conversionParameters: ConversionParametersType = { goalId: 123, revenue: 10000, negative: true, metadata: [new CustomData(0, 'value')], }; // -- Add new conversion data to client const conversion = new Conversion(conversionParameters); client.addData('my_visitor_code', conversion); } init(); ``` ```js theme={null} import { KameleoonClient, Conversion, CustomData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Defined conversion parameters const conversionParameters = { goalId: 123, revenue: 10000, negative: true, metadata: [new CustomData(0, 'value')], }; // -- Add new conversion data to client const conversion = new Conversion(conversionParameters); client.addData('my_visitor_code', conversion); } init(); ``` #### Cookie `Cookie` contient des informations sur le cookie stocké sur l'appareil du visiteur. * En général, le SDK JavaScript tentera d'utiliser un cookie `localStorage` pour les conditions. Si `localStorage` n'est pas possible, le SDK peut utiliser les données `Cookie` comme alternative. * Chaque visiteur ne peut avoir qu'un seul `Cookie`. Ajouter un second `Cookie` remplace le premier. | Name | Type | Description | | ------------------- | -------------- | ---------------------------------------------------------------------- | | cookie (*required*) | `CookieType[]` | Une liste d'objets `CookieType` composés de clés et valeurs de cookie. | ```ts theme={null} import { KameleoonClient, CookieType, Cookie } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Add new cookie data to client const cookieData: CookieType[] = [ { key: 'key_1', value: 'value_1' }, { key: 'key_2', value: 'value_2' }, ]; const cookie = new Cookie(cookieData); client.addData('my_visitor_code', cookie); } init(); ``` ```js theme={null} import { KameleoonClient, Cookie } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Add new cookie data to client const cookieData = [ { key: 'key_1', value: 'value_1' }, { key: 'key_2', value: 'value_2' }, ]; const cookie = new Cookie(cookieData); client.addData('my_visitor_code', cookie); } init(); ``` ##### Méthodes Les données `Cookie` disposent d'une méthode utilitaire statique, `fromString`, que vous pouvez utiliser pour créer un cookie en analysant une chaîne contenant des données de cookie valides. La méthode accepte une `string` comme paramètre et renvoie une instance `Cookie` initialisée. ```ts theme={null} import { Cookie } from '@kameleoon/javascript-sdk'; const cookieString = 'key_1=value_1; key_2=value_2'; const cookie: Cookie = Cookie.fromString(cookieString); // -- The result cookie will contain the following cookie array // [ // { key: 'key_1', value: 'value_1' }, // { key: 'key_2', value: 'value_2' }, // ] ``` ```js theme={null} import { Cookie } from '@kameleoon/javascript-sdk'; const cookieString = 'key_1=value_1; key_2=value_2'; const cookie = Cookie.fromString(cookieString); // -- The result cookie will contain the following cookie array // [ // { key: 'key_1', value: 'value_1' }, // { key: 'key_2', value: 'value_2' }, // ] ``` #### GeolocationData `GeolocationData` contient les détails de géolocalisation du visiteur. Chaque visiteur ne peut avoir qu'un seul `GeolocationData`. Ajouter un second `GeolocationData` remplace le premier. Un paramètre objet de type `GeolocationInfoType` contient les champs suivants : | Name | Type | Description | | ------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | country (*required*) | `string` | Le pays du visiteur. | | region (*optional*) | `string` | La région du visiteur. | | city (*optional*) | `string` | La ville du visiteur. | | postalCode (*optional*) | `string` | Le code postal du visiteur. | | coordinates (*optional*) | `[number, number]` | Tuple de coordonnées de deux valeurs de localisation (latitude et longitude). Le nombre de coordonnée représente des degrés décimaux. | ```ts theme={null} import { KameleoonClient, GeolocationData, GeolocationInfoType, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Add geolocation data const geolocationInfo: GeolocationInfoType = { country: 'France', region: 'Île-de-France', city: 'Paris', postalCode: '75008', coordinates: [48.8738, 2.295], }; const geolocationData = new GeolocationData(geolocationInfo); client.addData('my_visitor_code', geolocationData); } init(); ``` ```js theme={null} import { KameleoonClient, GeolocationData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Add geolocation data const geolocationInfo = { country: 'France', region: 'Île-de-France', city: 'Paris', postalCode: '75008', coordinates: [48.8738, 2.295], }; const geolocationData = new GeolocationData(geolocationInfo); client.addData('my_visitor_code', geolocationData); } init(); ``` *** #### CustomData `CustomData` permet d'associer facilement tout type de données à chaque visiteur. Elles peuvent ensuite être utilisées comme condition de ciblage dans les [segments](/user-manual/assets/segments/create-a-segment/) ou comme filtre/décomposition dans les rapports d'expérience. Pour en savoir plus sur les custom data, veuillez consulter cet [article](/developer-docs/custom-data). | Name | Type | Description | Default | | ----------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | index/name (*required*) | `number`/`string` | Index ou nom de la custom data. **Soit `index` soit `name` doit être fourni** pour identifier la donnée. | | | overwrite (*optional*) | `boolean` | Drapeau pour contrôler explicitement la manière dont les valeurs sont stockées et la façon dont elles apparaissent dans les rapports. [En savoir plus](/developer-docs/custom-data#default-logic-when-overwrite-parameter-is-false-or-omitted) | `true` | | value (*required*) | `string[]` | La valeur de la custom data. Elle doit être convertie en chaîne pour correspondre au type `string`. *Note :* value est variadique. | | * Chaque visiteur n'est autorisé à avoir qu'un seul `CustomData` pour chaque `index` unique. Ajouter un autre `CustomData` avec le même `index` remplacera celui existant. * L'`index` de la custom data se trouve dans le [tableau de bord Custom Data](/user-manual/assets/custom-data/manage-custom-data) sous la colonne « INDEX ». * Pour empêcher le SDK d'envoyer les données avec l'index sélectionné aux serveurs Kameleoon pour des raisons de confidentialité, activez l'option : **Use this data only locally for targeting purposes** lors de la création de la custom data. * Ajouter une instance `CustomData` créée avec un nom alors que l'instance du SDK n'est pas initialisée ou que le nom n'est pas enregistré entraînera l'ignorance de la donnée. ```ts theme={null} import { KameleoonClient, CustomData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); const dataItemOne = 'abc'; const dataItemTwo = JSON.stringify(100); const dataItemThree = JSON.stringify({ a: 200, b: 300 }); const customDataIndex = 0; // -- Create custom data using single parameter const customData = new CustomData(customDataIndex, dataItemOne); // -- Create custom data using overwrite flag const customData = new CustomData(customDataIndex, false, dataItemOne); // -- Create custom data using name instead of index const customData = new CustomData('customDataName', dataItemOne); // -- Create custom data using variadic number of parameters const customData = new CustomData(customDataIndex, dataItemOne, dataItemTwo); // -- Create custom data using an array of values const dataList = [dataItemOne, dataItemTwo, dataItemThree]; const customData = new CustomData(customDataIndex, ...dataList); // -- Create custom data using overwrite flag const customData = new CustomData(customDataIndex, false, ...dataList); // -- Create custom data using name instead of index const customData = new CustomData('customDataName', false, ...dataList); // -- Add custom data client.addData('my_visitor_code', customData); } init(); ``` ```js theme={null} import { KameleoonClient, CustomData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); const dataItemOne = 'abc'; const dataItemTwo = JSON.stringify(100); const dataItemThree = JSON.stringify({ a: 200, b: 300 }); const customDataIndex = 0; // -- Create custom data using single parameter const customData = new CustomData(customDataIndex, dataItemOne); // -- Create custom data using overwrite flag const customData = new CustomData(customDataIndex, false, dataItemOne); // -- Create custom data using name instead of index const customData = new CustomData('customDataName', dataItemOne); // -- Create custom data using variadic number of parameters const customData = new CustomData(customDataIndex, dataItemOne, dataItemTwo); // -- Create custom data using an array of values const dataList = [dataItemOne, dataItemTwo, dataItemThree]; const customData = new CustomData(customDataIndex, ...dataList); // -- Create custom data using overwrite flag const customData = new CustomData(customDataIndex, false, ...dataList); // -- Create custom data using name instead of index const customData = new CustomData('customDataName', false, ...dataList); // -- Add custom data client.addData('my_visitor_code', customData); } init(); ``` *** #### Device Depuis le SDK JavaScript `4.10.0`, `Device` est automatiquement détecté à partir de la chaîne `User-Agent`. Cependant, vous pouvez toujours le remplacer manuellement si nécessaire. Device contient des informations sur votre appareil. Chaque visiteur ne peut avoir qu'un seul `Device`. Ajouter un second `Device` remplace le premier. | Name | Type | Description | | ----------------------- | ------------ | --------------------------------------------------------------------- | | deviceType (*required*) | `DeviceType` | types possibles pour le type de device (`PHONE`, `TABLET`, `DESKTOP`) | ```ts theme={null} import { KameleoonClient, DeviceType, Device } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Add device data const device = new Device(DeviceType.Desktop); client.addData('my_visitor_code', device); } init(); ``` ```js theme={null} import { KameleoonClient, DeviceType, Device } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Add device data const device = new Device(DeviceType.Desktop); client.addData('my_visitor_code', device); } init(); ``` *** #### OperatingSystem Depuis le SDK JavaScript `4.10.0`, `OperatingSystem` est automatiquement détecté à partir de la chaîne `User-Agent`. Cependant, vous pouvez toujours le remplacer manuellement si nécessaire. `OperatingSystem` contient des informations sur le système d'exploitation de l'appareil du visiteur. Chaque visiteur ne peut avoir qu'un seul `OperatingSystem`. Ajouter un second `OperatingSystem` remplace le premier. | Name | Type | Description | | ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------- | | operatingSystem (*required*) | `OperatingSystemType` | types possibles pour le type de device : `WINDOWS_PHONE`, `WINDOWS`, `ANDROID`, `LINUX`, `MAC`, et `IOS` | ```ts theme={null} import { KameleoonClient, OperatingSystem, OperatingSystemType, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Add operating system data const operatingSystem = new OperatingSystem(OperatingSystemType.Windows); client.addData('my_visitor_code', operatingSystem); } init(); ``` ```js theme={null} import { KameleoonClient, OperatingSystem, OperatingSystemType, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Add operating system data const operatingSystem = new OperatingSystem(OperatingSystemType.Windows); client.addData('my_visitor_code', operatingSystem); } init(); ``` #### PageView Depuis le SDK JavaScript `4.10.0`, `PageView` est automatiquement détecté à partir de `window.location?.href` et `document.title`. Cependant, vous pouvez toujours le remplacer manuellement si nécessaire. `PageView` contient des informations sur votre page web. Chaque visiteur peut avoir un `PageView` par URL unique. Ajouter un second `PageView` avec la même URL notifie le SDK que le visiteur a revisité la page. `PageViewParametersType` pageViewParameters - un objet avec les paramètres de page view décrits ci-dessous | Name | Type | Description | | ----------------------- | ---------- | ----------------------------------------------------------------------------------------------- | | urlAddress (*required*) | `string` | adresse url de la page à tracker. | | title (*required*) | `string` | titre de la page web. | | referrer (*optional*) | `number[]` | un paramètre optionnel contenant une liste d'indices de referrer, n'a pas de valeur par défaut. | Vous trouverez l'index ou l'ID du [referrer](/user-manual/assets/advanced-targeting-tools/create-an-acquisition-channel) dans votre compte Kameleoon. Notez que cet index commence à 0, ce qui signifie que le premier canal d'acquisition que vous créez pour un site donné aura 0 comme ID, et non 1. ```ts theme={null} import { KameleoonClient, PageViewParametersType, PageView, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Define page view parameters const pageViewParameters: PageViewParametersType = { urlAddress: 'www.example.com', title: 'my example', referrers: [123, 456], }; // -- Add page view data const pageView = new PageView(pageViewParameters); client.addData('my_visitor_code', pageView); } init(); ``` ```js theme={null} import { KameleoonClient, PageView } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Define page view parameters const pageViewParameters = { urlAddress: 'www.example.com', title: 'my example', referrers: [123, 456], }; // -- Add page view data const pageView = new PageView(pageViewParameters); client.addData('my_visitor_code', pageView); } init(); ``` *** #### UserAgent `UserAgent` vous permet de stocker des informations sur le user-agent du visiteur. Les expériences côté serveur sont plus susceptibles d'être affectées par le trafic des bots que les expériences côté client. Kameleoon utilise l'IAB/ABC International Spiders and Bots List pour résoudre ce problème et reconnaître les bots et spiders connus. Kameleoon utilise également le champ `UserAgent` pour filtrer les bots et autres trafics indésirables qui pourraient fausser vos métriques de conversion. Pour plus de détails, consultez notre article d'aide sur le [filtrage des bots](/user-manual/faq#how-does-kameleoon-filter-bot-traffic-from-my-results). Si vous utilisez des bots internes, nous vous suggérons de transmettre la valeur **curl/8.0** du userAgent pour les exclure de nos analytics. Un `Visitor` ne peut avoir qu'un seul `UserAgent`. Ajouter un second `UserAgent` remplace le premier. | Name | Type | Description | | ------------------ | -------- | ----------------------------------- | | value (*required*) | `string` | valeur utilisée pour la comparaison | Si vous exécutez Kameleoon en mode hybride, vos expériences de feature sont automatiquement protégées contre le trafic des bots. Cette protection se produit car Kameleoon collecte automatiquement le user-agent sur le front-end. Vous n'avez donc pas besoin de transmettre le user-agent ou tout autre paramètre pour filtrer les bots et spiders. Si vous utilisez des bots internes, nous vous suggérons de transmettre la valeur **curl/8.0** du userAgent pour les exclure de nos analytics. ```ts theme={null} import { KameleoonClient, UserAgent } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Add user agent data const userAgent = new UserAgent('my_unique_value'); client.addData('my_visitor_code', userAgent); } init(); ``` ```js theme={null} import { KameleoonClient, UserAgent } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Add user agent data const userAgent = new UserAgent('my_unique_value'); client.addData('my_visitor_code', userAgent); } init(); ``` #### ApplicationVersion `ApplicationVersion` représente le numéro de version sémantique de votre application. Un **visiteur** ne peut avoir qu'un seul `ApplicationVersion`. Ajouter une seconde instance remplacera la première. | Name | Type | Description | | -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | version (*optional*) | `string` | La version de l'application mobile. Ce champ doit respecter le versioning sémantique. Les formats acceptés sont `major`, `major.minor` ou `major.minor.patch`. | ```ts theme={null} import { KameleoonClient, ApplicationVersion } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Add application version const applicationVersion = new ApplicationVersion('1.2'); client.addData('my_visitor_code', applicationVersion); } init(); ``` ```js theme={null} import { KameleoonClient, ApplicationVersion } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Add application version const applicationVersion = new ApplicationVersion('1.2'); client.addData('my_visitor_code', applicationVersion); } init(); ``` *** ### Types retournés #### DataFile Le `DataFile` contient les détails de la configuration du SDK. Il peut être étendu avec des informations supplémentaires si les clients en ont besoin. Si vous avez besoin de plus de détails, veuillez contacter votre Customer Success Manager. | Name | Type | Description | | ------------ | -------------------------- | ------------------------------------------------------------------------------------- | | featureFlags | `Map` | Une map d'objets [`FeatureFlag`](#featureflag), indexée par les clés de feature flag. | | dateModified | `number` | Le timestamp (en millisecondes) indiquant la dernière modification du `DataFile`. | ```ts theme={null} import { FeatureFlag } from '@kameleoon/javascript-sdk'; // Retrieves the map of feature flags from the DataFile. // The map is keyed by feature flag identifiers, with each value being a FeatureFlag object. const featureFlags: Map = dataFile.featureFlags; // Retrieves the last modification timestamp of the DataFile. // The value is a number representing milliseconds since the Unix epoch. const dateModified: number = dataFile.dateModified; ``` ```js theme={null} // Retrieves the map of feature flags from the DataFile. // The map is keyed by feature flag identifiers, with each value being a FeatureFlag object. const featureFlags = dataFile.featureFlags; // Retrieves the last modification timestamp of the DataFile. // The value is a number representing milliseconds since the Unix epoch. const dateModified = dataFile.dateModified; ``` #### FeatureFlag Le `FeatureFlag` représente un ensemble de propriétés qui définissent un feature flag lui-même — par exemple, ses [`Variations`](#variation), [`Rules`](#rule), son état d'environnement et d'autres détails associés. Il peut être étendu avec des informations supplémentaires si les clients en ont besoin. Si vous avez besoin de plus de détails, veuillez contacter votre Customer Success Manager. | Name | Type | Description | | ------------------- | ------------------------ | ------------------------------------------------------------------ | | environmentEnabled | `boolean` | Indique si le feature flag est activé dans l'environnement actuel. | | defaultVariationKey | `string` | La clé de la variation par défaut associée au feature flag. | | variations | `Map` | Une map d'objets `Variation`, indexée par les variation keys. | | rules | `Rule[]` | Une liste d'objets `Rule` | ```ts theme={null} import { Variation, Rule } from '@kameleoon/javascript-sdk'; // Check whether the feature flag is enabled in the current environment const isEnvironmentEnabled: boolean = featureFlag.environmentEnabled; // Retrieve the key of the default variation const defaultVariationKey: string = featureFlag.defaultVariationKey; // Retrieve all variations of the feature flag as a map (key = variation key, value = Variation object) const variations: Map = featureFlag.variations; // Retrieve all targeting rules associated with the feature flag const rules: Rule[] = featureFlag.rules; ``` ```js theme={null} // Check whether the feature flag is enabled in the current environment const isEnvironmentEnabled = featureFlag.environmentEnabled; // Retrieve the key of the default variation const defaultVariationKey = featureFlag.defaultVariationKey; // Retrieve all variations of the feature flag as a map (key = variation key, value = Variation object) const variations = featureFlag.variations; // Retrieve all targeting rules associated with the feature flag const rules = featureFlag.rules; ``` #### Rule La `Rule` représente un ensemble de propriétés qui définissent une règle elle-même — par exemple, ses [`Variations`](#variation). Il peut être étendu avec des informations supplémentaires si les clients en ont besoin. Si vous avez besoin de plus de détails, veuillez contacter votre Customer Success Manager. | Name | Type | Description | | ---------- | ------------------------ | ------------------------------------------------------------- | | variations | `Map` | Une map d'objets `Variation`, indexée par les variation keys. | ```ts theme={null} import { Variation } from '@kameleoon/javascript-sdk'; // Retrieve all variations of the rule as a map (key = variation key, value = Variation object) const variations: Map = rule.variations; ``` ```js theme={null} // Retrieve all variations of the rule as a map (key = variation key, value = Variation object) const variations = rule.variations; ``` #### Variation `Variation` contient des informations sur la variation attribuée au visiteur (ou sur la variation par défaut, si aucune attribution spécifique n'existe). | Name | Type | Description | | ------------ | ----------------------- | ----------------------------------------------------------------------------------------------------- | | name | `string` | nom de la variation. | | key | `string` | clé de la variation. | | id | `number` or `null` | id de la variation ou `null` si le visiteur a atterri sur la variation par défaut. | | experimentId | `number` or `null` | id de l'expérience ou `null` si le visiteur a atterri sur la variation par défaut. | | variables | `Map` | map des variables pour la variation, où la clé est la variable key et la valeur est l'objet variable. | * Assurez-vous que votre code gère le cas où `id` ou `experimentId` vaut `null`, indiquant une variation par défaut. * La map `variables` peut être vide si aucune variable n'est associée à la variation. ```ts theme={null} // Retrieving the variation name const variationName = variation.name; // Retrieving the variation key const variationKey = variation.key; // Retrieving the variation id const variationId = variation.id; // Retrieving the experiment id const experimentId = variation.experimentId; // Retrieving the variables map const variables = variation.variables; ``` ```js theme={null} // Retrieving the variation name const variationName = variation.name; // Retrieving the variation key const variationKey = variation.key; // Retrieving the variation id const variationId = variation.id; // Retrieving the experiment id const experimentId = variation.experimentId; // Retrieving the variables map const variables = variation.variables; ``` #### Variable `Variable` contient des informations sur une variable associée à la variation attribuée. | Name | Type | Description | | ----- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | key | `string` | La clé unique identifiant la variable. | | type | `string` | Le type de la variable. Valeurs possibles : **BOOLEAN**, **NUMBER**, **STRING**, **JSON**, **JS**, **CSS**. | | value | `any` | La valeur de la variable, qui peut être des types suivants : **boolean**, **number**, **String**, **Record\**, **any\[]**. | ```ts theme={null} // Retrieving the variables map const variables = variation.variables; // Variable type can be retrieved for further processing const type = variables.get('isDiscount')?.type || ''; // Retrieving the variable value by key const isDiscount = variables.get('isDiscount')?.value || false; // Variable value can be of different types const title = variables.get('title')?.value || ''; ``` ```js theme={null} // Retrieving the variables map const variables = variation.variables; // Variable type can be retrieved for further processing const type = variables.get('isDiscount')?.type || ''; // Retrieving the variable value by key const isDiscount = variables.get('isDiscount')?.value || false; // Variable value can be of different types const title = variables.get('title')?.value || ''; ``` ### Méthodes obsolètes Ces méthodes sont obsolètes et seront supprimées lors de la prochaine mise à jour majeure. #### getFeatureFlagVariationKey() * 📨 *Envoie des données de tracking à Kameleoon* * 🎯 *Événements :* [`EventType.Evaluation`](#events-1) Utilisez plutôt la méthode [`getVariation`](#getvariation) La méthode `getFeatureFlagVariationKey()` récupère la variation key pour un visiteur identifié par un `visitorCode`. Cette méthode inclut une vérification de ciblage qui identifie la variation appropriée exposée au visiteur, l'enregistre dans le stockage et envoie une requête de tracking. Lorsqu'un utilisateur n'est pas associé à un feature flag, le SDK renvoie aléatoirement une variation key selon les règles du feature flag. Si l'utilisateur a déjà été enregistré avec le feature flag, le SDK détectera cette association et renverra la valeur de variation key précédente de l'utilisateur. Cependant, si l'utilisateur ne satisfait aucune des règles définies, le SDK renverra la valeur par défaut spécifiée dans les règles de livraison du feature flag de Kameleoon. Il est important de noter que la valeur par défaut peut être une variation key, une valeur booléenne ou un autre type de données, selon la configuration du feature flag. ```ts theme={null} import { KameleoonClient, CustomData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Add CustomData with index `0` containing visitor id to check the targeting client.addData(new CustomData(0, 'visitor_id')); // -- Get visitor feature flag variation key const variationKey = client.getFeatureFlagVariationKey( visitorCode, 'my_feature_key', ); } init(); ``` ```js theme={null} import { KameleoonClient, CustomData } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Add CustomData with index `0` containing visitor id to check the targeting client.addData(new CustomData(0, 'visitor_id')); // -- Get visitor feature flag variation key const variationKey = client.getFeatureFlagVariationKey( visitorCode, 'my_feature_key', ); } init(); ``` ##### Arguments | Name | Type | Description | | ------------------------ | -------- | ------------------------------------------------------------------------ | | visitorCode (*required*) | `string` | unique visitor identification string, can't exceed 255 characters length | | featureKey (*required*) | `string` | une clé unique pour le feature flag | ##### Valeur de retour | Type | Description | | -------- | ------------------------------------------------------------------------------------------------------ | | `string` | une chaîne contenant la variable key pour la variation de feature flag allouée pour le visiteur fourni | ##### Exceptions levées | Type | Description | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `KameleoonException.Initialization` | La méthode a été exécutée avant que `initialize` n'ait été effectué pour `kameleoonClient`. | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale. | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.FeatureFlagConfigurationNotFound` | Aucun feature flag n'a été trouvé pour la `featureKey` fournie. | | `KameleoonException.FeatureFlagEnvironmentDisabled` | Le feature flag est désactivé pour l'environnement actuel. | #### getVisitorFeatureFlags() * 🚫 *N'envoie pas de données de tracking à Kameleoon* * 🎯 *Événements :* [`EventType.Evaluation`](#events-1) (for each feature flag) Utilisez plutôt la méthode [`getVariations`](#getvariations). La méthode `getVisitorFeatureFlags()` renvoie une liste de feature flags qui ciblent un visiteur identifié par son `visitorCode` ainsi que les feature flags actifs pour le visiteur spécifié. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get active feature flags for visitor const featureFlags = client.getVisitorFeatureFlags(visitorCode); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get active feature flags for visitor const featureFlags = client.getVisitorFeatureFlags(visitorCode); } init(); ``` Cette méthode ne collecte que les feature flags *actifs* du visiteur, ce qui signifie que le résultat exclut tous les feature flags pour lesquels le visiteur est attribué à la variation `off` (par défaut ou de contrôle). Lorsque vous avez besoin de tous les feature flags du visiteur, utilisez plutôt `getFeatureFlags`. Par exemple : ```ts theme={null} // -- `getVisitorFeatureFlags` doesn't trigger feature experiments; // it only returns feature flags where visitor didn't get the `off` variation client.getVisitorFeatureFlags('my_visitor').forEach(({ key }) => { // -- `getFeatureFlagVariationKey` triggers feature experiments, // as `off` is already filtered out - you won't see a // visitor taking part in experiment where the `off` variation was allocated. client.getFeatureFlagVariationKey('my_visitor', key); }); ``` Pour les cas où vous avez besoin de tous les feature flags du visiteur, utilisez plutôt [`getFeatureFlags`](#getfeatureflags) : ```ts theme={null} // -- Both `off` and other variations are processed as expected client.getFeatureFlags('my_visitor').forEach(({ key }) => { client.getFeatureFlagVariationKey('my_visitor', key); }); ``` ##### Arguments | Name | Type | Description | | ------------------------ | -------- | ------------------------------------------------------------------------------- | | visitorCode (*required*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères | ##### Valeur de retour | Type | Description | | ------------------- | ------------------------------------------------------------------- | | `FeatureFlagType[]` | liste des feature flags. Chaque feature flag contient `id` et `key` | ##### Exceptions levées | Type | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------------------ | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à `initialize`. | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.StorageRead` | Erreur lors de la lecture des données du stockage. | *** #### getActiveFeatureFlags() * 🚫 *N'envoie pas de données de tracking à Kameleoon* * 🎯 *Événements :* [`EventType.Evaluation`](#events-1) (for each feature flag) Utilisez plutôt la méthode [`getVariations`](#getvariations). La méthode `getActiveFeatureFlags()` renvoie une `Map`, où la clé est featurekey et la valeur est une information détaillée sur la variation du visiteur et ses variables ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get active feature flags for visitor // with detailed variation and variables data const activeFeatures = client.getActiveFeatureFlags(visitorCode); // -- Result example: // Map { // 'feature-key-one' => { // id: 100, // key: 'variation-key-one', // experimentId: 200, // variables: [ // { key: 'variable_bool', type: VariableType.Boolean, value: true }, // ] // }, // 'feature-key-two' => { // id: null, // -> `null` because it is default variation // key: 'default-variation-key', // experimentId: null, // -> `null` because it is default variation // variables: [] // } // } } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get active feature flags for visitor // with detailed variation and variables data const activeFeatures = client.getActiveFeatureFlags(visitorCode); // -- Result example: // Map { // 'feature-key-one' => { // id: 100, // key: 'variation-key-one', // experimentId: 200, // variables: [ // { key: 'variable_bool', type: VariableType.Boolean, value: true }, // ] // }, // 'feature-key-two' => { // id: null, // -> `null` because it is default variation // key: 'default-variation-key', // experimentId: null, // -> `null` because it is default variation // variables: [] // } // } } init(); ``` Cette méthode ne collecte que les feature flags *actifs* du visiteur. Cela signifie que le résultat exclut tous les feature flags pour lesquels le visiteur est attribué à la variation `off` (par défaut ou de contrôle). Lorsque vous avez besoin d'itérer sur tous les feature flags du visiteur, utilisez plutôt `getFeatureFlags`. Consultez la section *CAUTION* de la méthode [getVisitorFeatureFlags](#getvisitorfeatureflags) pour plus de détails. ##### Arguments | Name | Type | Description | | ------------------------ | -------- | ------------------------------------------------------------------------ | | visitorCode (*required*) | `string` | unique visitor identification string, can't exceed 255 characters length | ##### Valeur de retour | Type | Description | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `Map` | une map des feature flags, où `key` est `featureKey` et `value` contient des informations détaillées sur la variation du visiteur et ses variables. | ##### Exceptions levées | Type | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------------------ | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à `initialize`. | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.StorageRead` | Erreur lors de la lecture des données du stockage. | | `KameleoonException.NumberParse` | Impossible de parser la valeur Number. | | `KameleoonException.JSONParse` | Impossible de parser la valeur JSON. | #### getFeatureFlagVariable() * 📨 *Envoie des données de tracking à Kameleoon* * 🎯 *Événements :* [`EventType.Evaluation`](#events-1) Utilisez la méthode [`getVariation`](#getvariation). La méthode `getFeatureFlagVariable()` renvoie une variable pour un visiteur identifié par un `visitorCode`. Cette méthode inclut une vérification de ciblage qui identifie la variation appropriée exposée au visiteur, l'enregistre dans le stockage et envoie une requête de tracking. ```ts theme={null} import { KameleoonClient, VariableType, JSONType, } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get feature variable const result = client.getFeatureFlagVariable({ visitorCode, featureKey: 'my_feature_key' variableKey: 'my_variable_key' }); // -- Infer the type of variable by its `type` switch (result.type) { case VariableType.BOOLEAN: const myBool: boolean = result.value; break; case VariableType.NUMBER: const myNum: number = result.value; break; case VariableType.JSON: const myJson: JSONType = result.value; break; case VariableType.STRING: case VariableType.JS: case VariableType.CSS: const myStr: string = result.value; break; default: break; } } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get feature variable const variableResult = client.getFeatureFlagVariable({ visitorCode, featureKey: 'my_feature_key' variableKey: 'my_variable_key' }); const { type, value } = variableResult; } init(); ``` ##### Arguments Objet de paramètres de type `GetFeatureFlagVariableParamsType` contenant les champs suivants : | Name | Type | Description | | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | visitorCode (*required*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères. | | featureKey (*required*) | `string` | une clé unique pour le feature flag. | | variableKey (*required*) | `string` | clé de la variable à trouver pour un feature flag avec la `featureKey` fournie. Peut être trouvée dans la plateforme Kameleoon | ##### Valeur de retour | Type | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FeatureFlagVariableType` | un objet variable contenant les champs `type` et `value`. Vous pouvez vérifier le champ `type` par rapport à l'enum `VariableType`. Par exemple, si `type` vaut `VariableType.BOOLEAN`, alors `value` sera de type `boolean`. | ##### Exceptions levées | Type | Description | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à `initialize`. | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.FeatureFlagConfigurationNotFound` | Aucun feature flag n'a été trouvé pour la `featureKey` fournie. | | `KameleoonException.FeatureFlagVariableNotFound` | Aucune feature variable n'a été trouvée pour les `visitorCode` et `variableKey` fournis. | | `KameleoonException.FeatureFlagEnvironmentDisabled` | Le feature flag est désactivé pour l'environnement actuel. | | `KameleoonException.JSONParse` | Impossible de parser la valeur JSON. | | `KameleoonException.NumberParse` | Impossible de parser la valeur Number. | #### getFeatureFlagVariables() * 📨 *Envoie des données de tracking à Kameleoon* * 🎯 *Événements :* [`EventType.Evaluation`](#events-1) (for each feature flag) Utilisez la méthode [`getVariation`](#getvariation). La méthode `getFeatureFlagVariables()` renvoie une variable pour un visiteur identifié par un `visitorCode`. Cette méthode inclut une vérification de ciblage qui identifie la variation appropriée exposée au visiteur, l'enregistre dans le stockage et envoie une requête de tracking. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init(): Promise { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get a list of variables for the visitor under `visitorCode` in the feature flag const variables = client.getFeatureFlagVariables( visitorCode, 'my_feature_key', ); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code', configuration: { cookieDomain: '.example.com' }, }); async function init() { await client.initialize(); // -- Get visitor code const visitorCode = client.getVisitorCode(); // -- Get a list of variables for the visitor under `visitorCode` in the feature flag const variables = client.getFeatureFlagVariables( visitorCode, 'my_feature_key', ); } init(); ``` ##### Arguments | Name | Type | Description | | ------------------------ | -------- | -------------------------------------------------------------------------------- | | visitorCode (*required*) | `string` | chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères. | | featureKey (*required*) | `string` | une clé unique pour le feature flag. | ##### Valeur de retour | Type | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FeatureVariableResultType[]` | une liste d'objets variable contenant les champs `key`, `type` et `value`. Vous pouvez vérifier le champ `type` par rapport à l'enum `VariableType`. Par exemple, si `type` vaut `VariableType.BOOLEAN`, alors `value` sera de type `boolean`. | ##### Exceptions levées | Type | Description | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à `initialize`. | | `KameleoonException.VisitorCodeMaxLength` | Le visitor code a dépassé la longueur maximale (255 caractères). | | `KameleoonException.VisitorCodeEmpty` | Le visitor code est vide. | | `KameleoonException.FeatureFlagConfigurationNotFound` | Aucun feature flag n'a été trouvé pour la `featureKey` fournie. | | `KameleoonException.FeatureFlagVariationNotFound` | Aucune feature variation n'a été trouvée pour les `visitorCode` et `variationKey` fournis. | | `KameleoonException.FeatureFlagEnvironmentDisabled` | Le feature flag est désactivé pour l'environnement actuel. | | `KameleoonException.JSONParse` | Impossible de parser la valeur JSON. | | `KameleoonException.NumberParse` | Impossible de parser la valeur Number. | #### onConfigurationUpdate() Utilisez plutôt la méthode `onEvent` avec `EventType.ConfigurationUpdate`. La méthode `onConfigurationUpdate()` déclenche un callback lors de la mise à jour de la configuration du client. Cette méthode ne s'applique qu'aux server-sent events utilisés dans les mises à jour en temps réel. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Define logic to be executed on client configuration update client.onConfigurationUpdate(() => { // -- My Logic }); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Define logic to be executed on client configuration update client.onConfigurationUpdate(() => { // -- My Logic }); } init(); ``` ##### Arguments | Name | Type | Description | | --------------------- | ------------ | ---------------------------------------------------------------------------------------------- | | callback (*required*) | `() => void` | fonction callback sans paramètres qui sera appelée lors de la mise à jour de la configuration. | ##### Exceptions levées | Type | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------ | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à `initialize`. | *** #### getFeatureFlags() Utilisez plutôt la méthode [`getDataFile()`](#getdatafile). 🚫 *N'envoie pas de données de tracking à Kameleoon* La méthode `getFeatureFlags()` renvoie une liste des feature flags stockés dans la configuration du client. ```ts theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init(): Promise { await client.initialize(); // -- Get all feature flags const featureFlags = client.getFeatureFlags(); } init(); ``` ```js theme={null} import { KameleoonClient } from '@kameleoon/javascript-sdk'; const client = new KameleoonClient({ siteCode: 'my_site_code' }); async function init() { await client.initialize(); // -- Get all feature flags const featureFlags = client.getFeatureFlags(); } init(); ``` ##### Valeur de retour | Type | Description | | ------------------- | ----------------------------------------------------------------------- | | `FeatureFlagType[]` | liste des feature flags. Chaque feature flag contient un `id` et `key`. | ##### Exceptions levées | Type | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------ | | `KameleoonException.Initialization` | La méthode a été exécutée avant que le `kameleoonClient` n'ait terminé son appel à `initialize`. |