> ## 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.
# Flutter SDK
> Intégrez le SDK Flutter de Kameleoon pour exécuter des expériences et activer des feature flags sur toutes les plateformes ciblées par le framework Flutter.
Avec le SDK Flutter de Kameleoon, les expériences peuvent s'exécuter et les feature flags peuvent s'activer sur toutes les plateformes ciblées par le framework applicatif Flutter. L'intégration du SDK dans les applications est facile, et son empreinte (en termes de mémoire et d'utilisation réseau) est faible.
**Pour commencer** : pour obtenir de l'aide afin de démarrer, consultez le [guide du développeur](#guide-du-développeur).
**Changelog** : dernière version du SDK Flutter : 3.7.0 [Changelog](https://github.com/Kameleoon/client-flutter/blob/master/CHANGELOG.md).
**Méthodes du SDK** : pour la documentation complète de référence des méthodes du SDK Flutter, consultez la section [référence](#référence).
## Guide du développeur
### Pour commencer
Ce guide aide à intégrer le SDK et à commencer à exécuter des expériences dans des applications Flutter. Ce tutoriel explique la configuration d'un simple A/B test pour modifier le nombre de produits recommandés en fonction de différentes variations.
#### Installer le client Flutter
Pour installer le client Flutter de Kameleoon, déclarez une dépendance dans votre fichier `pubspec.yaml` :
```ruby theme={null}
kameleoon_client_flutter: ^3.0.0
```
En mode **release**, la bibliothèque JS se charge automatiquement. Cependant, en mode **debug**, des problèmes (dus au Dart Development Compiler) peuvent survenir lors de l'importation de la bibliothèque JS. Pour éviter d'éventuels problèmes, il est fortement recommandé d'importer explicitement la bibliothèque JS.
Ajoutez la ligne de script suivante à la section `` de votre `index.html` :
```html theme={null}
```
#### Initialiser le client Kameleoon
Après avoir installé le SDK dans votre application et configuré une expérience côté serveur dans l'application Kameleoon, l'étape suivante consiste à créer le client Kameleoon.
Un `KameleoonClient` est un objet singleton (par `siteCode`) qui agit comme un pont entre votre application et la plateforme Kameleoon. Il inclut toutes les méthodes et propriétés dont vous avez besoin pour exécuter une expérience.
```dart theme={null}
import 'package:kameleoon_client_flutter/kameleoon_client_flutter.dart';
class _HomePage extends State {
KameleoonClient kameleoonClient
@override
void initState() {
super.initState();
try {
// pass client configuration and visitorCode as arguments
final config = KameleoonClientConfig(
refreshIntervalMinutes: 15, // 60 minutes by default, optional
defaultTimeoutMilliseconds: 10000, // 10_000 milliseconds by default, optional
dataExpirationIntervalMinutes: 1440 * 365, // infinity by default, optional
trackingIntervalMilliseconds: 500, // 1000 milliseconds by default, optional
environment: "staging", // optional
isUniqueIdentifier: false, // false by default, optional
domain: "example.com", // web only option, optional
networkDomain: "company.com", // web only option, optional
defaultDataFile: "{...}" // optional
);
final visitorCode = "yourVisitorCode";
final kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode: visitorCode, config: config);
// or, if you want, visitor code will be generated automatically
final kameleoonClient = KameleoonClientFactory.create(siteCode, config: config);
} on SiteCodeIsEmpty catch (ex) {
// Exception indicates that the provided siteCode is empty
} on VisitorCodeInvalid catch (ex) {
// Exception indicates that the provided visitorCode is invalid
} on Exception catch (ex) {
// Any other error
}
}
}
```
Lors de son exécution, la méthode `KameleoonClientFactory.create()` initialise le client, mais celui-ci n'est pas immédiatement prêt à l'emploi, car le client Kameleoon doit récupérer la configuration actuelle des feature flags (avec leur répartition de trafic) auprès d'un serveur distant Kameleoon. Cette récupération nécessite un accès réseau, qui n'est pas toujours disponible. Tant que le client Kameleoon n'est pas entièrement prêt, vous ne devez pas tenter d'exécuter d'autres méthodes du SDK Android de Kameleoon. Notez qu'une fois la première configuration des feature flags récupérée, elle est ensuite rafraîchie périodiquement, mais même si le rafraîchissement échoue pour une raison quelconque, le client Kameleoon continuera de fonctionner en utilisant la configuration précédente.
Vous pouvez utiliser la méthode [`isReadyAsync()`](#isreadyasync) pour vérifier si l'initialisation du client Kameleoon est terminée.
Alternativement, un **callback d'aide** peut encapsuler la logique du déclenchement de feature flag et de l'implémentation de la variation. La meilleure approche ([`isReadyAsync()`](#isreadyasync) ou **callback**) dépend des préférences et du cas d'usage exact. Utilisez [`isReadyAsync()`](#isreadyasync) lorsque le SDK est censé être prêt à l'emploi rapidement. Par exemple, `isReadyAsync()` est approprié lors de l'exécution d'un feature flag sur une boîte de dialogue à laquelle les utilisateurs n'accéderont probablement pas durant les premières secondes ou minutes de navigation dans l'application. Un callback est recommandé lorsqu'il existe une forte probabilité que le SDK soit encore en cours d'initialisation. Par exemple, un feature flag qui apparaît à l'écran au lancement de l'application doit utiliser un callback qui fait attendre l'application jusqu'à ce que le SDK soit prêt ou qu'un délai spécifié soit écoulé.
Il est de votre responsabilité, en tant que développeur de l'application, de vous assurer que la logique de votre code applicatif est correcte dans le contexte de l'A/B testing avec Kameleoon. Une bonne pratique est de toujours supposer que l'utilisateur de l'application peut être exclu du feature flag lorsque le client Kameleoon n'est pas encore prêt. Cette exclusion est facile à mettre en œuvre, car elle correspond à l'implémentation de la logique de la variation par défaut ou de référence. Les exemples de code du paragraphe suivant montrent des exemples de cette approche.
Vous êtes maintenant prêt à implémenter la gestion des fonctionnalités et des feature flags. Consultez la section [Référence](#référence) pour plus de détails sur les méthodes supplémentaires.
#### Activer un feature flag
##### Récupérer la configuration d'un flag
Pour implémenter un feature flag dans votre code, vous devez d'abord créer un [feature flag](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag) dans votre compte Kameleoon.
Pour déterminer si un feature flag est actif pour un utilisateur spécifique, vous devez récupérer sa configuration. Utilisez la méthode [`getFeatureVariationKey()`](#getfeaturevariationkey) ou [`isFeatureActive()`](#isfeatureactive) pour récupérer la configuration en fonction du `featureKey`.
Utilisez la méthode `isFeatureActive()` si vous souhaitez récupérer la configuration d'un feature flag simple qui n'a qu'un état ON ou OFF, par opposition à des feature flags plus complexes avec plusieurs variations ou options de ciblage.
La méthode `getFeatureVariationKey()` récupère la configuration d'une expérience de fonctionnalité avec plusieurs variations. Vous pouvez utiliser la méthode pour obtenir une clé de variation pour un utilisateur donné en fournissant le `visitorCode` et le `featureKey` comme arguments obligatoires.
Les feature flags peuvent avoir des variables associées qui sont utilisées pour personnaliser leur comportement. Pour récupérer ces variables, utilisez la méthode [`getFeatureVariationVariables()`](#getfeaturevariationvariables) après avoir appelé `getFeatureVariationKey()`, car vous devez obtenir la `variationKey` pour l'utilisateur.
Pour vérifier si un feature flag est actif, il vous suffit d'utiliser **une** méthode. Choisissez `isFeatureFlagActive` si vous voulez savoir si un feature flag est activé ou désactivé. Pour des scénarios plus complexes, comme la modification dynamique du comportement de la fonctionnalité, utilisez `getFeatureFlagVariables`.
##### Ajouter des points de données pour cibler un utilisateur ou filtrer / décomposer les visites dans les rapports
Pour cibler un utilisateur, assurez-vous d'avoir ajouté les points de données pertinents à son profil avant de récupérer la variation de la fonctionnalité ou de vérifier si le flag est actif. Utilisez la méthode [`addData()`](#adddata) pour ajouter ces points de données au profil de l'utilisateur.
Pour récupérer des points de données collectés sur d'autres appareils ou pour accéder aux données utilisateur passées (collectées côté client lors de l'utilisation de 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. Appelez `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 assigner un utilisateur à une variation donnée d'un feature flag.
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 points de données que vous ajoutez au profil du visiteur seront disponibles lors de l'analyse de vos expériences, vous permettant de filtrer et de décomposer vos résultats par facteurs comme l'appareil et le navigateur. N'oubliez pas d'appeler la méthode `flush()` pour envoyer les données sauvegardées aux serveurs Kameleoon.
Si vous avez besoin de suivre des points de données supplémentaires au-delà de ce qui est collecté automatiquement, vous pouvez utiliser la [fonctionnalité Custom Data](#customdata) de Kameleoon. 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()` pour envoyer les données collectées aux serveurs Kameleoon pour analyse.
##### Suivre l'exposition aux flags et les conversions d'objectifs
Kameleoon suivra automatiquement l'exposition des visiteurs aux flags dès que vous appelez l'une de ces méthodes :
* `getFeatureVariationKey()`
* `getFeatureVariable()`
* `isFeatureActive()`
Lorsqu'un utilisateur effectue une action souhaitée (par exemple, un achat), cela compte comme une conversion. Pour suivre les conversions, vous devez utiliser la méthode [`trackConversion()`](#trackconversion) et fournir les paramètres `visitorCode` et `goalId`.
### Utilisation d'une clé de bucketing personnalisée
Par défaut, Kameleoon utilise un ID de visiteur anonyme et unique (`visitorCode`) pour assigner 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 **Custom Bucketing Key** vous permet de remplacer ce comportement par défaut en fournissant votre propre identifiant personnalisé pour le bucketing. Ce remplacement garantit que la logique d'assignation de Kameleoon utilise votre clé spécifiée au lieu 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 assignations de feature flag, en particulier dans ces situations :
* **Expériences au niveau du compte ou de l'organisation :** pour les produits B2B ou les scénarios où vous souhaitez assigner tous les utilisateurs de la même organisation à la même variation, vous pouvez utiliser un identifiant comme un `accountId`. Les clés de bucketing personnalisées sont cruciales pour les A/B tests de fonctionnalités qui impactent une équipe ou une entreprise entière.
En implémentant une clé de bucketing personnalisée, vous garantissez une plus grande cohérence et exactitude dans vos expériences, conduisant à des résultats plus fiables et une meilleure expérience utilisateur.
#### Détails techniques
Lorsque vous configurez une clé de bucketing personnalisée pour un feature flag, vous fournissez à Kameleoon un identifiant spécifique provenant des données de votre application :
```dart theme={null}
try {
await kameleoonClient.addData(CustomData.withIndex(index, values: ["newVisitorCode"]))
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
* **Fournir la clé personnalisée :** vous fournissez votre identifiant personnalisé au SDK Kameleoon en utilisant la méthode [`addData()`](#adddata). Dans cette méthode, vous passerez votre clé de bucketing personnalisée choisie en tant qu'objet [`CustomData`](#customdata). Ici, `newVisitorCode` fait référence à l'identifiant que vous souhaitez utiliser pour votre bucketing (par exemple, le nouveau `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 configuration dans Kameleoon, consultez cet [article](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag#Advanced_Flag_Settings).
* **Logique de bucketing :** une fois qu'une clé de bucketing personnalisée est fournie via la méthode `addData()`, tous les calculs de hachage pour l'assignation des utilisateurs aux variations utiliseront ce `newVisitorCode` (votre clé personnalisée) au lieu du `visitorCode` par défaut. L'utilisation du `newVisitorCode` signifie que la décision de bucketing est liée à votre identifiant personnalisé, garantissant des assignations cohérentes dans divers contextes où cet identifiant est présent.
* **Suivi des données et analyse :** il est crucial de noter que tandis que le `newVisitorCode` (votre clé personnalisée) est 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 vos analyses reflètent avec précision les parcours utilisateur individuels et les interactions dans le contexte plus large de votre expérience, même lorsque le bucketing est effectué à un niveau supérieur (comme un compte) ou sur plusieurs appareils/sessions. Vos données de visiteur originales restent intactes pour des rapports complets.
#### Exigences techniques
Pour utiliser efficacement une clé de bucketing personnalisée :
* La clé doit être une `String`.
* Elle doit être unique pour l'entité que vous souhaitez 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 de feature flag est évaluée pour cet utilisateur ou cette requête.
### Conditions de ciblage
Les SDK Kameleoon prennent en charge une variété de conditions de ciblage prédéfinies que vous pouvez utiliser pour cibler les utilisateurs dans vos campagnes. Pour la liste des conditions supportées 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/apis/data-api-rest/tutorials/storing-and-retrieving-external-data-to-target-users).
### Journalisation
Le SDK génère des journaux pour refléter divers processus internes et problèmes.
#### Niveaux de journalisation
Le SDK prend en charge la configuration de la limitation de la journalisation par niveau de journalisation.
```dart theme={null}
// The `none` log level does not allow logging.
KameleoonLogger.setLogLevel(LogLevel.none);
// The `error` log level only allows logging issues that may affect the SDK's main behaviour.
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.
KameleoonLogger.setLogLevel(LogLevel.warning);
// The `info` log level allows logging general information on the SDK's internal processes.
// It extends the `warning` log level.
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 support
// to assist with internal troubleshooting.
KameleoonLogger.setLogLevel(LogLevel.debug);
```
#### Gestion personnalisée des journaux
Le SDK écrit ses journaux dans la sortie de la console par défaut. Ce comportement peut être remplacé.
La limitation de la journalisation par niveau est effectuée séparément de la logique de gestion des journaux.
```dart theme={null}
import 'package:logging/logging.dart' as logging;
class CustomLogger extends Logger {
final logger = logging.Logger("CustomLogger");
// `log` method accepts logs from the SDK
@override
void log(LogLevel level, String message) {
// Custom log handling logic here. For example:
switch (level) {
case LogLevel.error:
logger.severe(message);
break;
case LogLevel.warning:
logger.warning(message);
break;
case LogLevel.info:
logger.info(message);
break;
case LogLevel.debug:
logger.fine(message);
break;
default:
break;
}
}
}
// Log level filtering is applied separately from log handling logic.
// The custom logger will only accept logs that meet or exceed the specified log level.
// Ensure the log level is set correctly.
KameleoonLogger.setLogLevel(LogLevel.debug); // Optional, defaults to `LogLevel.warning`.
KameleoonLogger.setLogger(CustomLogger());
```
### Gestion des erreurs
La gestion des erreurs est considérée comme une bonne pratique pour rendre votre application plus stable et éviter les problèmes techniques. La plupart des méthodes `KameleoonClient` peuvent lever une erreur `KameleoonException`.
Comme il peut être difficile de patcher la version du SDK côté client Android, il est recommandé d'encadrer chaque méthode du SDK dans une clause `try` qui intercepte les types d'erreurs `KameleoonException` et `Throwable` afin d'éviter d'autres erreurs fatales.
Par exemple :
```dart theme={null}
try {
// Calling a method of the SDK
} on KameleoonException {
// Handling expected exceptions
} on Exception {
// Any other error
}
```
## Référence
Voici la documentation de référence complète du SDK Flutter.
### Initialisation
Une fois que vous avez [installé le SDK](#installer-le-client-flutter) dans votre application, vous devez initialiser Kameleoon. Toutes les interactions de votre application avec le SDK, telles que le déclenchement d'une expérience, sont accomplies en utilisant cet objet client Kameleoon.
#### create()
Appelez cette méthode avant toute autre pour initialiser le SDK. Cette méthode se trouve dans `KameleoonClientFactory`. Votre application effectue toutes les interactions avec le SDK en utilisant l'objet `KameleoonClient` résultant que cette méthode crée.
Vous pouvez personnaliser le comportement du SDK (par exemple, l'environnement, les identifiants, etc.) en fournissant un [objet de configuration](#additional-configuration). Sinon, le SDK tente de trouver votre fichier de configuration et l'utilise à la place.
```dart theme={null}
import 'package:kameleoon_client_flutter/kameleoon_client_flutter.dart'
final siteCode = "a8st4f59bj";
try {
// pass client configuration and visitorCode as arguments
final config = KameleoonClientConfig(
refreshIntervalMinutes: 15, // 60 minutes by default, optional
defaultTimeoutMilliseconds: 10000, // 10_000 milliseconds by default, optional
dataExpirationIntervalMinutes: 1440 * 365, // infinity by default, optional
trackingIntervalMilliseconds: 500, // 1000 milliseconds by default, optional
environment: "staging", // optional
isUniqueIdentifier: false, // false by default, optional
domain: "example.com" // web only option, optional
networkDomain: "company.com", // web only option, optional
defaultDataFile: "{...}" // optional
);
final visitorCode = "yourVisitorCode";
final kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode: visitorCode, config: config);
} on SiteCodeIsEmpty catch (ex) {
// Exception indicates that the provided siteCode is empty
} on VisitorCodeInvalid catch (ex) {
// Exception indicates that the provided visitorCode is invalid
} on Exception catch (ex) {
// Any other error
}
try {
// generate visitorCode automatically and use default Kameleoon client config
final kameleoonClient = KameleoonClientFactory.create(siteCode);
} on SiteCodeIsEmpty catch (ex) {
// Exception indicates that the provided siteCode is empty
} on Exception catch (ex) {
// Any other error
}
```
##### Arguments
| Name | Type | Description | Default |
| ------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| siteCode (*required*) | `String` | Une [clé unique](/user-manual/faq#how-do-i-find-my-sitecode) identifiant le projet Kameleoon utilisé avec le SDK. | |
| visitorCode (*optional*) | `String` | Un identifiant de visiteur optionnel. S'il est disponible, utilisez votre **ID utilisateur** interne ; sinon, le SDK en générera un automatiquement. | `nil` |
| config (*optional*) | `KameleoonClientConfig` | Si la configuration du SDK n'est pas fournie, le SDK utilisera automatiquement les paramètres par défaut. | `nil` |
##### Valeur de retour
| Type | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `KameleoonClient` | Une instance de la classe `KameleoonClient` que votre application peut ensuite utiliser pour gérer vos expériences et feature flags. |
##### Exceptions levées
| Type | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Exception indiquant que le code visiteur fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
| `SiteCodeIsEmpty` | Exception indiquant que le site code spécifié est une chaîne vide, ce qui n'est pas une valeur valide. |
#### isReadyAsync()
Pour les SDK mobiles, le client Kameleoon ne peut pas s'initialiser immédiatement car il doit effectuer un appel serveur pour récupérer la configuration actuelle des feature flags actifs. Utilisez `isReadyAsync()` pour vérifier si le SDK est prêt en appelant cette méthode avant de déclencher tout feature flag.
Alternativement, vous pouvez utiliser un callback (voir la méthode [`runWhenReady()`](#runwhenready) pour plus de détails).
```dart theme={null}
final ready = kameleoonClient.isReadyAsync();
```
##### Valeur de retour
| Name | Type | Description |
| ----- | ---- | ------------------------------------------------------------------------------------------- |
| ready | bool | Booléen représentant l'état du SDK (correctement initialisé ou pas encore prêt à l'emploi). |
#### runWhenReady()
Pour les SDK mobiles, le client Kameleoon ne peut pas s'initialiser immédiatement car il doit effectuer un appel serveur pour récupérer la configuration actuelle de tous les feature flags actifs. Utilisez la méthode [`runWhenReady()`](#runwhenready) de la classe `KameleoonClient` pour passer un callback qui sera exécuté dès que le SDK sera prêt à l'emploi. Vous pouvez également définir un délai d'attente.
Le callback donné en premier argument de cette méthode doit être une instance d'un type `Function(bool ready)`. Si `ready` est égal à `true`, le client Kameleoon est prêt et doit contenir du code qui déclenche un feature flag et implémente les variations. Sinon, le délai spécifié sera atteint avant l'initialisation du client. Le callback doit contenir du code qui implémente la variation de référence, car l'utilisateur sera exclu du feature flag si un timeout se produit.
```dart theme={null}
kameleoonClient.runWhenReady((ready) async {
final defaultProductsNumber = 5;
if (ready) {
late int recommendedProductsNumber;
try {
recommendedProductsNumber = await kameleoonClient.getFeatureVariable("feature_key", "product_number");
} on Exception {
recommendedProductsNumber = defaultProductsNumber;
}
} else {
recommendedProductsNumber = defaultProductsNumber;
}
setState(() {
_recommendedProductsNumber = recommendedProductsNumber;
});
}, 2000);
```
##### Arguments
| Name | Type | Description |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| callback (*required*) | `Function(bool)` | Objet callback avec le flag `ready`. |
| timeout (*optional)* | `Duration` | Délai d'attente (en millisecondes). S'il n'est pas fourni, il utilisera la valeur par défaut de `defaultTimeoutMilliseconds` (de `KameleoonClientConfig`) millisecondes. |
### Feature flags et variations
#### isFeatureActive()
* 📨 *Envoie des données de tracking à Kameleoon*
Pour activer une bascule de fonctionnalité, appelez cette méthode. Cette méthode accepte un `featureKey` comme argument requis pour vérifier si la fonctionnalité spécifiée sera active pour un visiteur.
Si le visiteur n'a jamais été associé à ce feature flag, la méthode renvoie une valeur booléenne aléatoire (`true` si la fonctionnalité doit être affichée au visiteur, sinon `false`). Si le visiteur est déjà enregistré avec ce feature flag, cette méthode renvoie la valeur précédente du feature flag.
Assurez-vous de configurer une gestion appropriée des erreurs comme indiqué dans l'exemple de code pour intercepter les exceptions potentielles.
Kameleoon utilise le tracking pour compter les sessions et les visiteurs lorsque vous appelez certaines méthodes, telles que `isFeatureActive()`, `getVariation()` ou `getVariations()`.
Utilisez la valeur par défaut `true` pour le paramètre `track` lorsque vous exposez les visiteurs à une variation et avez besoin de les compter. Définissez le paramètre `track` sur `false` uniquement si vous appelez ces méthodes avant d'exposer les visiteurs.
Par exemple, si vous appelez `getVariations()` pour récupérer toutes les variations avant d'exposer les visiteurs, définissez le paramètre `track` sur `false`. Ce paramètre empêche Kameleoon de compter prématurément une session. Vous pouvez ensuite déclencher le tracking ultérieurement lorsque vous exposez explicitement le visiteur.
Kameleoon envoie les données de tracking chaque seconde par défaut. Vous pouvez configurer cet intervalle jusqu'à cinq secondes en utilisant 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 compte les événements comme des sessions distinctes. Une visite apparaît dans vos rapports 30 minutes après le dernier événement enregistré dans la session.
```dart theme={null}
String featureKey = "new_checkout";
bool hasNewCheckout = false;
try {
hasNewCheckout = await kameleoonClient.isFeatureActive(featureKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error has occurred; feature flag isn't found in current configuration.
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error
}
if (hasNewCheckout) {
// Implement new checkout code here
}
```
La méthode `isFeatureActive()` é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
| Name | Type | Description |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| featureKey | `String` | Clé unique de la fonctionnalité que vous souhaitez exposer à un utilisateur. Ce champ est requis. |
| track | `bool` | Un paramètre optionnel pour activer ou désactiver le suivi de l'évaluation de la fonctionnalité (`true` par défaut). |
##### Valeur de retour
| Type | Description |
| -------------- | --------------------------------------------------------- |
| `Future` | Valeur de la fonctionnalité enregistrée pour un visiteur. |
##### Exceptions levées
| Type | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| SDKNotReady | Exception indiquant que le SDK n'a pas terminé son initialisation. |
| FeatureNotFound | Exception indiquant que l'ID de la fonctionnalité demandée n'a pas été trouvé dans la configuration interne du SDK. Cette exception signifie généralement que le feature flag n'a pas été activé du côté de Kameleoon (mais que le code implémentant la fonctionnalité est déjà déployé dans l'application). |
| PlatformException | Exception indiquant que l'intégration native du plugin fonctionne incorrectement. |
#### 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 un `visitorCode` et un `featureKey` comme arguments obligatoires. L'argument `track` est optionnel et vaut `true` par défaut.
Elle renvoie la `Variation` attribuée au visiteur. Si le visiteur n'est associé à aucune règle de feature flag, la méthode renvoie la `Variation` par défaut pour le feature flag donné.
Assurez-vous d'implémenter une gestion appropriée des erreurs dans votre code pour gérer les exceptions potentielles.
La variation par défaut fait référence à la variation attribuée à un visiteur lorsqu'il ne correspond à aucune règle de livraison prédéfinie pour un feature flag. En d'autres termes, c'est la variation de repli appliquée à tous les utilisateurs qui ne sont pas ciblés par des règles spécifiques. Elle est représentée par la variation dans la section "Then, for everyone else..." dans une interface de gestion.
```dart theme={null}
final String featureKey = "featureKey";
Variation? variation;
try {
variation = await client.getVariation(featureKey);
// disabling tracking
variation = await client.getVariation(featureKey, track: false);
} on SDKNotReady {
// Exception indicating that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The feature key is not in the configuration file that has been fetched by the SDK.
} on FeatureEnvironmentDisabled {
// The feature flag is disabled for the environment.
}
String? title = variation?.variables['title']?.value;
switch (variation?.key) {
case "on":
// Main variation key is selected for visitorCode
break;
case "alternative_variation":
// Alternative variation key
break;
default:
// Default variation key
break;
}
```
##### Arguments
| Name | Type | Description | Default |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------ | ------- |
| visitorCode (*required*) | `String` | Identifiant unique du visiteur. | |
| featureKey (*required*) | `String` | Clé de la fonctionnalité que vous souhaitez exposer à un visiteur. | |
| track (*optional*) | `bool` | Un paramètre optionnel pour activer ou désactiver le suivi de l'évaluation de la fonctionnalité. | `true` |
##### Valeur de retour
| Type | Description |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `Future` | Une [`Variation`](#variation) attribuée à un visiteur donné pour un feature flag spécifique. |
##### Exceptions levées
| Type | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Exception indiquant que le code visiteur fourni n'est pas valide. Il est soit vide, soit plus long que 255 caractères. |
| `FeatureNotFound` | Exception indiquant que la clé de fonctionnalité 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 fonctionnalité est déjà déployé dans l'application). |
| `FeatureEnvironmentDisabled` | Exception indiquant que le feature flag est désactivé pour l'environnement actuel du visiteur (par exemple, production, staging ou développement). |
#### getVariations()
* 📨 *Envoie des données de tracking à Kameleoon (selon le paramètre `track`)*
Récupère une map d'objets [`Variation`](#variation) attribués à un visiteur donné pour tous les feature flags.
Cette méthode itère sur tous les feature flags disponibles et renvoie la `Variation` attribuée pour chaque flag associé au visiteur spécifié. Elle prend `onlyActive` et `track` comme arguments optionnels.
* Si `onlyActive` est défini sur `true`, la méthode `getVariations()` renverra les variations des feature flags à condition que l'utilisateur ne soit pas bucketé avec la variation `off`.
* Le paramètre `track` contrôle si la méthode suivra ou non les assignations de variation. Par défaut, il est défini sur `true`. S'il est défini sur `false`, le suivi sera désactivé.
La map renvoyée se compose des clés de feature flag comme clés et de leurs `Variation` correspondantes comme valeurs. Si aucune variation n'est attribuée pour un feature flag, la méthode renvoie la `Variation` par défaut pour ce flag.
Une gestion appropriée des erreurs doit être implémentée pour gérer les exceptions potentielles.
La variation par défaut fait référence à la variation attribuée à un visiteur lorsqu'il ne correspond à aucune règle de livraison prédéfinie pour un feature flag. En d'autres termes, c'est la variation de repli appliquée à tous les utilisateurs qui ne sont pas ciblés par des règles spécifiques. Elle est représentée par la variation dans la section "Then, for everyone else..." dans une interface de gestion.
```dart theme={null}
try {
Map variations = await kameleoonClient.getVariations();
// only active variations
Map variations = await kameleoonClient.getVariations(onlyActive: true);
// disable tracking
Map variations = await kameleoonClient.getVariations(onlyActive: false, track: false);
} on SDKNotReady {
// Exception indicating that the SDK has not completed its initialization yet.
}
```
##### Arguments
| Name | Type | Description | Default |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | ------- |
| onlyActive (*optional*) | `bool` | Un paramètre optionnel indiquant s'il faut renvoyer les variations pour les feature flags actifs (`true`) ou pour tous (`false`). | `false` |
| track (*optional*) | `bool` | Un paramètre optionnel pour activer ou désactiver le suivi de l'évaluation de la fonctionnalité. | `true` |
##### Valeur de retour
| Type | Description |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `Future>` | Map qui contient les objets [`Variation`](#variation) attribués des feature flags en utilisant les clés des fonctionnalités correspondantes. |
##### Exceptions levées
| Type | Description |
| ------------- | ----------------------------------------------------------- |
| `SDKNotReady` | Indique que le SDK n'est pas encore entièrement initialisé. |
#### getFeatureList()
Renvoie une liste de clés de feature flags actuellement disponibles pour le SDK.
```dart theme={null}
try {
final allFeatureFlagKeys = await kameleoonClient.getFeatureList();
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
##### Valeur de retour
| Type | Description |
| ---------------------- | ------------------------------- |
| `Future>` | Liste des clés de feature flags |
#### getDataFile()
Pour évaluer tous les feature flags, utilisez [`getVariations()`](#getvariations). Cette méthode est plus efficace que d'appeler `DataFile` et d'itérer sur les flags avec [`getVariation()`](#getvariation).
Renvoie la configuration actuelle du SDK sous forme d'objet [`DataFile`](#datafile).
```dart theme={null}
try {
final dataFile = await kameleoonClient.getDataFile();
final dateModified = dataFile.dateModified;
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
##### Valeur de retour
| Type | Description |
| ---------- | ------------------------------------------------------------ |
| `DataFile` | Le [`DataFile`](#datafile) contenant la configuration du SDK |
##### Erreurs levées
| Type | Description |
| ------------- | ----------------------------------------------------------- |
| `SDKNotReady` | Indique que le SDK n'est pas encore entièrement initialisé. |
#### setForcedVariation()
La méthode vous permet d'assigner par programmation 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 tels que le débogage ou les tests personnalisés.
Lorsqu'une variation est **forcée**, 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`.
Une variation forcée est traitée de la même manière qu'une variation évaluée. Elle est suivie dans les analyses et stockée dans le contexte utilisateur comme toute variation standard évaluée, garantissant la cohérence dans les 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 que votre application reste stable et résiliente.
```dart theme={null}
final experimentId = 9516;
try {
// Forcing the variation "on" for the experiment 9516 for the visitor
await kameleoonClient.setForcedVariation(experimentId, "on")
// Forcing the variation "on" while preserving segmentation and targeting conditions during the experiment
await kameleoonClient.setForcedVariation(experimentId, "on", forceTargeting: false)
// Resetting the forced variation for the experiment 9516 for the visitor
await kameleoonClient.setForcedVariation(experimentId, null);
} on KameleoonException {
// Handling the exception
}
```
##### Arguments
| Name | Type | Description | Default |
| --------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| experimentId (*required*) | `int` | **Experiment Id** qui sera ciblé et sélectionné pendant le processus d'évaluation. | |
| variationKey (*required*) | `String` | **Variation Key** correspondant à une `Variation` qui doit être forcée comme valeur de retour pour l'expérience. Si la valeur est `null`, la variation forcée sera réinitialisée. | |
| forceTargeting (*optional*) | `bool` | Indique si le ciblage pour l'expérience doit être forcé et ignoré (`true`) ou appliqué comme dans le processus d'évaluation standard (`false`). | `true` |
##### Erreurs levées
| Type | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SDKNotReady` | Indique que le SDK n'est pas encore entièrement initialisé. |
| `FeatureExperimentNotFound` | 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 à la règle n'a pas encore été activée du côté de Kameleoon. |
| `FeatureVariationNotFound` | Exception indiquant que la variation key (id) demandée n'a pas été trouvée dans la configuration interne du SDK. Cela est généralement normal et signifie que l'expérience correspondante à la variation n'a pas encore été activée du côté de Kameleoon. |
Dans la plupart des cas, seule l'erreur de base, `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 chacune séparément en fonction des exigences spécifiques. De plus, pour une fiabilité accrue, les erreurs de langage général peuvent être gérées en incluant `Exception`.
#### evaluateAudiences()
* 📨 *Envoie des données de tracking à Kameleoon*
Cette méthode évalue les visiteurs par rapport à tous les segments disponibles dans Audiences Explorer et suit ceux qui correspondent.
`evaluateAudiences()` doit être appelée **après que toutes les données pertinentes du visiteur aient été définies ou mises à jour**, et **juste avant** d'obtenir une variation de fonctionnalité 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.
```dart theme={null}
try {
await kameleoonClient.evaluateAudiences();
} on KameleoonException {
// Handling the exception
}
```
##### Erreurs levées
| Type | Description |
| ------------- | ----------------------------------------------------------- |
| `SDKNotReady` | Indique que le SDK n'est pas encore entièrement initialisé. |
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 chacune séparément en fonction des exigences spécifiques. De plus, pour une fiabilité accrue, les erreurs de langage général peuvent être gérées en incluant `Exception`.
### Objectifs
#### trackConversion()
* 📨 *Envoie des données de tracking à Kameleoon*
Utilisez cette méthode pour suivre les conversions. Cette méthode nécessite un `goalId` pour suivre la conversion sur cet [objectif](/user-manual//assets/goals/create-a-goal) particulier. De plus, cette méthode accepte également les arguments `revenue`, `metadata` et `negative`.
La méthode `trackConversion()` ne renvoie aucune valeur. Cette méthode est non bloquante car l'appel serveur est effectué de manière asynchrone.
```dart theme={null}
kameleoonClient.trackConversion(goalId); // default revenue
kameleoonClient.trackConversion(goalId, 10); // provided revenue == 10
// Add metadata
kameleoonClient.trackConversionWithOptParams(goalId, metadata: [CustomData.withIndex(1, values: ["true"])]);
kameleoonClient.trackConversionWithOptParams(goalId, revenue: 10, metadata: [CustomData.withIndex(1, values: ["true"])]);
```
##### Arguments
| Name | Type | Description | Default |
| --------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| goalId (*required*) | `int` | ID de l'objectif. | |
| revenue (*optional*) | `double` | Revenu de la conversion. | `0` |
| negative (*optional*) | `bool` | Définit si le revenu est positif ou négatif. | `false` |
| metadata (*optional*) | `List` | Métadonnées de la conversion. [Doivent être définies au préalable dans l'application Kameleoon](/fr/user-manual/assets/goals/create-a-goal#métadonnées). | `[]` |
les valeurs de metadata sont accessibles via les [exports de données brutes](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export) et [la page de résultats](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata).
Si le paramètre `metadata` est fourni, Kameleoon utilisera ces valeurs spécifiées pour la conversion actuelle au lieu de ce qui a été précédemment collecté à l'aide de la méthode [`addData()`](#adddata). Si le paramètre est omis, Kameleoon utilisera les dernières valeurs suivies pour ces [`CustomData`](#customdata) avant la conversion et au cours de la même visite.
Kameleoon ne prendra en compte que les valeurs de métadonnées qui sont explicitement passées comme paramètres à la méthode `trackConversion()`.
Dans l'exemple ci-dessous, Kameleoon associera la conversion uniquement à la valeur de custom data explicitement fournie en paramètre (ici : index 5 avec la valeur 'Amex Credit Card').
```dart theme={null}
kameleoonClient.addData([
CustomData.withIndex(5, values: ["Credit Card"]),
CustomData.withIndex(9, values: ["Express Delivery"])
]);
kameleoonClient.trackConversionWithOptParams(1000, metadata: [CustomData.withIndex(5, values: ["Amex Credit Card"])]);
```
### Événements
#### onUpdateConfiguration()
Cette méthode s'appelait auparavant `updateConfigurationHandler`, qui a été supprimée dans la version `3.0.0` du SDK.
La méthode `onUpdateConfiguration()` vous permet de gérer l'événement lorsque la configuration a mis à jour les données. Elle prend un paramètre d'entrée, **handler**. Le handler qui sera appelé lorsque la configuration est mise à jour à l'aide d'un événement de configuration en temps réel.
```dart theme={null}
kameleoonClient.onUpdateConfiguration((timestamp) {
// timestamp value contains the value of Unix time (number of seconds elapsed since January 1, 1970) when configuration was updated.
});
```
##### Arguments
| Name | Type | Description |
| ------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| handler | `Function(int)?` | Le handler qui sera appelé lorsque la configuration sera mise à jour à l'aide d'un événement de configuration en temps réel. |
### Données du visiteur
#### getVisitorCode()
Renvoie le code visiteur unique utilisé dans le SDK.
```dart theme={null}
final visitorCode = await kameleoonClient.getVisitorCode();
```
##### Valeur de retour
| Type | Description |
| ---------------- | ---------------------------------------------------------------- |
| `Future` | Chaîne représentant un code visiteur unique utilisé dans le SDK. |
#### 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 les données pour décider si elles doivent 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. Au lieu de cela, toutes les données déclarées sont sauvegardées pour une transmission future via la méthode [`flush()`](#flush). Cette approche réduit le nombre d'appels serveur effectués, car les données sont généralement regroupées en un seul appel serveur déclenché par `flush()`.
La méthode [`trackConversion()`](#trackconversion) envoie également toutes les données précédemment associées, tout comme `flush()`. Il en va de même pour les méthodes [`getVariation()`](#getvariation) et [`getVariations()`](#getvariations) si une règle d'expérimentation est déclenchée.
Chaque visiteur ne peut avoir qu'une instance de données associée pour la plupart des types de données. Cependant, [`CustomData`](#customdata) est une exception. Les visiteurs peuvent avoir une instance de `CustomData` associée par index.
```dart theme={null}
try {
await kameleoonClient.addData([
Device(Devices.phone),
CustomData.withIndex(1, values: ["some custom value"]),
Conversion(32, 10f, false),
]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
##### Arguments
| Name | Type | Description | Default value |
| ------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| track (*optional*) | `bool` | Indique si les données ajoutées sont éligibles au suivi. Lorsqu'il est défini sur `false`, les données sont stockées localement et utilisées uniquement pour l'évaluation du ciblage ; elles ne sont pas envoyées à la Data API de Kameleoon. | `true` |
| data (*required*) | `List` | Collection de types de données Kameleoon. | |
##### Exceptions
| Type | Description |
| ------------------- | --------------------------------------------------------------------------------- |
| `PlatformException` | Exception indiquant que l'intégration native du plugin fonctionne incorrectement. |
#### flush()
* 📨 *Envoie des données de tracking à Kameleoon*
Les données associées à l'utilisateur actuel via la méthode `addData()` ne sont pas envoyées immédiatement au serveur. Elles sont stockées et accumulées jusqu'à ce qu'elles soient envoyées automatiquement par la méthode `trackConversion()`, ou envoyées manuellement en appelant la méthode `flush()`, donnant le contrôle sur le moment exact où les données sont envoyées aux serveurs. Par exemple, si la méthode `addData()` est appelée une douzaine de fois, envoyer des données au serveur après chaque appel à `addData()` gaspillerait des ressources. Appelez `flush()` une seule fois à la fin.
La méthode `flush()` ne renvoie aucune valeur. Cette méthode est non bloquante car l'appel serveur est effectué de manière asynchrone.
```dart theme={null}
kameleoonClient.flush(); // Interval tracking (most performant tracking method)
kameleoonClient.flush(instant: true); // Instant tracking
```
##### Exceptions levées
| Type | Description |
| ----------------- | -------------------------------------------------------------------------------------- |
| PlatformException | Exception indiquant que l'intégration native du plugin ne fonctionne pas correctement. |
#### getRemoteData()
Cette méthode s'appelait auparavant `retrieveDataFromRemoteSource`, qui a été supprimée dans la version `3.0.0` du SDK.
Utilisez cette méthode pour récupérer des données depuis un serveur distant Kameleoon en fonction du `siteCode` actif et de l'argument `key` (ou du `visitorCode` actif si la `key` est omise). Le `visitorCode` et le `siteCode` sont spécifiés dans `KameleoonClientFactory.create()`. Les données peuvent être stockées rapidement et facilement sur des serveurs distants hautement évolutifs à l'aide de la Data API de Kameleoon. L'application peut ensuite récupérer les données en utilisant cette méthode.
Notez que comme un appel serveur est requis, ce mécanisme est asynchrone.
```dart theme={null}
try {
final data = await kameleoonClient.getRemoteData("test");
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
```
##### Arguments
| Name | Type | Description |
| ---- | ------ | --------------------------------------------------------------------------------------------------- |
| key | String | La clé à laquelle les données que vous essayez de récupérer sont associées. Ce champ est optionnel. |
##### Valeur de retour
| Type | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| `Future` | Future avec récupération de données pour une `key` spécifique (ou `visitorCode` si la `key` est omise). |
| Type | Description |
| ----------------- | --------------------------------------------------------------------------------- |
| PlatformException | Exception indiquant que l'intégration native du plugin fonctionne incorrectement. |
| Exception | Exception indiquant que la requête a expiré ou toute autre raison d'échec. |
#### getRemoteVisitorData()
`getRemoteVisitorData()` est une méthode asynchrone pour récupérer les données de visites Kameleoon pour le `visitorCode` depuis la Data API de Kameleoon. Cette méthode ajoute les 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 via cette méthode jouent un rôle important lorsque vous souhaitez :
* utiliser des données collectées sur d'autres appareils.
* accéder à l'historique d'un utilisateur, comme des custom data collectées lors de visites précédentes.
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 avoir à appeler `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).
```dart theme={null}
// Visitor data will be fetched and automatically added for `visitorCode`.
try {
final visitorData = await kameleoonClient.getRemoteVisitorData();
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
// If you only want to fetch data and add it yourself manually, set addData == `false`.
try {
final visitorData = await kameleoonClient.getRemoteVisitorData(addData: false);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
// If you want to fetch custom list of data types
final filter = RemoteVisitorDataFilter.withValues(
previousVisitAmount: 25,
currentVisit: true,
conversions: true,
);
try {
final visitorData = await kameleoonClient.getRemoteVisitorData(filter: filter, addData: false);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
```
##### Arguments
| Name | Type | Description |
| ------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filter | `RemoteVisitorDataFilter` | Filtre qui sélectionne les données à récupérer depuis l'historique des visites. Par défaut, `getRemoteVisitorData` récupère les `CustomData` de la visite actuelle et de la dernière visite précédente (`RemoteVisitorDataFilter()`). Tous les autres paramètres du filtre sont par défaut à `false`. Ce champ est optionnel. |
| addData | boolean | Un booléen indiquant si la méthode doit automatiquement ajouter les données récupérées pour un visiteur. Si non spécifié, la valeur par défaut est **true**. Ce champ est optionnel. |
##### Valeur de retour
| Type | Description |
| -------------------- | ------------------------------------------------------------- |
| `Future>` | Un tableau contenant les données récupérées pour le visiteur. |
##### Exceptions levées
| Type | Description |
| ----------------- | -------------------------------------------------------------------------------------- |
| PlatformException | Exception indiquant que l'intégration native du plugin ne fonctionne pas correctement. |
| Exception | Exception indiquant que la requête a expiré ou toute autre raison d'échec. |
##### Utiliser les 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 de 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, supposons que vous souhaitiez récupérer des données sur les visiteurs qui ont accompli un 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 des paramètres dans la méthode `getRemoteVisitorData()` pour récupérer des données sur une variété de comportements des visiteurs.
Voici la liste des options disponibles pour `RemoteVisitorDataFilter` :
| Name | Type | Description | Default |
| ---------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| previousVisitAmount (*optional*) | `int` | Nombre de visites précédentes pour lesquelles récupérer des 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` |
| geolocation (*optional*) | `boolean` | Si true, les données de géolocalisation 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` |
| pageViews (*optional*, *web only*) | `boolean` | Si true, les données de page seront récupérées. | `false` |
| device (*optional*, *web only*) | `boolean` | Si true, les données d'appareil seront récupérées. | `false` |
| browser (*optional*, *web only*) | `boolean` | Si true, les données de navigateur seront récupérées. | `false` |
| operatingSystem (*optional*, *web only*) | `boolean` | Si true, les données du système d'exploitation 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` |
| cbs (*optional*) | `boolean` | Si true, les données de score Contextual Bandit seront récupérées. | `false` |
#### getVisitorWarehouseAudience()
Récupère toutes les données d'audience associées au visiteur dans votre data warehouse. Le paramètre optionnel `warehouseKey` est généralement votre ID utilisateur interne. Le paramètre `customDataIndex` correspond à la custom data Kameleoon que Kameleoon utilise pour cibler vos visiteurs. Vous pouvez consulter la [documentation sur le ciblage warehouse](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) pour plus de détails. La méthode renvoie le résultat sous forme d'objet `CustomData`, confirmant que les données ont été ajoutées au visiteur et sont disponibles à des fins de ciblage.
Comme un appel serveur est requis, ce mécanisme est asynchrone.
```dart theme={null}
try {
final customData = await kameleoonClient.getVisitorWarehouseAudience(customDataIndex);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
// If you need to specify warehouse key
try {
final customData = await kameleoonClient.getVisitorWarehouseAudience(customDataIndex, "warehouseKey");
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
```
##### Arguments
| Name | Type | Description |
| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
| visitorCode | string | Une chaîne d'identification unique du visiteur, ne peut pas dépasser 255 caractères. |
| customDataIndex | int | Un entier représentant l'index de la custom data que vous souhaitez utiliser pour cibler vos Audiences BigQuery. |
| warehouseKey | string | Une clé unique pour identifier les données du warehouse (généralement, votre ID utilisateur interne). Ce champ est optionnel. |
##### Valeur de retour
| Type | Description |
| -------------------- | ---------------------------------------------------------------------------------- |
| `Future` | Une instance `CustomData` confirmant que les données ont été ajoutées au visiteur. |
##### Exceptions levées
| Type | Description |
| ----------------- | -------------------------------------------------------------------------------------- |
| PlatformException | Exception indiquant que l'intégration native du plugin ne fonctionne pas correctement. |
| Exception | Exception indiquant que la requête a expiré ou toute autre raison d'échec. |
#### setLegalConsent()
Vous devez utiliser cette méthode pour spécifier si le visiteur a donné son consentement légal pour l'utilisation de ses données personnelles. Définir le paramètre `consent` sur `false` limite les types de données que vous pouvez inclure dans les requêtes de tracking. Cette méthode vous aide à respecter les exigences légales et réglementaires tout en gérant de manière responsable les données des visiteurs. Vous pouvez trouver plus d'informations sur les données personnelles dans la [politique de gestion du consentement](/user-manual/project-management/consent-management-policy).
```dart theme={null}
try {
final customData = await kameleoonClient.setLegalConsent(true);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error (including network issues).
}
```
##### Arguments
| Name | Type | Description |
| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| consent | 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. Ce champ est requis. |
##### Exceptions levées
| Type | Description |
| ----------------- | --------------------------------------------------------------------------------- |
| PlatformException | Exception indiquant que l'intégration native du plugin fonctionne incorrectement. |
##### Comportement de révocation du consentement
Ceci est applicable uniquement au SDK Flutter Web.
Lorsque vous appelez `setLegalConsent()` avec `consent=false`, le SDK ne supprime pas le cookie `kameleoonVisitorCode`. Au lieu de cela, il cesse de prolonger la date d'expiration du cookie, permettant au cookie de persister jusqu'à son expiration naturelle.
Si vos exigences de conformité exigent la suppression immédiate du fichier cookie lors du désengagement, vous devez le supprimer manuellement en utilisant les méthodes natives de gestion des cookies de votre framework. Le SDK ne supprimera pas le fichier automatiquement.
### Types de données
Cette section liste les types `Data` supportés par Kameleoon. Plusieurs types de données standard sont fournis, ainsi que le type `CustomData` pour définir des types de données personnalisés.
#### Conversion
L'ensemble de données `Conversion` stocké ici peut être utilisé pour filtrer les rapports d'expérience et de personnalisation par tout objectif qui lui est associé.
* Chaque visiteur peut avoir plusieurs objets `Conversion`.
* Vous pouvez trouver le `goalId` dans l'application Kameleoon.
| Name | Type | Description | Default |
| --------------------- | ------------------ | -------------------------------------------- | ------- |
| goalId (*required*) | `int` | ID de l'objectif. | |
| revenue (*optional*) | `double` | Revenu de la conversion | `0` |
| negative (*optional*) | `bool` | Définit si le revenu est positif ou négatif. | `false` |
| metadata (*optional*) | `List` | Métadonnées de la conversion. | `[]` |
```dart theme={null}
try {
final conversion = Conversion(32, 10);
final conversionMetadata = Conversion(32, 10, false, [CustomData.withIndex(1, values: ["true"])]);
final conversionOptParams = Conversion.withOptParams(32, metadata: [CustomData.withIndex(1, values: ["true"])]);
await kameleoonClient.addData([conversion, conversionMetadata, conversionOptParams]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### CustomData
Ce type de données est disponible pour les deux types de SDK : Mobile et Web.
`CustomData` permet d'associer facilement tout type de données à chaque visiteur. `CustomData` peut ensuite être utilisé comme condition de ciblage dans des [segments](/user-manual/assets/segments/create-a-segment/) ou comme filtre/décomposition dans les rapports d'expériences.
Pour en savoir plus sur les custom data, veuillez consulter cet [article](/developer-docs/custom-data).
| Name | Type | Description | |
| ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| index/name (*required*) | `int`/`String` | Index ou Nom de la custom data. **Soit `index` soit `name` doit être fourni** pour identifier les données. | |
| overwrite (*optional*) | `bool` | Flag pour contrôler explicitement comment les valeurs sont stockées et comment elles apparaissent dans les rapports. [Voir plus](/developer-docs/custom-data#default-logic-when-overwrite-parameter-is-false-or-omitted) | `true` |
| values (*optional*) | `List` | Valeurs de la custom data à stocker. | |
* Chaque visiteur ne peut avoir qu'une seule `CustomData` pour chaque `index` unique. Ajouter une autre `CustomData` avec le même `index` remplacera la `CustomData` existante.
* L'`index` de la custom data peut être trouvé dans le [dashboard Custom Data](/user-manual/assets/custom-data/manage-custom-data) sous la colonne « INDEX ».
* Pour empêcher le SDK d'envoyer des 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 de `CustomData` créée avec un nom alors que la configuration de l'instance du SDK n'est pas à jour ou que le nom n'est pas enregistré entraînera l'ignorance des données.
```dart theme={null}
try {
await kameleoonClient.addData([CustomData.withIndex(1, values: ["some custom value"])]);
// With several values
await kameleoonClient.addData(CustomData.withIndex(1, values: ["value 1", "value 2"]))
// To set the 'overwrite' flag to false
await kameleoonClient.addData(CustomData.withIndex(1, overwrite: false, values: ["first value", "second value"]))
// To use a name instead of the index
await kameleoonClient.addData(CustomData.withName("my-custom-data", values: ["value"]))
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### Device
Ce type de données est disponible pour les deux types de SDK : Mobile et Web.
Stocker des informations sur l'appareil de l'utilisateur.
| Name | Type | Description |
| ------ | ------- | ---------------------------------------------------------------------------- |
| device | Devices | Liste des appareils : `phone`, `table`, `desktop`. Ce champ est obligatoire. |
```dart theme={null}
try {
await kameleoonClient.addData([Device(Devices.phone)]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### Geolocation
Ce type de données est disponible pour les deux types de SDK : Mobile et Web.
`Geolocation` contient les détails de géolocalisation du visiteur.
| 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. |
| latitude (*optional*) | `double?` | La coordonnée de latitude représentant l'emplacement du visiteur. Le nombre de coordonnées représente des degrés décimaux. |
| longitude (*optional*) | `double?` | La coordonnée de longitude représentant l'emplacement du visiteur. Le nombre de coordonnées représente des degrés décimaux. |
* Chaque visiteur ne peut avoir qu'une seule `Geolocation`. L'ajout d'une seconde `Geolocation` remplace la première.
```dart theme={null}
try {
await kameleoonClient.addData([Geolocation("France", region: "Île-de-France", city: "Paris")]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### Browser
Ce type de données est disponible uniquement pour le Web SDK
L'ensemble de données `Browser` stocké ici peut être utilisé pour filtrer les rapports d'expériences et de personnalisation par toute valeur qui lui est associée.
| Name | Type | Description |
| -------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
| browser (*required*) | `Browsers` | Liste des navigateurs : `chrome`, `internetExplorer`, `firefox`, `safari`, `opera`, `other`. |
| version (*optional*) | `double?` | Version du navigateur, le nombre à virgule flottante représente la version majeure et mineure du navigateur |
```dart theme={null}
try {
await kameleoonClient.addData([Browser(Browsers.chrome)]);
await kameleoonClient.addData([Browser(Browsers.chrome, 10.0)]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### PageView
Ce type de données est disponible uniquement pour les SDK Web.
| Name | Type | Description |
| --------- | ----------- | ------------------------------------------------------- |
| url | String | URL de la page consultée. Ce champ est obligatoire. |
| title | String | Titre de la page consultée. Ce champ est obligatoire. |
| referrers | `List` | Référents des pages consultées. Ce champ est optionnel. |
L'index (ID) du référent est disponible dans la page de configuration du canal d'acquisition dans l'application Kameleoon. Attention : cet index commence à 0, donc le premier [canal d'acquisition](/user-manual/assets/advanced-targeting-tools/create-an-acquisition-channel) que vous créez pour un site donné aura l'ID 0, et non 1.
```dart theme={null}
try {
await kameleoonClient.addData([PageView("https://url.com", "title", [3])]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### OperatingSystem
Ce type de données est disponible uniquement pour les SDK Web.
`OperatingSystem` contient des informations sur le système d'exploitation de l'appareil du visiteur.
Chaque visiteur ne peut avoir qu'un seul `OperatingSystem`. L'ajout d'un second `OperatingSystem` remplace le premier.
| Name | Type | Description |
| ---- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| type | `OperatingSystems` | Liste des systèmes d'exploitation : `windows`, `mac`, `ios`, `linux`, `android`, `windowsPhone` . Ce champ est requis. |
```dart theme={null}
try {
await kameleoonClient.addData([OperatingSystem(OperatingSystem.linux)]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
#### Cookie
Ce type de données est disponible uniquement pour les SDK Web.
`Cookie` contient des informations sur le cookie stocké sur l'appareil du visiteur.
| Name | Type | Description |
| ------- | --------------------- | ------------------------------------------------------------------------------------------ |
| cookies | `Map` | Une map d'objets de chaîne composée de clés et de valeurs de cookies. Ce champ est requis. |
Chaque visiteur ne peut avoir qu'un seul `Cookie`. Ajouter un second `Cookie` remplace le premier.
```dart theme={null}
try {
await kameleoonClient.addData([Cookie({
"my_key1": "my_value1",
"my_key2": "my_value2"
})]);
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
### Types renvoyés
#### DataFile
Le `DataFile` contient les détails de configuration du SDK.
Il peut être étendu avec des informations supplémentaires si les clients le demandent. 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 | `int` | L'horodatage (en millisecondes) indiquant la dernière modification du `DataFile`. |
```dart 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.
final featureFlags = dataFile.featureFlags;
// Retrieves the last modification timestamp of the DataFile.
// The value is an int representing milliseconds since the Unix epoch.
final 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), ses [`Rules`](#rule), son statut d'environnement et d'autres détails connexes.
Il peut être étendu avec des informations supplémentaires si les clients le demandent. Si vous avez besoin de plus de détails, veuillez contacter votre Customer Success Manager.
| Name | Type | Description |
| ------------------- | ------------------------ | ------------------------------------------------------------------ |
| environmentEnabled | `bool` | 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 clés de variation. |
| rules | `List` | Une liste d'objets `Rule` |
```dart theme={null}
// Check whether the feature flag is enabled in the current environment
final isEnvironmentEnabled = featureFlag.environmentEnabled
// Retrieve the key of the default variation
final defaultVariationKey = featureFlag.defaultVariationKey
// Retrieve the default variation object
final defaultVariation = featureFlag.defaultVariation
// Retrieve all variations of the feature flag as a map (key = variation key, value = Variation object)
final variations = featureFlag.variations
// Retrieve all targeting rules associated with the feature flag
final rules = featureFlag.rules
```
#### Rule
Le `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 le demandent. 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 clés de variation. |
```dart theme={null}
// Retrieve all variations of the rule as a map (key = variation key, value = Variation object)
final variations = rule.variations
```
#### Variation
`Variation` contient des informations sur la variation attribuée au visiteur (ou la variation par défaut, s'il n'existe aucune attribution spécifique).
| Name | Type | Description |
| ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | `String` | Le nom de la variation. |
| key | `String` | La clé unique identifiant la variation. |
| id | `int?` | L'ID de la variation attribuée (ou `-1` s'il s'agit de la variation par défaut). |
| experimentId | `int?` | L'ID de l'expérience associée à la variation (ou `-1` si par défaut). |
| variables | `Map` | Une map contenant les variables de la variation attribuée, indexée par les noms de variables. Cela peut être une collection vide si aucune variable n'est associée. |
* L'objet `Variation` fournit des détails sur la variation attribuée et son expérience associée, tandis que l'objet [`Variable`](#variable) contient des détails spécifiques sur chaque variable dans une variation.
* Assurez-vous que votre code gère le cas où `id` ou `experimentId` peut être `-1`, indiquant une variation par défaut.
* La map `variables` peut être vide si aucune variable n'est associée à la variation.
```dart theme={null}
// Retrieving the variation name
var variationName = variation.name
// Retrieving the variation key
var variationKey = variation.key;
// Retrieving the variation id
var variationId = variation.id;
// Retrieving the experiment id
var experimentId = variation.experimentId;
// Retrieving the variables map
var 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**. |
| value | `dynamic` | La valeur de la variable, qui peut être de l'un des types suivants : **bool**, **int**, **double**, **String**, **Map\** (objet json), **\[dynamic]** (tableau json). |
```swift theme={null}
// Retrieving the variables map
var variables = variation.variables;
// Variable type can be retrieved for further processing
var type = variables["isDiscount"]?.type ?? "";
// Retrieving the variable value by key
var isDiscount = variables["isDiscount"]?.value as bool? ?? false;
// Variable value can be of different types
var title = variables["title"]?.value as String? ?? "";
```
### Méthodes dépréciées
Ces méthodes sont dépréciées et seront supprimées dans la version `4.0.0` du SDK.
#### isReady()
Utilisez [`isReadyAsync()`](#isreadyasync) à la place. Sur iOS et Android, [`isReady()`](#isready) peut renvoyer des résultats incorrects (`false`) même si le SDK a déjà été initialisé avec [`defaultDataFile`](#initialize-the-kameleoon-client).
Pour les SDK mobiles, le client Kameleoon ne peut pas s'initialiser immédiatement car il doit effectuer un appel serveur pour récupérer la configuration actuelle des feature flags actifs. Utilisez `isReady()` pour vérifier si le SDK est prêt en appelant cette méthode avant de déclencher tout feature flag.
Alternativement, vous pouvez utiliser un callback (voir la méthode [`runWhenReady()`](#runwhenready) pour plus de détails).
```dart theme={null}
final ready = kameleoonClient.isReady();
```
##### Valeur de retour
| Name | Type | Description |
| ----- | ---- | ------------------------------------------------------------------------------------------- |
| ready | bool | Booléen représentant l'état du SDK (correctement initialisé ou pas encore prêt à l'emploi). |
#### getFeatureVariationKey()
* 📨 *Envoie des données de tracking à Kameleoon*
Utilisez [`getVariation()`](#getvariation) à la place.
Utilisez cette méthode pour obtenir la clé de variation de fonctionnalité pour un visiteur. Cette méthode prend `featureKey` comme argument requis pour récupérer la clé de variation pour l'utilisateur spécifié.
Si le visiteur n'a jamais été associé à ce feature flag, le SDK renvoie une clé de variation attribuée aléatoirement (selon les règles du feature flag). Si le visiteur est déjà enregistré avec ce feature flag, cette méthode renvoie la clé de variation précédente. Si l'utilisateur ne correspond à aucune des règles, la valeur par défaut sera renvoyée, qui est définie dans le compte de votre client.
Assurez-vous de configurer une gestion appropriée des erreurs comme indiqué dans l'exemple de code pour intercepter les exceptions potentielles.
```dart theme={null}
String featureKey = "new_checkout";
String variationKey = "";
try {
variationKey = await kameleoonClient.getFeatureVariationKey(featureKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error has occurred; feature flag isn't found in current configuration.
} on FeatureEnvironmentDisabled {
// The feature flag is disabled for the environment.
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error.
}
switch(variationKey) {
case 'on':
// Main variation key is selected for visitorCode
break;
case 'alternative_variation':
// Alternative variation key
break;
default:
// Default variation key
break;
}
```
##### Arguments
| Name | Type | Description |
| ---------- | ------ | ----------------------------------------------------------------------------------------------- |
| featureKey | String | Clé de la fonctionnalité que vous souhaitez exposer à un utilisateur. Ce champ est obligatoire. |
##### Valeur de retour
| Type | Description |
| ---------------- | -------------------------------------------------------------- |
| `Future` | Clé de variation du feature flag enregistrée pour un visiteur. |
##### Exceptions levées
| Type | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| SDKNotReady | Exception indiquant que le SDK n'a pas terminé son initialisation. |
| FeatureNotFound | Exception indiquant que l'ID de la fonctionnalité demandée n'a pas été trouvé dans la configuration interne du SDK. Cette exception signifie généralement que le feature flag n'a pas été activé du côté de Kameleoon (mais que le code implémentant la fonctionnalité est déjà déployé dans l'application). |
| PlatformException | Exception indiquant que l'intégration native du plugin ne fonctionne pas correctement. |
#### getActiveFeatures()
* Utilisez [`getVariations()`](#getvariations) à la place.
* Anciennement appelée `getFeatureListForVisitorCode`, qui a été supprimée dans la version `4.0.0` du SDK.
La méthode `getActiveFeatures` récupère des informations sur les feature flags actifs disponibles pour le visiteur.
```dart theme={null}
try {
final activeFeatures = await kameleoonClient.getActiveFeatures();
} on KameleoonException {
// Generic exception in native plugin integration occurred.
}
```
##### Valeur de retour
| Type | Description |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `Future>` | Map qui contient les variations attribuées des fonctionnalités actives en utilisant les clés des fonctionnalités actives correspondantes. |
#### getFeatureVariable()
* 📨 *Envoie des données de tracking à Kameleoon*
- Utilisez [`getVariation()`](#getvariation) à la place.
- Cette méthode s'appelait auparavant `obtainFeatureVariable`, qui a été supprimée dans la version `3.0.0` du SDK.
Cette méthode obtient la valeur d'une variable de clé de variation pour un utilisateur spécifique. Elle prend un `featureKey` et un `variableKey` comme arguments requis.
Si le visiteur n'a jamais été associé au `featureKey`, le SDK renvoie une valeur de variable attribuée aléatoirement pour la clé de variation spécifiée (selon les règles du feature flag). Si le visiteur est déjà enregistré avec ce feature flag, cette méthode renvoie la valeur de variable pour la variation précédemment enregistrée. Si l'utilisateur ne correspond à aucune des règles, la valeur de variable par défaut est renvoyée.
Assurez-vous de configurer une gestion appropriée des erreurs comme indiqué dans l'exemple de code pour intercepter les exceptions potentielles.
```dart theme={null}
String featureKey = "feature_key";
String variableKey = "product_number";
int recommendedProductsNumber = 5;
try {
recommendedProductsNumber = await kameleoonClient.getFeatureVariable(featureKey, variableKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error has occurred; feature flag isn't found in current configuration.
} on FeatureEnvironmentDisabled {
// The feature flag is disabled for the environment.
} on FeatureVariableNotFound {
// Requested variable not defined in Kameleoon.
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error.
}
setState(() {
_recommendedProductsNumber = recommendedProductsNumber;
});
```
##### Arguments
| Name | Type | Description |
| ----------- | ------ | ----------------------------------------------------------------------------------------------- |
| featureKey | String | Clé de la fonctionnalité que vous souhaitez exposer à un utilisateur. Ce champ est obligatoire. |
| variableKey | String | Nom de la variable pour laquelle vous souhaitez obtenir une valeur. Ce champ est obligatoire. |
##### Valeur de retour
| Type | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Future` | Valeur de la variable de la variation enregistrée pour un visiteur pour ce feature flag. Types possibles : `bool`, `int`, `double`, `String`, `List`, `Map` |
##### Exceptions levées
| Type | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| SDKNotReady | Exception indiquant que le SDK n'a pas terminé son initialisation. |
| FeatureNotFound | Exception indiquant que l'ID de la fonctionnalité demandée n'a pas été trouvé dans la configuration interne du SDK. Cette exception signifie généralement que le feature flag n'a pas été activé du côté de Kameleoon (mais que le code implémentant la fonctionnalité est déjà déployé dans l'application). |
| FeatureEnvironmentDisabled | Exception indiquant que le feature flag est désactivé pour l'environnement actuel du visiteur (par exemple, production, staging ou développement). |
| FeatureVariableNotFound | Exception indiquant que la variable spécifiée n'a pas été trouvée. Vérifiez que la clé de variable dans l'application Kameleoon correspond à la clé dans votre code. |
| PlatformException | Exception indiquant que l'intégration native du plugin fonctionne incorrectement. |
#### getFeatureVariationVariables()
* Utilisez [`getVariation()`](#getvariation) à la place.
* Cette méthode s'appelait auparavant `getFeatureAllVariables`, qui a été supprimée dans la version `4.0.0` du SDK.
Pour récupérer toutes les variables d'une fonctionnalité, appelez cette méthode. Vous pouvez modifier les variables de votre fonctionnalité dans l'application Kameleoon.
Cette méthode prend un paramètre d'entrée : `featureKey`. Elle renvoie les données sous forme de type `Map`, telles que définies dans l'application Kameleoon. Elle lève une exception (`FeatureNotFound`) si la fonctionnalité demandée n'a pas été trouvée dans la configuration interne du SDK.
```dart theme={null}
final featureKey = "featureKey";
final variationKey = "variationKey";
try {
final allVariables = await client.getFeatureVariationVariables(featureKey, variationKey);
} on SDKNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} on FeatureNotFound {
// The error has occurred; feature flag isn't found in current configuration.
} on FeatureEnvironmentDisabled {
// The feature flag is disabled for the environment.
} on KameleoonException {
// Generic exception in native plugin integration occurred.
} on Exception {
// Any other error.
}
```
##### Arguments
| Name | Type | Description |
| ------------ | ------ | ----------------------------------------------------------------------------------------------- |
| featureKey | String | Clé d'identification de la fonctionnalité que vous souhaitez obtenir. Ce champ est obligatoire. |
| variationKey | String | La clé de la variation que vous souhaitez obtenir. Ce champ est obligatoire. |
##### Valeur de retour
| Type | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Future>` | Données associées à ce feature flag. Les valeurs peuvent être un int, double, bool, String, List ou Map (selon le type défini sur l'interface web). |
##### Exceptions levées
| Type | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FeatureNotFound | Exception indiquant que la fonctionnalité demandée n'a pas été trouvée dans la configuration interne du SDK. Cette exception est généralement normale et signifie que le feature flag n'a pas été activé du côté de Kameleoon. |
| FeatureEnvironmentDisabled | Exception indiquant que le feature flag est désactivé pour l'environnement actuel du visiteur (par exemple, production, staging ou développement). |
| FeatureVariationNotFound | Exception indiquant que l'ID de variation demandé n'a pas été trouvé dans la configuration interne du SDK. Cette exception est généralement normale et signifie que l'expérience correspondant à la variation n'a pas été activée du côté de Kameleoon. |
| PlatformException | Exception indiquant que l'intégration native du plugin ne fonctionne pas correctement. |