Avec le SDK Elixir de Kameleoon, vous pouvez exécuter des expériences et activer des feature flags dans vos services et back-ends web Elixir.
Pour commencer : Pour obtenir de l’aide pour démarrer, consultez le guide du développeur.
Version : Dernière version du SDK Elixir : 0.8.6 Changelog.
Méthodes du SDK : Pour la documentation complète de référence du SDK Elixir, consultez la section référence.
Guide du développeur
Ce guide est conçu pour vous aider à intégrer rapidement le SDK Elixir et à commencer à évaluer des feature flags dans votre application Elixir.
Pour commencer
Installer le client Elixir
Ajoutez le SDK comme dépendance dans votre fichier mix.exs :
def deps do
[
{:kameleoon_client, "~> 0.8.6"}
]
end
Configuration supplémentaire
Créez un fichier de configuration client-elixir.conf pour fournir les identifiants et personnaliser le comportement du SDK.
Nous recommandons d’enregistrer ce fichier au chemin par défaut, /etc/kameleoon/client-elixir.conf. Kameleoon.ClientFactory.create utilise automatiquement ce chemin lorsque vous ne transmettez pas d’options de configuration. Si vous stockez le fichier ailleurs, indiquez le chemin avec l’option config_path: lors de la création du client.
Le SDK Elixir peut être configuré soit avec un fichier de configuration utilisé par Kameleoon.ClientFactory.create, soit en passant une structure %Kameleoon.ClientConfig\{\} avec l’option config:.
Le tableau suivant présente les propriétés disponibles que vous pouvez définir :
| Clé (Code / Fichier de configuration) | Description | Valeur par défaut |
|---|
client_id / clientId (obligatoire) | Requis pour l’authentification au service Kameleoon. Pour trouver votre client_id, consultez la documentation API credentials. | |
client_secret / clientSecret (obligatoire) | Requis pour l’authentification au service Kameleoon. Pour trouver votre client_secret, consultez la documentation API credentials. | |
session_duration_minutes / sessionDurationMinutes (optionnel) | Intervalle de temps, en minutes, pendant lequel le SDK conserve un visiteur et ses données associées en mémoire. | 30 minutes |
refresh_interval_minutes / refreshIntervalMinutes (optionnel) | Intervalle, en minutes, utilisé pour rafraîchir la configuration des expériences actives et des feature flags. | 60 minutes |
default_timeout_millis / defaultTimeoutMillis (optionnel) | Délai d’attente par défaut, en millisecondes, pour les requêtes réseau du SDK. | 10000 millisecondes |
tracking_interval_millis / trackingIntervalMillis (optionnel) | Intervalle, en millisecondes, utilisé pour regrouper les requêtes de tracking. Les valeurs sont limitées à la plage [1000, 5000]. | 1000 millisecondes |
environment / environment (optionnel) | Environnement à partir duquel la configuration du feature flag doit être utilisée. La valeur peut être production, staging ou development. | production |
top_level_domain / topLevelDomain (optionnel) | Le domaine de premier niveau actuel pour votre site web. Utilisez le format example.com sans protocole ni sous-domaines. | nil |
proxy_host / proxyHost (optionnel) | Hôte proxy pour les appels sortants du SDK. Formats pris en charge : https://my.prox, https://my.prox:4545, socks5://192.168.1.1:9000. | nil |
network_domain / networkDomain (optionnel) | Domaine personnalisé utilisé par les SDK pour les requêtes sortantes, souvent pour le proxy. Doit être un domaine valide (par exemple, example.com ou sub.example.com). Les formats invalides utilisent la valeur par défaut de Kameleoon. | nil |
Initialiser le client Kameleoon
Une fois que vous avez installé le SDK et configuré vos identifiants, créez un %Kameleoon.Client\{\} en utilisant Kameleoon.ClientFactory.
Fichier de configuration
Code
alias Kameleoon.Client
alias Kameleoon.ClientFactory
site_code = "a8st4f59bj"
{:ok, client} = ClientFactory.create(site_code, config_path: "/etc/kameleoon/client-elixir.conf")
:ok = Client.initialize(client)
alias Kameleoon.Client
alias Kameleoon.ClientConfig
alias Kameleoon.ClientFactory
site_code = "a8st4f59bj"
config = %ClientConfig{
client_id: "<client-id>",
client_secret: "<client-secret>",
refresh_interval_minutes: 60,
session_duration_minutes: 30,
default_timeout_millis: 10_000,
tracking_interval_millis: 1_000,
environment: "development",
top_level_domain: ".example.com",
proxy_host: "http://192.168.0.25:8080",
network_domain: "example.com"
}
{:ok, client} = ClientFactory.create(site_code, config: config)
:ok = Client.initialize(client)
%Kameleoon.Client\{\} est l’objet principal utilisé pour évaluer les feature flags, ajouter des données de visiteur et envoyer des requêtes de tracking.
- Il est recommandé d’utiliser
%Kameleoon.Client\{\} comme un objet singleton, car il sert de pont entre votre application et la plateforme Kameleoon. Il expose toutes les méthodes et propriétés requises pour exécuter efficacement vos expériences.
- Le SDK Elixir s’initialise via le Core natif. Vous devez appeler
initialize() avant de vous appuyer sur l’évaluation des fonctionnalités dans du code de production.
Activation d’un feature flag
Attribution d’un identifiant unique à un utilisateur
Pour attribuer un identifiant unique à un utilisateur, vous pouvez utiliser la méthode Client.get_visitor_code. Si un visitor code n’existe pas (à partir du cookie des en-têtes de requête), la méthode génère un identifiant unique aléatoire ou utilise un default_visitor_code que vous auriez généré. L’identifiant est ensuite défini dans un cookie des en-têtes de réponse.
Si vous utilisez Kameleoon en mode hybride, l’appel à la méthode Client.get_visitor_code garantit que l’identifiant unique (visitor code) est partagé entre le fichier d’application engine.js (anciennement nommé kameleoon.js) et le SDK.
Récupération de la configuration d’un flag
Pour implémenter un feature flag dans votre code, vous devez d’abord créer le feature flag dans votre compte Kameleoon.
Pour déterminer le statut ou la variation d’un feature flag pour un utilisateur spécifique, vous devez utiliser la méthode Client.get_variation ou Client.is_feature_active? afin de récupérer la configuration en fonction de la feature_key.
La méthode Client.get_variation gère à la fois les feature flags simples avec des états ON/OFF et les flags plus complexes avec plusieurs variations. La méthode récupère la variation appropriée pour l’utilisateur en vérifiant les règles du feature, en attribuant la variation et en la renvoyant en fonction de la feature_key et du visitor_code.
La méthode Client.is_feature_active? peut être utilisée si vous souhaitez récupérer la configuration d’un feature flag simple qui n’a qu’un état ON ou OFF, par opposition à des feature flags plus complexes avec plusieurs variations ou options de ciblage.
Si votre feature flag est associé à des variables (telles que des comportements spécifiques liés à chaque variation), Client.get_variation vous permet également d’accéder à l’objet Variation, qui fournit des détails sur la variation attribuée et son expérience associée. Cette méthode vérifie si l’utilisateur est ciblé, trouve la variation attribuée au visiteur et l’enregistre dans le stockage. Lorsque track=true, le SDK enverra l’événement d’exposition à l’expérience spécifiée lors de la prochaine requête de tracking, qui est automatiquement déclenchée en fonction du paramètre tracking_interval_millis du SDK. Par défaut, cet intervalle est défini à 1000 millisecondes (1 seconde).
La méthode Client.get_variation vous permet de contrôler si le tracking est effectué. Si track=false, aucun événement d’exposition ne sera envoyé par le SDK. Cela est utile si vous préférez ne pas suivre les données via le SDK et plutôt vous appuyer sur le tracking côté client géré par le moteur Kameleoon, par exemple. De plus, définir track=false est utile lors de l’utilisation de la méthode Client.get_variations, où vous pourriez n’avoir besoin que des variations de tous les flags sans déclencher d’événements de tracking. Si vous souhaitez en savoir plus sur le fonctionnement du tracking, consultez cet article.
Ajout de points de données pour cibler un utilisateur ou filtrer / découper les visites dans les rapports
Pour cibler un utilisateur, assurez-vous d’avoir ajouté les points de données pertinents à son profil avant de récupérer la variation du feature ou de vérifier si le flag est actif. Utilisez la méthode Client.add_data pour ajouter ces points de données au profil de l’utilisateur.
Pour récupérer les points de données collectés sur d’autres appareils ou pour accéder aux données passées de l’utilisateur (collectées côté client lors de l’utilisation de Kameleoon en mode hybride), utilisez la méthode Client.get_remote_visitor_data. Cette méthode récupère les données depuis les serveurs de manière asynchrone. Il est important d’appeler Client.get_remote_visitor_data avant de récupérer la variation ou de vérifier si le feature flag est actif, car ces données peuvent être nécessaires pour attribuer un utilisateur à une variation donnée.
Pour en savoir plus sur les conditions de ciblage disponibles, consultez l’article détaillé à ce sujet.
De plus, les points de données que vous ajoutez au profil du visiteur seront disponibles lors de l’analyse de vos expériences, vous permettant de filtrer et de découper vos résultats par facteurs tels que l’appareil et le navigateur. Le mode hybride de Kameleoon collecte automatiquement une variété de points de données côté client, ce qui facilite la décomposition de vos résultats en fonction de ces points de données pré-collectés. Consultez la liste complète ici.
Si vous devez suivre des points de données supplémentaires au-delà de ceux collectés automatiquement, vous pouvez utiliser la fonctionnalité Custom Data de Kameleoon. Les Custom Data vous permettent de capturer et d’analyser des informations spécifiques pertinentes pour vos expériences. N’oubliez pas d’appeler la méthode Client.flush pour envoyer les données collectées aux serveurs Kameleoon pour analyse.
Pour garantir l’exactitude de vos résultats, il est recommandé de filtrer les bots à l’aide du type de données UserAgent. Suivi des conversions d’objectifs
Lorsqu’un utilisateur effectue une action souhaitée (telle qu’un achat), elle est enregistrée comme une conversion. Pour suivre les conversions, utilisez la méthode Client.track_conversion et fournissez les paramètres visitor_code et goal_id requis.
La requête de suivi de conversion sera envoyée avec la prochaine requête de tracking planifiée, que le SDK envoie à intervalles réguliers (définis par tracking_interval_millis). Si vous préférez envoyer la requête immédiatement, utilisez la méthode Client.flush_instant.
Envoi d’événements aux solutions d’analyse
Pour suivre les conversions et envoyer des événements d’exposition à votre solution d’analyse client, vous devez d’abord implémenter Kameleoon en mode hybride. Ensuite, utilisez la méthode Client.get_engine_tracking_code.
La méthode Client.get_engine_tracking_code récupère le code de tracking unique requis pour envoyer des événements d’exposition à votre solution d’analyse. L’utilisation de cette méthode vous permet d’enregistrer les événements et de les envoyer à la plateforme d’analyse de votre choix.
Utilisation d’une clé de bucketing personnalisée
Par défaut, Kameleoon utilise un identifiant de visiteur anonyme unique (visitor_code) pour attribuer les utilisateurs aux variations des feature flags. Cet identifiant est généralement généré et stocké sur l’appareil de l’utilisateur (dans un cookie de navigateur pour les SDK côté client et côté serveur — dans un stockage persistant pour les SDK mobiles). Cependant, dans certains scénarios, vous pouvez avoir besoin de garantir que tous les utilisateurs d’une même organisation voient la même variante d’un feature flag.
L’option Clé de bucketing personnalisée vous permet de remplacer ce comportement par défaut en fournissant votre propre identifiant personnalisé pour le bucketing. Ce remplacement garantit que la logique d’attribution de Kameleoon utilise la clé que vous avez spécifiée au lieu du visitor_code par défaut.
Cas d’usage
L’utilisation d’une clé de bucketing personnalisée est essentielle pour maintenir la cohérence et l’exactitude de vos attributions de feature flags, en particulier dans les situations suivantes :
- Expériences au niveau du compte ou de l’organisation : Pour les produits B2B ou les scénarios où vous souhaitez attribuer tous les utilisateurs d’une même organisation à la même variation, vous pouvez utiliser un identifiant tel qu’un
account_id. Les clés de bucketing personnalisées sont cruciales pour les tests A/B de fonctionnalités qui impactent toute une équipe ou une entreprise.
En implémentant une clé de bucketing personnalisée, vous garantissez une cohérence et une exactitude accrues dans vos expériences, ce qui conduit à des résultats plus fiables et à une meilleure expérience utilisateur.
Détails techniques
Lorsque vous configurez une clé de bucketing personnalisée pour un feature flag, vous fournissez à Kameleoon un identifiant spécifique provenant des données de votre application :
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
:ok = Client.add_data(client, visitor_code, CustomData.new!(42, ["new_visitor_code"]))
- Fournir la clé personnalisée : Vous fournissez votre identifiant personnalisé au SDK Kameleoon en utilisant la méthode
Client.add_data. Dans cette méthode, vous passerez votre clé de bucketing personnalisée choisie sous la forme d’un objet CustomData. Ici, new_visitor_code fait référence à l’identifiant que vous souhaitez utiliser pour votre bucketing (par exemple, le nouveau user_id ou account_id).
Pour que la clé de bucketing personnalisée fonctionne correctement, elle doit également être définie et configurée pour le feature flag lors du processus de création ou de modification du flag. Sans cette configuration correspondante, le bucketing du SDK n’appliquera pas votre clé personnalisée. Pour des instructions détaillées sur la façon de configurer cela dans Kameleoon, consultez cet article.
- Logique de bucketing : Une fois qu’une clé de bucketing personnalisée est fournie via la méthode
Client.add_data, tous les calculs de hachage pour attribuer les utilisateurs aux variations utiliseront ce new_visitor_code (votre clé personnalisée) au lieu du visitor_code par défaut. L’utilisation du new_visitor_code signifie que la décision de bucketing est liée à votre identifiant personnalisé, garantissant des attributions cohérentes dans divers contextes où cet identifiant est présent.
- Suivi des données et analyse : Il est crucial de noter que, bien que le
new_visitor_code (votre clé personnalisée) soit utilisé pour les décisions de bucketing, toutes les données ultérieures (événements de tracking et conversions, par exemple) sont envoyées et associées au visitor_code d’origine. Cette séparation garantit que vos analyses reflètent avec précision les parcours et interactions individuels des utilisateurs dans le contexte plus large de votre expérience, même lorsque le bucketing est effectué à un niveau supérieur (comme un compte) ou sur plusieurs appareils/sessions. Vos données originales de visiteur restent intactes pour un reporting complet.
Exigences techniques
Pour utiliser efficacement une clé de bucketing personnalisée :
- La clé doit être un
String.t().
- Elle doit être unique pour l’entité que vous souhaitez bucketer (par exemple, si vous utilisez un
user_id, l’identifiant de chaque utilisateur doit être unique).
- La clé doit être disponible pour le SDK au moment exact où la décision du feature flag est évaluée pour cet utilisateur ou cette requête.
Conditions de ciblage
Les SDK Kameleoon prennent en charge une variété de conditions de ciblage prédéfinies que vous pouvez utiliser pour cibler les utilisateurs dans vos campagnes. Pour la liste des conditions prises en charge par ce SDK, consultez utiliser l’historique de visite pour cibler les utilisateurs.
Vous pouvez également utiliser vos propres données externes pour cibler les utilisateurs.
Expérimentation cross-device
Pour prendre en charge les visiteurs qui accèdent à une application depuis plusieurs appareils, Kameleoon permet la synchronisation des données de visiteur précédemment collectées sur chacun des appareils du visiteur, ainsi que la réconciliation de leur historique de visite sur tous les appareils grâce à l’expérimentation cross-device. Des études de cas et des informations détaillées sur la façon dont Kameleoon gère les données entre les appareils sont disponibles dans l’article sur l’expérimentation cross-device.
Synchronisation des données personnalisées entre les appareils
Bien que la synchronisation par mappage personnalisé soit utilisée pour aligner les données de visiteur entre les appareils, elle n’est pas toujours nécessaire. Voici deux scénarios où la synchronisation par mappage personnalisé n’est pas requise :
Même ID utilisateur sur tous les appareils
Si le même ID utilisateur est utilisé de manière cohérente sur tous les appareils, la synchronisation est gérée automatiquement sans synchronisation par mappage personnalisé. Il suffit d’appeler la méthode Client.get_remote_visitor_data lorsque vous souhaitez synchroniser les données collectées entre plusieurs appareils.
Instances multi-serveurs avec identifiants cohérents
Dans des configurations complexes impliquant plusieurs serveurs (par exemple, des instances de serveurs distribués), où le même ID utilisateur est disponible sur tous les serveurs, la synchronisation entre les serveurs (avec Client.get_remote_visitor_data) est suffisante sans synchronisation par mappage personnalisé supplémentaire.
Les clients qui ont besoin de données supplémentaires peuvent se référer à la description de la méthode Client.get_remote_visitor_data pour plus d’informations. Dans le code ci-dessous, on suppose que le même identifiant unique (dans ce cas, le visitor_code, également appelé userId) est utilisé de manière cohérente entre les deux appareils pour une récupération précise des données.
Si vous souhaitez synchroniser les données collectées en temps réel, vous devez choisir le scope Visitor pour vos données personnalisées.
# Dans cet exemple, une Custom Data avec l'index `90` a été définie sur le scope "Visitor" dans Kameleoon.
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
visitor_scope_custom_data_index = 90
:ok = Client.add_data(client, visitor_code, CustomData.new!(visitor_scope_custom_data_index, ["your data"]))
:ok = Client.flush_instant(client, visitor_code)
# Avant de travailler avec les données, appelez la méthode `get_remote_visitor_data`.
:ok = Client.get_remote_visitor_data(client, visitor_code)
# Après avoir appelé la méthode, le SDK sur l'Appareil B aura accès aux CustomData de scope Visitor définies sur l'Appareil A.
# Ainsi, "your data" sera disponible pour le ciblage et le suivi du visiteur.
Utilisation de données personnalisées pour la fusion de sessions
L’expérimentation cross-device permet de combiner l’historique d’un visiteur sur chacun de ses appareils (réconciliation d’historique). La réconciliation d’historique permet de fusionner différentes sessions de visiteur en une seule. Pour réconcilier l’historique des visites, utilisez CustomData pour fournir un identifiant unique pour le visiteur. Pour plus d’informations, consultez la documentation dédiée.
Une fois la réconciliation cross-device activée, l’appel à Client.get_remote_visitor_data avec le paramètre userId récupère toutes les données connues pour un utilisateur donné.
Les sessions avec le même identifiant verront toujours la même variation dans une expérience. Dans la vue Visiteur des pages de résultats de votre expérience, ces sessions apparaîtront comme un visiteur unique.
La configuration du SDK garantit que les sessions associées voient toujours la même variation de l’expérience. Cependant, il existe certaines limitations concernant l’attribution de variations cross-device. Ces limitations sont décrites ici.
Suivez le guide activation de la réconciliation d’historique cross-device pour configurer vos données personnalisées sur la plateforme Kameleoon.
Ensuite, vous pouvez utiliser le SDK normalement. Les méthodes suivantes peuvent être utiles dans le contexte de la fusion de sessions :
Client.get_remote_visitor_data avec UniqueIdentifier(true) ajouté - pour récupérer les données de tous les visiteurs liés.Client.track_conversion ou Client.flush avec la donnée UniqueIdentifier(true) ajoutée - pour suivre certaines données pour un visiteur spécifique qui est associé à un autre visiteur.
Voici un exemple d’utilisation de données personnalisées pour la fusion de sessions.
# Dans cet exemple, 91 représente l'index de la Custom Data configurée comme identifiant unique dans Kameleoon.
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
alias Kameleoon.Data.UniqueIdentifier
mapping_index = 91
feature_key = "ff123"
anonymous_visitor_code = "anonymous-visitor"
user_id = "authenticated-user"
# 1. Avant l'authentification du visiteur
# Récupérer la variation pour un visiteur non authentifié.
# On suppose que anonymousVisitorCode est l'ID généré aléatoirement pour ce visiteur.
{:ok, anonymous_variation} = Client.get_variation(client, anonymous_visitor_code, feature_key)
# 2. Après l'authentification du visiteur
# On suppose que `userId` est le code visiteur du visiteur authentifié.
:ok = Client.add_data(client, anonymous_visitor_code, CustomData.new!(mapping_index, [user_id]))
:ok = Client.flush_instant(client, anonymous_visitor_code)
# Indiquer que `userId` est un identifiant unique.
:ok = Client.add_data(client, user_id, UniqueIdentifier.new!(true))
# 3. Après l'autorisation du visiteur
# Récupérer la variation pour le `userId`, qui correspondra à la variation du code visiteur anonyme.
{:ok, user_variation} = Client.get_variation(client, user_id, feature_key)
is_same_variation = user_variation.key == anonymous_variation.key # true
# `userId` et `anonymousVisitorCode` sont désormais liés et peuvent être suivis comme un seul visiteur.
:ok = Client.track_conversion(client, user_id, 123)
# De plus, les visiteurs liés partagent toutes les données distantes précédemment suivies et récupérées.
:ok = Client.get_remote_visitor_data(client, user_id)
Client.get_visitor_code est utilisé. Après la connexion de l’utilisateur, le visiteur anonyme est associé à l’ID utilisateur et utilisé comme identifiant unique pour le visiteur.
Journalisation
Le SDK génère des logs pour refléter les différents processus et problèmes internes.
Niveaux de log
Le SDK prend en charge la limitation de la journalisation par niveau de log.
alias Kameleoon.Logger
# Le niveau de log `:none` désactive la journalisation.
:ok = Logger.set_log_level(:none)
# Le niveau de log `:error` permet uniquement de journaliser les problèmes susceptibles d'affecter le comportement principal du SDK.
:ok = Logger.set_log_level(:error)
# Le niveau de log `:warning` permet de journaliser les problèmes nécessitant une attention.
# Il étend le niveau de log `:error`.
# Le niveau de log `:warning` est le niveau par défaut.
:ok = Logger.set_log_level(:warning)
# Le niveau de log `:info` permet de journaliser des informations générales sur les processus internes du SDK.
# Il étend le niveau de log `:warning`.
:ok = Logger.set_log_level(:info)
# Le niveau `:debug` consigne des détails supplémentaires sur les processus internes du SDK.
:ok = Logger.set_log_level(:debug)
Gestion personnalisée des logs
Le SDK écrit ses logs sur la sortie console par défaut. Ce comportement peut être remplacé.
La limitation de la journalisation par niveau de log est effectuée indépendamment de la logique de gestion des logs.
defmodule MyKameleoonLogger do
@behaviour Kameleoon.Logger
require Logger
@impl true
def log(level, message) do
Logger.log(level, message)
end
end
# Le filtrage par niveau de log est appliqué séparément de la logique de gestion des logs.
# Le logger personnalisé n'acceptera que les logs qui correspondent ou dépassent le niveau de log spécifié.
:ok = Kameleoon.Logger.set_log_level(:debug)
:ok = Kameleoon.Logger.set_logger(MyKameleoonLogger)
Référence
Voici la documentation complète de référence pour le SDK Elixir.
Initialisation
create()
Pour utiliser le SDK, créez un %Kameleoon.Client\{\} avec Kameleoon.ClientFactory.create. Par défaut, create lit /etc/kameleoon/client-elixir.conf. Vous pouvez également fournir soit une structure %Kameleoon.ClientConfig\{\} via config:, soit un chemin de fichier de configuration personnalisé via config_path:.
alias Kameleoon.ClientConfig
alias Kameleoon.ClientFactory
config = %ClientConfig{
client_id: "<client-id>",
client_secret: "<client-secret>",
refresh_interval_minutes: 60,
session_duration_minutes: 30,
default_timeout_millis: 10_000,
tracking_interval_millis: 1_000,
environment: "development",
top_level_domain: ".example.com",
proxy_host: "http://192.168.0.25:8080",
network_domain: "example.com"
}
{:ok, client} = ClientFactory.create(site_code, config: config)
Arguments
| Nom | Type | Description |
|---|
site_code (obligatoire) | String.t() | Clé unique du projet Kameleoon utilisée par le SDK. |
config (obligatoire) | Kameleoon.ClientConfig.t() | Structure de configuration du SDK. |
alias Kameleoon.ClientFactory
{:ok, client} = ClientFactory.create("a8st4f59bj", config_path: "/etc/kameleoon/client-elixir.conf")
Arguments
| Nom | Type | Description |
|---|
site_code (obligatoire) | String.t() | Clé unique du projet Kameleoon utilisée par le SDK. |
config_path (obligatoire) | String.t() | Chemin vers le fichier de configuration. |
Valeur retournée
| Type | Description | |
|---|
| `{:ok, Kameleoon.Client.t()} | {:error, Kameleoon.Error.t()}` | Une instance du client en cas de succès, sinon une erreur d’initialisation. |
Erreurs
| Type | Description |
|---|
ConfigCredentialsInvalid | Les identifiants du SDK sont manquants. |
SiteCodeIsEmpty | Le site code fourni est vide. |
initialize()
Attend que le client Kameleoon soit initialisé, en utilisant soit la valeur configurée default_timeout_millis, soit un timeout fourni. Cette méthode garantit que le client est entièrement initialisé avant d’effectuer toute autre opération.
alias Kameleoon.Client
# Initialise le client en utilisant le délai d'attente par défaut configuré
:ok = Client.initialize(client)
# Initialise le client avec un délai d'attente personnalisé de 5 secondes
:ok = Client.initialize(client, timeout: 5_000)
Arguments
| Nom | Type | Description |
|---|
timeout (optionnel) | non_neg_integer() | Temps maximal d’attente pour l’initialisation, en millisecondes. |
Valeur retournée
| Type | Description | |
|---|
| `:ok | {:error, Kameleoon.Error.t()}` | Indique si l’initialisation s’est terminée avec succès ou si une erreur s’est produite. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
is_ready()
Vérifie si le client a été initialisé.
{:ok, ready?} = Kameleoon.Client.is_ready?(client)
if ready? do
# Le client est prêt
end
Valeur retournée
| Type | Description | |
|---|
| `{:ok, boolean()} | {:error, Kameleoon.Error.t()}` | \{:ok, true\} si le client est prêt à être utilisé, \{:ok, false\} s’il n’est pas prêt, sinon une erreur. |
forget()
Supprime le client SDK mis en cache associé au site_code spécifié.
alias Kameleoon.ClientFactory
# Supprime le client mis en cache pour le site code donné
:ok = ClientFactory.forget("a8st4f59bj")
# Supprime le client mis en cache pour le site code et l'environnement donnés
:ok = ClientFactory.forget("a8st4f59bj", environment: "production")
Arguments
| Nom | Type | Description |
|---|
site_code (obligatoire) | String.t() | Identifiant unique du projet Kameleoon. |
environment (optionnel) | String.t() | Clé d’environnement associée au client mis en cache. |
Valeur retournée
| Type | Description | |
|---|
| `:ok | {:error, Kameleoon.Error.t()}` | Indique si le client mis en cache a été correctement supprimé ou si une erreur s’est produite. |
Feature flags et variations
is_feature_active()
- 📨 Envoie des données de tracking à Kameleoon (selon l’option
track)
Détermine si un feature flag est actif pour un utilisateur donné.
Si le visiteur n’a pas encore été évalué pour ce feature flag, le SDK évalue les règles de ciblage et renvoie le résultat. Si le visiteur dispose déjà d’une évaluation stockée pour le feature, le SDK réutilise le résultat existant pour garantir la cohérence.
Kameleoon utilise le tracking pour compter les sessions et les visiteurs lorsque vous appelez certaines méthodes, telles que Client.is_feature_active?, Client.get_variation ou Client.get_variations.Utilisez la valeur par défaut true pour le paramètre track lorsque vous exposez les visiteurs à une variation et devez les compter. Définissez le paramètre track sur false uniquement si vous appelez ces méthodes avant d’exposer les visiteurs.Par exemple, si vous appelez Client.get_variations pour récupérer toutes les variations avant d’exposer les visiteurs, définissez le paramètre track sur false. Ce paramètre empêche Kameleoon de comptabiliser prématurément une session. Vous pouvez ensuite déclencher le tracking ultérieurement lorsque vous exposez explicitement le visiteur.Kameleoon envoie les données de tracking chaque seconde par défaut. Vous pouvez configurer cet intervalle jusqu’à cinq secondes à l’aide de l’option de configuration de l’intervalle de tracking. Kameleoon regroupe les événements de tracking dans une seule session tant que l’intervalle entre les événements est inférieur à 30 minutes. Si plus de 30 minutes s’écoulent entre les événements de tracking, Kameleoon comptabilise les événements comme des sessions distinctes. Une visite apparaît dans vos rapports 30 minutes après le dernier événement enregistré dans la session.
La méthode Client.is_feature_active? évalue la variante servie, et non l’état du master flag. Si vous excluez des règles, la méthode utilise l’état par défaut Then, for everyone else serve. Si vous sélectionnez Off pour cet état par défaut, la méthode renvoie toujours false même lorsque le master feature flag est sur On.
alias Kameleoon.Client
feature_key = "new_checkout"
# Évalue le feature flag et envoie les données de tracking (comportement par défaut)
{:ok, active?} = Client.is_feature_active?(client, visitor_code, feature_key)
# Évalue le feature flag sans envoyer de données de tracking
{:ok, active_without_tracking?} =
Client.is_feature_active?(client, visitor_code, feature_key, track: false)
Arguments
| Nom | Type | Description | Par défaut |
|---|
visitor_code (obligatoire) | String.t() | Identifiant unique de l’utilisateur. | |
feature_key (obligatoire) | String.t() | Clé du feature à évaluer pour l’utilisateur. | |
track (optionnel) | boolean() | Active ou désactive le suivi de l’évaluation du feature. | true |
Valeur retournée
| Type | Description | |
|---|
| `{:ok, boolean()} | {:error, Kameleoon.Error.t()}` | Indique si le feature flag est actif pour le visitor_code spécifié, ou renvoie une erreur. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
FeatureNotFound | Exception indiquant que la clé du feature demandée est introuvable dans la configuration interne du SDK. Cela signifie généralement que le feature flag n’est pas activé dans l’application Kameleoon (mais que le code implémentant le feature est déjà déployé dans l’application). |
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
get_variation()
- 📨 Envoie des données de tracking à Kameleoon (selon le paramètre
track)
Récupère la Variation attribuée à un visiteur donné pour un feature flag spécifique.
Cette méthode prend un visitor_code et une feature_key comme arguments obligatoires. L’argument track est optionnel et vaut true par défaut.
Elle renvoie la Variation attribuée au visiteur. Si le visiteur n’est associé à aucune règle de feature flag, la méthode renvoie la Variation par défaut pour le feature flag donné.
Assurez-vous qu’une gestion appropriée des erreurs est implémentée dans votre code pour gérer les exceptions potentielles.
La variation par défaut désigne la variation attribuée à un visiteur lorsqu’il ne correspond à aucune règle de livraison prédéfinie pour un feature flag. En d’autres termes, il s’agit de la variation de repli appliquée à tous les utilisateurs qui ne sont pas ciblés par des règles spécifiques. Elle est représentée comme la variation dans la section « Then, for everyone else… » d’une interface de gestion.
alias Kameleoon.Client
feature_key = "new_checkout"
# Récupère la variation attribuée au visiteur (avec le tracking activé par défaut)
{:ok, variation} = Client.get_variation(client, visitor_code, feature_key)
# Récupère la variation sans envoyer de données de tracking
{:ok, variation_without_tracking} =
Client.get_variation(client, visitor_code, feature_key, track: false)
Arguments
| Nom | Type | Description | Par défaut |
|---|
| visitor_code (obligatoire) | String.t() | Identifiant unique du visiteur. | |
| feature_key (obligatoire) | String.t() | Clé du feature que vous souhaitez exposer à un visiteur. | |
| track (optionnel) | boolean() | Paramètre optionnel pour activer ou désactiver le suivi de l’évaluation du feature. | true |
Valeur retournée
| Type | Description |
|---|
\{:ok, Kameleoon.Types.Variation.t()\} | \{:error, Kameleoon.Error.t()\} | Une Variation attribuée à un visiteur donné pour un feature flag spécifique en cas de succès, sinon une erreur. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
FeatureNotFound | Exception indiquant que la clé du feature demandée est introuvable dans la configuration interne du SDK. Cela signifie généralement que le feature flag n’est pas activé dans l’application Kameleoon (mais que le code implémentant le feature est déjà déployé dans l’application). |
FeatureEnvironmentDisabled | Exception indiquant que le feature flag est désactivé pour l’environnement actuel du visiteur (par exemple, production, staging ou development). |
FeatureEvaluationBlocked | Exception indiquant que l’évaluation du feature est bloquée. La raison est décrite dans le message d’erreur. Cela se produit généralement en raison de restrictions RGPD lorsque le visiteur n’a pas fourni de consentement légal. |
get_variations()
- 📨 Envoie des données de tracking à Kameleoon (selon le paramètre
track)
Récupère une map d’objets Variation attribués à un visiteur donné pour tous les feature flags.
Cette méthode itère sur tous les feature flags disponibles et renvoie la Variation attribuée pour chaque flag associé au visiteur spécifié. Elle prend visitor_code comme argument obligatoire, tandis que only_active et track sont optionnels.
- Si
only_active est défini sur true, la méthode Client.get_variations renverra les variations des feature flags à condition que l’utilisateur ne soit pas bucketé avec la variation off.
- Le paramètre
track contrôle si la méthode suivra ou non les attributions de variations. Par défaut, il est défini sur true. S’il est défini sur false, le tracking sera désactivé.
La map retournée se compose des clés des feature flags en tant que clés et de leurs Variation correspondantes en tant que valeurs. Si aucune variation n’est attribuée pour un feature flag, la méthode renvoie la Variation par défaut pour ce flag.
Une gestion appropriée des erreurs doit être implémentée pour gérer les exceptions potentielles.
La variation par défaut désigne la variation attribuée à un visiteur lorsqu’il ne correspond à aucune règle de livraison prédéfinie pour un feature flag. En d’autres termes, il s’agit de la variation de repli appliquée à tous les utilisateurs qui ne sont pas ciblés par des règles spécifiques. Elle est représentée comme la variation dans la section « Then, for everyone else… » d’une interface de gestion.
alias Kameleoon.Client
# Récupère toutes les variations attribuées au visiteur (avec les options par défaut)
{:ok, variations} = Client.get_variations(client, visitor_code)
# Récupère uniquement les variations actives pour le visiteur
{:ok, only_active_variations} = Client.get_variations(client, visitor_code, only_active: true)
# Récupère les variations sans envoyer de données de tracking
{:ok, variations_without_tracking} = Client.get_variations(client, visitor_code, track: false)
Arguments
| Nom | Type | Description | Par défaut |
|---|
| visitor_code (obligatoire) | String.t() | Identifiant unique du visiteur. | |
| only_active (optionnel) | boolean() | Paramètre optionnel indiquant s’il faut renvoyer les variations pour les feature flags actifs (true) ou tous (false). | false |
| track (optionnel) | boolean() | Paramètre optionnel pour activer ou désactiver le suivi de l’évaluation du feature. | true |
Valeur retournée
| Type | Description |
|---|
\{:ok, %\{String.t() => Kameleoon.Types.Variation.t()\}\} | \{:error, Kameleoon.Error.t()\} | Map contenant les objets Variation attribués des feature flags en utilisant les clés des features correspondants en cas de succès, sinon une erreur. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
set_forced_variation()
La méthode vous permet d’attribuer par programmation une Variation spécifique à un utilisateur, en contournant le processus d’évaluation standard. Cela est particulièrement précieux pour les expériences contrôlées où la logique d’évaluation habituelle n’est pas requise ou doit être ignorée. Cela peut également être utile dans des scénarios tels que le débogage ou les tests personnalisés.
Lorsqu’une variation forcée est définie, elle remplace la logique d’évaluation en temps réel de Kameleoon. Les processus tels que la segmentation, les conditions de ciblage et les calculs algorithmiques sont ignorés. Pour préserver la segmentation et les conditions de ciblage pendant une expérience, définissez plutôt force_targeting=false.
Les variations simulées ont toujours la priorité dans l’ordre d’exécution. Si un calcul de variation simulée est déclenché, il sera entièrement traité et terminé en premier.
Il est important de distinguer les variations forcées des variations simulées :
- Variations forcées : Sont spécifiques à une expérience individuelle.
- Variations simulées : Affectent le résultat global du feature flag.
alias Kameleoon.Client
experiment_id = 202_387
# Force le visiteur dans "variation_2" pour l'expérience donnée
:ok = Client.set_forced_variation(client, visitor_code, experiment_id, "variation_2")
# Supprime toute variation précédemment forcée pour le visiteur dans cette expérience
:ok = Client.set_forced_variation(client, visitor_code, experiment_id, nil)
# Force le visiteur dans "variation_2" avec des options personnalisées.
# Dans ce cas, les règles de ciblage sont respectées (force_targeting = false).
:ok =
Client.set_forced_variation(
client,
visitor_code,
experiment_id,
"variation_2",
force_targeting: false
)
Arguments
| Nom | Type | Description | Par défaut |
|---|
| visitor_code (obligatoire) | String.t() | Identifiant unique du visiteur. | |
| experiment_id (obligatoire) | non_neg_integer() | ID d’expérience qui sera ciblé et sélectionné lors du processus d’évaluation. | |
| variation_key (obligatoire) | String.t() | nil | Clé de variation correspondant à une Variation qui doit être forcée comme valeur retournée pour l’expérience. Si la valeur est nil, la variation forcée sera réinitialisée. | |
| force_targeting (optionnel) | boolean() | Indique si le ciblage de l’expérience doit être forcé et ignoré (true) ou appliqué comme dans le processus d’évaluation standard (false). | true |
Valeur retournée
| Type | Description | |
|---|
| `:ok | {:error, Kameleoon.Error.t()}` | Indique si la variation forcée a été définie avec succès ou si une erreur s’est produite. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
FeatureExperimentNotFound | Exception indiquant que l’ID d’expérience demandé est introuvable dans la configuration interne du SDK. C’est généralement normal et signifie que l’expérience correspondante de la règle n’a pas encore été activée du côté de Kameleoon. |
FeatureVariationNotFound | Exception indiquant que la clé (id) de variation demandée est introuvable dans la configuration interne du SDK. C’est généralement normal et signifie que l’expérience correspondante de la variation n’a pas encore été activée du côté de Kameleoon. |
evaluate_audiences()
- 📨 Envoie des données de tracking à Kameleoon
Cette méthode évalue les visiteurs par rapport à tous les segments Audiences Explorer disponibles et suit ceux qui correspondent.
Client.evaluate_audiences doit être appelée après que toutes les données pertinentes du visiteur ont été définies ou mises à jour, et juste avant d’obtenir une variation de feature ou de vérifier un feature flag. Cette approche garantit que le visiteur est évalué par rapport aux données les plus récentes disponibles, permettant une attribution d’audience précise basée sur tous les critères.
Après avoir appelé cette méthode, vous pouvez effectuer une analyse détaillée des performances des segments dans Audiences Explorer.
:ok = Kameleoon.Client.evaluate_audiences(client, visitor_code)
Arguments
| Nom | Type | Description |
|---|
| visitor_code (obligatoire) | String.t() | Identifiant unique du visiteur. |
Valeur retournée
| Type | Description | |
|---|
| `:ok | {:error, Kameleoon.Error.t()}` | Indique si l’évaluation de l’audience a réussi ou si une erreur s’est produite. |
Erreurs
| Type | Description |
|---|
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
get_datafile()
Renvoie la configuration actuelle du SDK sous forme d’objet DataFile.
{:ok, datafile} = Kameleoon.Client.get_datafile(client)
Valeur retournée
| Type | Description |
|---|
\{:ok, Kameleoon.Types.DataFile.t()\} | \{:error, Kameleoon.Error.t()\} | Le DataFile contenant la configuration du SDK en cas de succès, sinon une erreur. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
Données du visiteur
get_visitor_code()
Utilisez get_visitor_code() pour obtenir le visitor_code Kameleoon du visiteur actuel. La méthode fonctionne avec n’importe quel store de cookies qui implémente le behaviour Kameleoon.CookieAccessor.
La logique d’implémentation est la suivante :
- Le SDK vérifie si un cookie
kameleoonVisitorCode est déjà disponible via l’accessor fourni.
- Si le cookie est absent, le SDK utilise
default_visitor_code lorsque vous en fournissez un.
- Sinon, le SDK génère un nouveau visitor code et le stocke via l’accessor.
Pour plus d’informations, consultez Expérimentation hybride.
Si vous fournissez votre propre visitor_code, son unicité doit être garantie de votre côté. Notez également que la longueur de visitor_code est limitée à 255 caractères.
La méthode Client.get_visitor_code vous permet de définir des variations simulées pour un visiteur. Lorsque les cookies (d’une requête ou d’un document) contiennent la clé kameleoonSimulationFFData, le processus d’évaluation standard est contourné. Au lieu de cela, la méthode renvoie directement une Variation basée sur les données fournies.Vous pouvez appliquer les simulations de deux manières :
- Automatiquement (recommandé) : Si vous utilisez Kameleoon Web Experimentation ou le SDK en mode hybride, le cookie est créé automatiquement lors de la simulation de l’affichage d’une variante via le Simulation Panel.
- Manuellement : Définissez manuellement le cookie
kameleoonSimulationFFData.
Il est important de distinguer les variations simulées des variations forcées :
- Variations simulées : Affectent le résultat global du feature flag.
- Variations forcées : Sont spécifiques à une expérience individuelle.
⚙️ Configuration manuelleVeuillez vous assurer que le cookie kameleoonSimulationFFData suit ce format :
kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}} : Simule la variation avec varId de l’expérience expId pour la featureKey donnée.kameleoonSimulationFFData={"featureKey":{"expId":0}} : Simule la variation par défaut (définie dans la section Then, for everyone else in Production, serve) pour la featureKey donnée.
⚠️ Pour garantir le bon fonctionnement, la valeur du cookie doit être encodée en tant que composant URI à l’aide d’une méthode telle que encodeURIComponent. defmodule MemoryCookies do
@behaviour Kameleoon.CookieAccessor
@impl true
def get(cookies, key), do: Map.get(cookies, key)
@impl true
def set(cookies, key, value, _max_age, _top_level_domain) do
Map.put(cookies, key, value)
end
end
cookies = {MemoryCookies, %{}}
# Génère ou récupère un visitor code en utilisant une valeur générée automatiquement.
{:ok, visitor_code, cookies} = Kameleoon.Client.get_visitor_code(client, cookies)
# Génère ou récupère un visitor code en utilisant un ID utilisateur prédéfini.
{:ok, visitor_code, cookies} = Kameleoon.Client.get_visitor_code(client, {MemoryCookies, cookies}, "user_id")
defmodule PlugConnCookies do
@behaviour Kameleoon.CookieAccessor
@impl true
def get(conn, key), do: conn.req_cookies[key]
@impl true
def set(conn, key, value, max_age, top_level_domain) do
opts = [path: "/", max_age: max_age]
opts = if top_level_domain, do: Keyword.put(opts, :domain, top_level_domain), else: opts
Plug.Conn.put_resp_cookie(conn, key, value, opts)
end
end
def get_visitor_code(conn, client) do
cookies = {PlugConnCookies, conn}
with {:ok, visitor_code, conn} <- Kameleoon.Client.get_visitor_code(client, cookies) do
{:ok, visitor_code, conn}
end
end
Arguments
| Nom | Type | Description | |
|---|
cookies (obligatoire) | \{module(), term()\} | Module accessor de cookies et état spécifique au framework utilisés pour lire et stocker le cookie du visiteur. | |
default_visitor_code (optionnel) | `String.t() | nil` | Visitor code à utiliser lorsqu’aucun cookie n’est présent. |
get et set. get lit une valeur de cookie depuis l’état de l’accessor, et set renvoie l’état mis à jour après avoir reçu key, value, max_age et top_level_domain.
Valeur retournée
| Type | Description | |
|---|
| `{:ok, String.t(), term()} | {:error, Kameleoon.Error.t()}` | Chaîne représentant un visitor code unique utilisé dans le SDK en cas de succès, sinon une erreur. |
add_data()
La méthode Client.add_data ajoute des données de ciblage au stockage afin que d’autres méthodes puissent les utiliser pour décider s’il faut cibler ou non le visiteur actuel.
La méthode Client.add_data ne renvoie aucune valeur et n’interagit pas avec les serveurs back-end de Kameleoon par elle-même. Au lieu de cela, toutes les données déclarées sont enregistrées pour une transmission ultérieure via la méthode Client.flush. Cette approche réduit le nombre d’appels au serveur, car les données sont généralement regroupées en un seul appel au serveur déclenché par Client.flush.
La méthode Client.track_conversion envoie également toutes les données précédemment associées, tout comme Client.flush. Il en va de même pour les méthodes Client.get_variation et Client.get_variations si une règle d’expérimentation est déclenchée.
Chaque visiteur ne peut avoir qu’une seule instance de données associées pour la plupart des types de données. Cependant, CustomData est une exception. Les visiteurs peuvent avoir une instance de CustomData associée par index. alias Kameleoon.Client
alias Kameleoon.Data.Browser
alias Kameleoon.Data.PageView
alias Kameleoon.Data.UserAgent
:ok = Client.add_data(client, visitor_code, Browser.new!(:chrome, version: 123.0))
:ok =
Client.add_data(client, visitor_code, [
PageView.new!("https://example.com/pricing", title: "Pricing", referrers: [3]),
UserAgent.new!("Mozilla/5.0")
])
:ok =
Client.add_data(
client,
visitor_code,
PageView.new!("https://example.com/checkout", title: "Checkout"),
track: false
)
Arguments
| Nom | Type | Description | Valeur par défaut |
|---|
| visitor_code (obligatoire) | String.t() | Identifiant unique du visiteur. | |
| data (obligatoire) | struct() | [struct()] | Collection de types de données Kameleoon. | |
| track (optionnel) | boolean() | Spécifie si les données ajoutées sont éligibles au tracking. Lorsqu’elles sont définies sur false, les données sont stockées localement et utilisées uniquement pour l’évaluation du ciblage ; elles ne sont pas envoyées à l’API Data de Kameleoon. | true |
Valeur retournée
| Type | Description | |
|---|
| `:ok | {:error, Kameleoon.Error.t()}` | Indique si les données ont été ajoutées avec succès ou si une erreur s’est produite. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
flush()
- 📨 Envoie des données de tracking à Kameleoon
La méthode flush() agrège toutes les données Kameleoon associées à un visiteur et envoie une requête de tracking au serveur. Cette requête inclut toutes les données précédemment ajoutées via la méthode add_data qui n’ont pas encore été transmises par d’autres mécanismes de tracking (voir les méthodes référencées pour plus de détails). L’opération flush() est non bloquante, car l’appel au serveur est effectué de manière asynchrone.
Cette méthode offre un contrôle sur le moment où les données liées à un visitor_code spécifique sont transmises. Par exemple, si add_data() est appelée plusieurs fois, l’envoi d’une requête après chaque invocation serait inefficace. Au lieu de cela, vous pouvez regrouper ces mises à jour et appeler flush() une seule fois pour envoyer toutes les données accumulées en une seule requête.
La méthode flush() utilise le visitor_code fourni comme identifiant unique du visiteur.
flush() — Met en file d’attente une opération de flush selon l’intervalle de tracking configuré.flush_instant() — Envoie immédiatement les données de tracking sans attendre l’intervalle.
# Met en file d'attente une opération de flush pour le visitor_code donné.
# Les données seront envoyées selon l'intervalle de tracking configuré.
:ok = Kameleoon.Client.flush(client, visitor_code)
# Envoie immédiatement toutes les données de tracking en attente pour le visitor_code donné.
:ok = Kameleoon.Client.flush_instant(client, visitor_code)
Arguments
| Nom | Type | Description |
|---|
visitor_code (obligatoire) | String.t() | Identifiant unique du visiteur. |
Valeur retournée
| Type | Description | |
|---|
| `:ok | {:error, Kameleoon.Error.t()}` | Indique si l’opération a été planifiée ou exécutée avec succès, ou si une erreur s’est produite. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
get_remote_data()
La méthode get_remote_data() vous permet de récupérer des données distantes stockées sur les serveurs Kameleoon pour la key spécifiée. Dans la plupart des configurations, ces données sont écrites via l’API Data de Kameleoon et peuvent ensuite être récupérées par votre service Elixir chaque fois que vous avez besoin d’un contexte applicatif supplémentaire.
Cette méthode est utile lorsque vous souhaitez conserver des informations structurées sur l’infrastructure distante de Kameleoon et les réutiliser depuis votre back-end sans maintenir un mécanisme de récupération séparé.
{:ok, data} = Kameleoon.Client.get_remote_data(client, "test-key")
Arguments
| Nom | Type | Description |
|---|
key (obligatoire) | String.t() | Clé associée aux données distantes que vous souhaitez récupérer. |
Valeur retournée
| Type | Description | |
|---|
| `{:ok, String.t()} | {:error, Kameleoon.Error.t()}` | Charge utile associée à la key spécifiée en cas de succès, sinon une erreur. Dans la plupart des cas, la charge utile est sérialisée au format JSON sous forme de chaîne. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
Network | Renvoyé lorsque la requête de données distantes échoue ou que le serveur répond avec un code de statut non réussi. |
get_remote_visitor_data()
get_remote_visitor_data() récupère les données de visite Kameleoon pour le visitor_code fourni. La méthode ajoute les données au stockage local du visiteur afin que d’autres méthodes du SDK puissent les utiliser pour les décisions de ciblage.
Les données obtenues via cette méthode sont particulièrement utiles lorsque vous souhaitez :
- utiliser des données collectées depuis d’autres appareils.
- accéder à l’historique d’un visiteur, comme les pages précédemment consultées lors de visites passées.
- utiliser des données qui ne sont disponibles que côté client, telles que les variables de datalayer et les conversions d’objectifs front-end.
Lisez cet article pour mieux comprendre les cas d’utilisation possibles.
alias Kameleoon.Client
alias Kameleoon.Types.RemoteVisitorDataFilter
# Récupérer les données distantes du visiteur sans aucun filtre.
# Cela renverra toutes les données disponibles pour le visiteur donné.
:ok = Client.get_remote_visitor_data(client, visitor_code)
# Créer un filtre pour limiter les données renvoyées.
filter = %RemoteVisitorDataFilter{
previous_visit_amount: 5,
conversions: true,
page_views: true
}
# Récupérer les données distantes du visiteur en utilisant le filtre spécifié.
# Cela ne renverra que les données correspondant aux critères du filtre.
:ok = Client.get_remote_visitor_data(client, visitor_code, filter: filter)
Arguments
| Nom | Type | Description | Par défaut | |
|---|
visitor_code (obligatoire) | String.t() | Visitor code dont les données doivent être récupérées. | | |
filter (optionnel) | `Kameleoon.Types.RemoteVisitorDataFilter.t() | nil` | Filtre décrivant quelles données distantes du visiteur doivent être récupérées. | %RemoteVisitorDataFilter\{\} |
Valeur retournée
| Type | Description | |
|---|
| `:ok | {:error, Kameleoon.Error.t()}` | Renvoie avec succès lorsque les données sont récupérées et ajoutées localement, sinon une erreur. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
Network | Renvoyé lorsque la requête de données distantes du visiteur échoue, ne peut pas être analysée, ou que le serveur répond avec un code de statut non réussi. |
Utilisation des paramètres dans get_remote_visitor_data()
La méthode get_remote_visitor_data() vous permet de contrôler quelles données sont récupérées pour un visiteur. La même approche de filtrage fonctionne pour les objectifs, les expériences, les variations et autres données du visiteur.
Par exemple, si vous souhaitez cibler les utilisateurs qui ont converti sur un objectif lors de leurs cinq dernières visites, vous pouvez définir previous_visit_amount sur 5 et conversions sur true.
La flexibilité illustrée dans cet exemple ne se limite pas aux données d’objectifs. Vous pouvez utiliser le filtre pour récupérer de nombreux comportements de visiteurs différents et les rendre disponibles pour la logique de ciblage et de reporting dans votre application Elixir.
Champs de RemoteVisitorDataFilter
| Nom | Type | Description | Par défaut |
|---|
previous_visit_amount | non_neg_integer() | Nombre de visites précédentes à partir desquelles récupérer les données. | 1 |
current_visit | boolean() | Si true, les données de la visite actuelle seront récupérées. | true |
custom_data | boolean() | Si true, les données personnalisées seront récupérées. | true |
visitor_code | boolean() | Si true, le visitor code le plus récent sera réutilisé. | true |
page_views | boolean() | Si true, les données de page vue seront récupérées. | false |
geolocation | boolean() | Si true, les données de géolocalisation seront récupérées. | false |
device | boolean() | Si true, les données d’appareil seront récupérées. | false |
browser | boolean() | Si true, les données de navigateur seront récupérées. | false |
operating_system | boolean() | Si true, les données du système d’exploitation seront récupérées. | false |
conversions | boolean() | Si true, les données de conversion seront récupérées. | false |
experiments | boolean() | Si true, les données d’expérience seront récupérées. | false |
kcs | boolean() | Si true, les données du Kameleoon Conversion Score seront récupérées. | false |
personalizations | boolean() | Si true, les données de personnalisation seront récupérées. | false |
cbs | boolean() | Si true, les données du Contextual Bandit score seront récupérées. | false |
get_visitor_warehouse_audience()
Cette méthode récupère les données d’audience associées à un visiteur dans votre intégration warehouse en utilisant le visitor_code spécifié et, éventuellement, une warehouse_key. La warehouse_key est généralement votre ID utilisateur interne. Le paramètre custom_data_index correspond à la donnée personnalisée Kameleoon que Kameleoon utilise pour cibler vos visiteurs.
Lorsque l’appel réussit, le SDK convertit la liste d’audiences renvoyée en CustomData, l’ajoute au visiteur localement et la rend disponible à des fins de ciblage. Pour plus de contexte, consultez la documentation sur le ciblage warehouse.
alias Kameleoon.Client
# Récupérer les données d'audience d'un visiteur en utilisant uniquement le visitor_code.
:ok = Client.get_visitor_warehouse_audience(client, visitor_code, 98)
# Récupérer les données d'audience d'un visiteur en utilisant à la fois visitor_code et warehouse_key.
# Utile lorsque votre warehouse utilise un identifiant différent du visitor_code.
:ok = Client.get_visitor_warehouse_audience(client, visitor_code, 98, warehouse_key: "internal-user-id")
Arguments
| Nom | Type | Description | Par défaut | |
|---|
visitor_code (obligatoire) | String.t() | Visiteur dont les audiences warehouse doivent être récupérées. | | |
custom_data_index (obligatoire) | non_neg_integer() | Index de données personnalisées configuré dans Kameleoon pour le ciblage d’audience warehouse. | | |
warehouse_key (optionnel) | `String.t() | nil` | Clé warehouse externe, généralement votre ID utilisateur interne. | visitor_code |
Valeur retournée
| Type | Description | |
|---|
| `:ok | {:error, Kameleoon.Error.t()}` | Succès lorsque les données d’audience warehouse sont récupérées et stockées localement en tant que CustomData. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
Network | Renvoyé lorsque la requête d’audience warehouse échoue, ne peut pas être analysée, ou que le serveur répond avec un code de statut non réussi. |
set_legal_consent()
Vous devez utiliser cette méthode pour spécifier si le visiteur a donné son consentement légal à l’utilisation de ses données personnelles. Définir legal_consent sur false limite les types de données pouvant être inclus dans les requêtes de tracking. Cela vous aide à respecter les exigences légales et réglementaires tout en gérant les données des visiteurs de manière responsable. Pour plus d’informations, consultez la politique de gestion du consentement.
Le SDK Elixir met à jour les cookies du visiteur via l’adaptateur Kameleoon.CookieAccessor requis et renvoie l’état mis à jour de l’adaptateur.
cookies = {PlugConnCookies, conn}
# Définir le consentement et mettre à jour les cookies.
{:ok, conn} = Kameleoon.Client.set_legal_consent(client, visitor_code, true, cookies)
Arguments
| Nom | Type | Description | Par défaut |
|---|
visitor_code (obligatoire) | String.t() | Identifiant unique de l’utilisateur. | |
consent (obligatoire) | boolean() | true indique que le visiteur a donné son consentement légal, false indique que le visiteur n’a jamais fourni ou a retiré son consentement légal. | |
cookies (obligatoire) | \{module(), term()\} | Module accessor de cookies et état spécifique au framework utilisés pour mettre à jour les cookies. | |
Valeur retournée
| Type | Description | |
|---|
| `{:ok, term()} | {:error, Kameleoon.Error.t()}` | Renvoie l’état mis à jour du cookie lorsque l’état du consentement du visiteur a été mis à jour avec succès, sinon une erreur. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
Comportement de révocation du consentement
Lorsque vous appelez Client.set_legal_consent avec legal_consent=false, le SDK ne supprime pas le cookie kameleoonVisitorCode. Au lieu de cela, il cesse de prolonger la date d’expiration du cookie, permettant au cookie de persister jusqu’à son expiration naturelle.
Si vos exigences de conformité imposent la suppression immédiate du fichier cookie lors du retrait du consentement, vous devez le supprimer manuellement en utilisant les méthodes natives de gestion des cookies de votre framework. Le SDK ne supprimera pas le fichier automatiquement.
Objectifs et analyses tierces
track_conversion()
- 📨 Envoie des données de tracking à Kameleoon
Utilisez cette méthode pour suivre une conversion pour un objectif et un utilisateur spécifiques. Cette méthode requiert visitor_code et goal_id. De plus, cette méthode accepte également des arguments optionnels revenue, negative et metadata. Le visitor_code est généralement identique à celui utilisé lors du déclenchement de l’expérience.
Cette méthode est non bloquante car l’appel au serveur est effectué de manière asynchrone.
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
# Suivre un objectif.
:ok = Client.track_conversion(client, visitor_code, goal_id)
# Suivre un objectif avec un revenu.
:ok = Client.track_conversion(client, visitor_code, goal_id, revenue: 100.0)
# Suivre un objectif avec un revenu négatif.
:ok = Client.track_conversion(client, visitor_code, goal_id, revenue: 100.0, negative: true)
# Suivre un objectif avec des métadonnées personnalisées.
:ok =
Client.track_conversion(
client,
visitor_code,
goal_id,
metadata: [CustomData.new!(4, ["true"])]
)
Arguments
| Nom | Type | Description | Par défaut |
|---|
visitor_code (obligatoire) | String.t() | Identifiant unique du visiteur. | |
goal_id (obligatoire) | non_neg_integer() | ID de l’objectif. | |
revenue (optionnel) | number() | nil | Revenu de la conversion. | 0 |
negative (optionnel) | boolean() | Définit si le revenu est positif ou négatif. | false |
metadata (optionnel) | [Kameleoon.Data.CustomData.t()] | Métadonnées de la conversion. Doivent être définies au préalable dans l’application Kameleoon. | [] |
Les valeurs des métadonnées sont accessibles via les exports de données brutes et la page de résultats.Si le paramètre metadata est fourni, Kameleoon utilisera ces valeurs spécifiées pour la conversion en cours au lieu de ce qui a été précédemment collecté en utilisant la méthode Client.add_data. Si le paramètre est omis, Kameleoon utilisera les dernières valeurs suivies pour ces CustomData avant la conversion et au cours de la même visite.Kameleoon ne prendra en compte que les valeurs de métadonnées explicitement passées en tant que paramètres à la méthode Client.track_conversion.Dans l’exemple ci-dessous, Kameleoon associera la conversion uniquement à la valeur de donnée personnalisée explicitement fournie en paramètre (ici : index 5 avec la valeur ‘Amex Credit Card’).:ok =
Client.add_data(client, visitor_code, [
CustomData.new!(5, ["Credit Card"]),
CustomData.new!(9, ["Express Delivery"])
])
:ok =
Client.track_conversion(
client,
visitor_code,
goal_id,
metadata: [CustomData.new!(5, ["Amex Credit Card"])]
)
Valeur retournée
| Type | Description | |
|---|
| `:ok | {:error, Kameleoon.Error.t()}` | Indique si la conversion a été correctement mise en file d’attente pour le tracking asynchrone, sinon une erreur. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
get_engine_tracking_code()
Kameleoon s’intègre à plusieurs solutions d’analyse, notamment Mixpanel, Google Analytics 4 et Segment. Pour suivre correctement les expériences côté serveur, appelez la méthode Client.get_engine_tracking_code après que le visiteur a déclenché une expérience. Le SDK renvoie des commandes de file d’attente JavaScript pour les expériences que le visiteur a déclenchées au cours des cinq dernières secondes. Lorsque vous insérez ce code dans la page, Engine.js traite les commandes et envoie les événements d’exposition via l’intégration d’analyse active.
Consultez l’expérimentation hybride pour plus d’informations sur l’implémentation de cette méthode.
{:ok, tracking_code} = Kameleoon.Client.get_engine_tracking_code(client, visitor_code)
- Pour utiliser cette fonctionnalité, implémentez à la fois le SDK Elixir et Kameleoon Engine.js. Étant donné qu’Engine.js n’est utilisé que pour le tracking dans ce flux, vous pouvez installer le tag asynchrone avant la balise de fermeture
</body>.
- Si vous souhaitez uniquement suivre les expériences dans Kameleoon et n’avez pas besoin d’envoyer des événements d’exposition à des outils d’analyse tiers, utilisez le SDK JavaScript / TypeScript. Cette option fonctionne bien pour les plateformes de calcul serverless en périphérie. Le SDK JavaScript / TypeScript suit automatiquement les variations lorsque vous appelez
getVisitorCode, à condition que vous ajoutiez les attributions d’expérience correspondantes à window.kameleoonQueue.
- Vous pouvez insérer le code de tracking renvoyé directement dans une balise HTML
<script>.
<html lang="en">
<body>
<script>
const engineTrackingCode = `
window.kameleoonQueue = window.kameleoonQueue || [];
window.kameleoonQueue.push(['Experiments.assignVariation', 123456, 7890, true]);
window.kameleoonQueue.push(['Experiments.trigger', 123456, true]);
window.kameleoonQueue.push(['Experiments.assignVariation', 234567, 8901, true]);
window.kameleoonQueue.push(['Experiments.trigger', 234567, true]);
`;
const script = document.createElement('script');
script.textContent = engineTrackingCode;
document.body.appendChild(script);
</script>
</body>
</html>
123456 et 234567 sont des IDs d’expérience, et 7890 et 8901 sont des IDs de variation. Dans votre implémentation, le SDK génère ces valeurs dans le code de tracking renvoyé.Arguments
| Nom | Type | Description |
|---|
| visitor_code (obligatoire) | String.t() | Identifiant unique du visiteur. |
Valeur retournée
| Type | Description | |
|---|
| `{:ok, String.t()} | {:error, Kameleoon.Error.t()}` | Code JavaScript à insérer dans la page en cas de succès ; sinon, une erreur. |
Erreurs
| Type | Description |
|---|
Initialization | Indique que le SDK n’est pas encore entièrement initialisé. |
VisitorCodeInvalid | Exception indiquant que le visitor code fourni n’est pas valide. Il est soit vide, soit plus long que 255 caractères. |
Événements
on_datafile_update()
La méthode Client.on_datafile_update vous permet de gérer l’événement déclenché lorsque la configuration a mis à jour des données. Elle prend un paramètre d’entrée, handler. Le handler qui sera appelé lorsque la configuration est mise à jour via un événement de configuration en temps réel.
:ok =
Kameleoon.Client.on_datafile_update(client, fn ->
IO.puts("Kameleoon datafile updated")
end)
:ok = Kameleoon.Client.on_datafile_update(client, nil)
Arguments
| Nom | Type | Description |
|---|
| handler | (() -> any()) | nil | Le handler qui sera appelé lorsque la configuration est mise à jour via un événement de configuration en temps réel. |
Types de données
Cette section répertorie les types de données Elixir disponibles sous Kameleoon.Data.
ApplicationVersion
ApplicationVersion représente le numéro de version sémantique de votre application.
Un visiteur ne peut avoir qu’une seule ApplicationVersion. L’ajout d’une seconde instance remplacera la première.
| Nom | Type | Description |
|---|
| version (obligatoire) | String.t() | La version de l’application. Ce champ doit suivre le versionnement sémantique. Les formats acceptés sont major, major.minor ou major.minor.patch. |
alias Kameleoon.Client
alias Kameleoon.Data.ApplicationVersion
# major
:ok = Client.add_data(client, visitor_code, ApplicationVersion.new!("10"))
# major.minor
:ok = Client.add_data(client, visitor_code, ApplicationVersion.new!("10.20"))
# major.minor.patch
:ok = Client.add_data(client, visitor_code, ApplicationVersion.new!("10.20.30"))
Browser
L’ensemble de données Browser stocké ici peut être utilisé pour filtrer les rapports d’expérience et de personnalisation par toute valeur qui lui est associée.
| Nom | Type | Description |
|---|
| type (obligatoire) | atom() | Liste des navigateurs : :chrome, :internet_explorer, :firefox, :safari, :opera, :other. |
| version (optionnel) | number() | nil | Version du navigateur, le nombre à virgule flottante représente la version majeure et mineure du navigateur. |
alias Kameleoon.Client
alias Kameleoon.Data.Browser
# Données de navigateur avec une version
:ok = Client.add_data(client, visitor_code, Browser.new!(:safari, version: 26.4))
# Données de navigateur sans version
:ok = Client.add_data(client, visitor_code, Browser.new!(:chrome))
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
goal_id dans l’application Kameleoon.
| Nom | Type | Description | Par défaut |
|---|
| goal_id (obligatoire) | non_neg_integer() | ID de l’objectif. | |
| revenue (optionnel) | number() | nil | Revenu de la conversion. | nil |
| negative (optionnel) | boolean() | Définit si le revenu est positif ou négatif. | false |
| metadata (optionnel) | [Kameleoon.Data.CustomData.t()] | Métadonnées de la conversion. | [] |
alias Kameleoon.Client
alias Kameleoon.Data.Conversion
alias Kameleoon.Data.CustomData
# Ajouter une conversion simple avec l'ID 32
:ok = Client.add_data(client, visitor_code, Conversion.new!(32))
# Ajouter une conversion avec l'ID 33 incluant un revenu et marquée comme négative
:ok = Client.add_data(client, visitor_code, Conversion.new!(33, revenue: 10.0, negative: true))
# Ajouter une conversion avec l'ID 34 incluant un revenu, un drapeau négatif et des métadonnées personnalisées
:ok =
Client.add_data(
client,
visitor_code,
Conversion.new!(34,
revenue: 10.0,
negative: true,
metadata: [
CustomData.new!(3, ["metadata1", "md2"]),
CustomData.new!(5, ["md3"])
]
)
)
Cookie
Cookie contient des informations sur les cookies stockés sur l’appareil du visiteur.
| Nom | Type | Description |
|---|
| cookies | %\{String.t() => String.t()\} | Une map de chaînes contenant les clés et les valeurs des cookies. |
Chaque visiteur ne peut avoir qu’un seul Cookie. L’ajout d’un second Cookie remplace le premier.
alias Kameleoon.Client
alias Kameleoon.Data.Cookie
:ok = Client.add_data(client, visitor_code, Cookie.new!(%{"segment" => "vip"}))
CustomData
CustomData permet l’association de tout type de données à chaque visiteur, ce qui en fait un outil efficace pour les conditions de ciblage dans les segments. De plus, il peut être utilisé comme filtre ou découpage dans les rapports d’expérience. Pour plus d’informations sur les custom data, veuillez consulter cet article.
Définissez les types de données personnalisées dans l’application Kameleoon ou via l’API Data, puis utilisez-les depuis le SDK.
| Nom | Type | Description | Par défaut |
|---|
| index/name (obligatoire) | non_neg_integer()/String.t() | Index ou nom de la donnée personnalisée. Soit index, soit name doit être fourni pour identifier la donnée. | |
| values (obligatoire) | [String.t()] | Valeurs de la donnée personnalisée à stocker. | |
| overwrite (optionnel) | boolean() | Drapeau permettant de contrôler explicitement la façon dont les valeurs sont stockées et apparaissent dans les rapports. En savoir plus | true |
-
Chaque visiteur n’est autorisé à avoir qu’une seule
CustomData pour chaque index(name) unique. L’ajout d’une autre CustomData avec le même index(name) remplacera l’existante.
-
L’« index » de la donnée personnalisée se trouve dans le tableau de bord 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 donnée personnalisée.
-
L’ajout d’une instance de
CustomData créée avec un nom alors que l’instance du SDK n’est pas initialisée ou que le nom n’est pas enregistré entraînera l’ignorance de la donnée.
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
:ok = Client.add_data(client, visitor_code, CustomData.new!(1, ["value"]))
# Avec plusieurs valeurs
:ok = Client.add_data(client, visitor_code, CustomData.new!(1, ["value1", "value2"]))
# Pour définir le drapeau `overwrite` à false
:ok = Client.add_data(client, visitor_code, CustomData.new!(1, ["value"], overwrite: false))
# Pour utiliser un nom à la place de l'index
:ok = Client.add_data(client, visitor_code, CustomData.new_with_name!("my-custom-data", ["value"]))
# Pour utiliser un nom à la place de l'index et définir le drapeau `overwrite` à false
:ok =
Client.add_data(
client,
visitor_code,
CustomData.new_with_name!("my-custom-data", ["value"], overwrite: false)
)
Device
Vous pouvez utiliser les données d’appareil pour filtrer les rapports d’expérience et de personnalisation par toute valeur associée.
| Nom | Type | Description | | |
|---|
| type | `:phone | :tablet | :desktop` | Type d’appareil. |
alias Kameleoon.Client
alias Kameleoon.Data.Device
:ok = Client.add_data(client, visitor_code, Device.new!(:desktop))
Geolocation
Geolocation contient les détails de géolocalisation du visiteur.
| Nom | Type | Description |
|---|
| country (obligatoire) | String.t() | Le pays du visiteur. |
| region (optionnel) | String.t() | nil | La région du visiteur. |
| city (optionnel) | String.t() | nil | La ville du visiteur. |
| postal_code (optionnel) | String.t() | nil | Le code postal du visiteur. |
| latitude (optionnel) | number() | nil | La coordonnée de latitude représentant l’emplacement du visiteur. Le nombre de la coordonnée représente des degrés décimaux. |
| longitude (optionnel) | number() | nil | La coordonnée de longitude représentant l’emplacement du visiteur. Le nombre de la coordonnée 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.
alias Kameleoon.Client
alias Kameleoon.Data.Geolocation
geolocation =
Geolocation.new!("France",
region: "Ile-de-France",
city: "Paris",
postal_code: "75009",
latitude: 48.8720171,
longitude: 2.3338352
)
:ok = Client.add_data(client, visitor_code, geolocation)
OperatingSystem
OperatingSystem contient des informations sur le système d’exploitation de l’appareil du visiteur.
| Nom | Type | Description | | | | | |
|---|
| type | `:windows | :mac | :ios | :linux | :android | :windows_phone` | Famille du système d’exploitation. |
Chaque visiteur ne peut avoir qu’un seul OperatingSystem. L’ajout d’un second OperatingSystem remplace le premier.
alias Kameleoon.Client
alias Kameleoon.Data.OperatingSystem
:ok = Client.add_data(client, visitor_code, OperatingSystem.new!(:windows))
PageView
Stocker les événements de page vue.
| Nom | Type | Description | Par défaut | |
|---|
| url | String.t() | URL de la page consultée. | | |
| title | `String.t() | nil` | Titre de la page consultée. | nil |
| referrers | [integer()] | Indices de référents des pages précédemment consultées. | [] | |
L’index de référent est disponible dans l’application Kameleoon sur la page de configuration des canaux d’acquisition. Attention : l’index commence à 0, donc le premier canal d’acquisition que vous créez a l’ID 0, et non 1. alias Kameleoon.Client
alias Kameleoon.Data.PageView
# Constructeur complet avec url, titre optionnel et référents.
:ok = Client.add_data(client, visitor_code, PageView.new!("https://example.com", title: "Homepage", referrers: [3]))
# Constructeur minimal, ne nécessite qu'une URL.
:ok = Client.add_data(client, visitor_code, PageView.new!("https://example.com"))
UniqueIdentifier
Si vous n’ajoutez pas UniqueIdentifier pour un visiteur, visitor_code est utilisé comme identifiant unique du visiteur, ce qui est utile pour l’expérimentation cross-device. Lorsque vous ajoutez UniqueIdentifier(true), le SDK lie les données envoyées (flush) au visiteur associé à l’identifiant spécifié.
Cela peut être utile dans des situations où vous ne pouvez pas accéder au visitor_code anonyme attribué à l’origine à un visiteur, mais où vous avez accès à un identifiant interne lié à ce visiteur via la fusion de sessions.
| Nom | Type | Description |
|---|
value | boolean() | Indique si le visitor_code actuel doit être traité comme un identifiant unique. |
alias Kameleoon.Client
alias Kameleoon.Data.UniqueIdentifier
:ok = Client.add_data(client, visitor_code, UniqueIdentifier.new!(true))
UserAgent
Les expériences côté serveur sont plus susceptibles d’être affectées par le trafic des bots que les expériences côté client. Kameleoon utilise la liste IAB/ABC International Spiders and Bots pour reconnaître les bots et spiders connus, et utilise également le champ UserAgent pour filtrer d’autres trafics indésirables qui pourraient fausser vos métriques de conversion. Pour plus d’informations, consultez l’article d’aide sur le filtrage des bots.
Si vous utilisez des bots internes, nous vous recommandons d’envoyer la valeur user-agent curl/8.0 pour les exclure des analyses.
| Nom | Type | Description |
|---|
| value | String.t() | Valeur User-Agent envoyée avec les requêtes de tracking. |
alias Kameleoon.Client
alias Kameleoon.Data.UserAgent
:ok = Client.add_data(client, visitor_code, UserAgent.new!("Mozilla/5.0"))
Types retournés
DataFile
Le DataFile contient les détails de configuration du SDK.
Il peut être étendu avec des informations supplémentaires si les clients en ont besoin. Si vous avez besoin de plus de détails, veuillez contacter votre Customer Success Manager.
| Nom | Type | Description |
|---|
| feature_flags | %\{String.t() => Kameleoon.Types.FeatureFlag.t()\} | Une map d’objets FeatureFlag, indexée par les clés des feature flags. |
| date_modified | non_neg_integer() | nil | L’horodatage (en millisecondes) indiquant la dernière modification du DataFile. |
# Récupère la map des feature flags depuis le DataFile.
# La map est indexée par les identifiants de feature flag, chaque valeur étant une structure FeatureFlag.
feature_flags = datafile.feature_flags
# Récupère l'horodatage de la dernière modification du DataFile.
# La valeur est un entier représentant les millisecondes depuis l'époque Unix.
date_modified = datafile.date_modified
FeatureFlag
Le FeatureFlag représente un ensemble de propriétés qui définissent un feature flag lui-même — par exemple, ses Variations, Rules, son statut d’environnement et d’autres détails associés.
Il peut être étendu avec des informations supplémentaires si les clients en ont besoin. Si vous avez besoin de plus de détails, veuillez contacter votre Customer Success Manager.
| Nom | Type | Description |
|---|
| environment_enabled | boolean() | Indique si le feature flag est activé dans l’environnement actuel. |
| default_variation_key | String.t() | La clé de la variation par défaut associée au feature flag. |
| variations | %\{String.t() => Kameleoon.Types.Variation.t()\} | Une map d’objets Variation, indexée par les clés de variation. |
| rules | [Kameleoon.Types.Rule.t()] | Une liste d’objets Rule. |
# Vérifie si le feature flag est activé dans l'environnement actuel.
environment_enabled = feature_flag.environment_enabled
# Récupère la clé de la variation par défaut.
default_variation_key = feature_flag.default_variation_key
# Récupère la structure de la variation par défaut.
default_variation = Kameleoon.Types.FeatureFlag.default_variation(feature_flag)
# Récupère toutes les variations du feature flag sous forme de map (clé = clé de variation, valeur = structure Variation).
variations = feature_flag.variations
# Récupère toutes les règles de ciblage associées au feature flag.
rules = feature_flag.rules
Rule
La Rule représente un ensemble de propriétés qui définissent une règle elle-même — par exemple, ses Variations.
Elle peut être étendue avec des informations supplémentaires si les clients en ont besoin. Si vous avez besoin de plus de détails, veuillez contacter votre Customer Success Manager.
| Nom | Type | Description |
|---|
| variations | %\{String.t() => Kameleoon.Types.Variation.t()\} | Une map d’objets Variation, indexée par les clés de variation. |
# Récupère toutes les variations de la règle sous forme de map (clé = clé de variation, valeur = structure Variation).
variations = rule.variations
Variation
Variation contient des informations sur la variation attribuée au visiteur, ou la variation par défaut lorsqu’aucune attribution spécifique n’existe.
| Nom | Type | Description | |
|---|
| name | `String.t() | nil` | Le nom de la variation. |
| key | `String.t() | nil` | La clé unique identifiant la variation. |
| id | `non_neg_integer() | nil` | L’ID de la variation attribuée, ou nil pour une variation par défaut. |
| experiment_id | `non_neg_integer() | nil` | L’ID de l’expérience associée à la variation, ou nil pour une variation par défaut. |
| variables | [Kameleoon.Types.Variable.t()] | Variables associées à la variation. Cette collection peut être vide lorsqu’aucune variable n’est attachée. | |
Variation décrit la variation attribuée ou par défaut, tandis que Variable contient les détails de chaque variable individuelle.id et experiment_id peuvent être nil, ce qui indique une variation par défaut qui n’est pas liée à une attribution d’expérience spécifique.
| Méthode | Type de retour | Description |
|---|
Kameleoon.Types.Variation.active? | boolean() | Renvoie false pour la variation off. |
# Récupération du nom de la variation.
variation_name = variation.name
# Récupération de la clé de la variation.
variation_key = variation.key
# Récupération de l'id de la variation.
variation_id = variation.id
# Récupération de l'id de l'expérience.
experiment_id = variation.experiment_id
# Récupération de la liste des variables.
variables = variation.variables
# Vérifier si la variation est active (c'est-à-dire actuellement servie aux visiteurs).
active? = Kameleoon.Types.Variation.active?(variation)
# Récupération d'une variable par sa clé, renvoyant nil si introuvable.
variable = Enum.find(variation.variables, &(&1.key == "title"))
Variable
Variable contient des informations sur une variable associée à la variation attribuée.
| Nom | Type | Description | |
|---|
| key | String.t() | nil | La clé unique identifiant la variable. | |
| kind | String.t() | nil | Le type de variable. Les valeurs possibles incluent BOOLEAN, NUMBER, STRING, JSON, JS et CSS. | |
| value | `boolean() | number() | String.t() | nil` | La valeur de la variable. Selon kind, elle peut contenir un booléen, un nombre, une chaîne, une chaîne JSON, un extrait JavaScript ou un extrait CSS. |
# Récupérer la liste des variables associées à la variation.
variables = variation.variables
# Accéder au type de variable (kind) pour une gestion conditionnelle.
kind = variable.kind
# Extraire la valeur en tant que nombre.
number = variable.value
# Extraire la valeur en tant que booléen.
apply_discount? = variable.value
# Extraire la valeur en tant que chaîne.
title = variable.value
