L'API Identify vous permet de transmettre des données sur vos utilisateurs avec JavaScript, et de les enregistrer en tant que Caractéristiques de l’utilisateur. Ces Caractéristiques de l’utilisateur peuvent être utilisées pour cibler des sondages. Vous pouvez envoyer jusqu'à 100 caractéristiques d'utilisateur sur n'importe quel site, avec n'importe quel nombre d'utilisateurs associés à ces caractéristiques.
- Aperçu
- Gestion des ID utilisateur
- Appels à l'API Identify
- Valeurs des Caractéristiques de l’utilisateur
- Gestion des adresses e-mail
- Exemples de transmission de Caractéristiques de l’utilisateur
- Désactivation des Caractéristiques de l’utilisateur
- Suppression des Caractéristiques de l’utilisateur
- Bonnes pratiques
Aperçu
Les Caractéristiques de l’utilisateur sont des valeurs de données concernant les utilisateurs de votre site transmises depuis votre code côté client via l'API Identify. Ces données sont transmises sous forme de paires clé-valeur lors d'un appel AJAX asynchrone à nos serveurs. Ces valeurs sont associées à un ID utilisateur, une valeur identifiable de manière unique transmise à nous dans votre code à partir d'une valeur ID utilisateur de votre base de données utilisateur. Cela permet à Contentsquare d'associer les données collectées à leur sujet avec le même ID utilisateur que vous utilisez dans votre propre base de données, ainsi que de rechercher des informations sur l'utilisateur détenues à propos de cet utilisateur.
Il y a 4 phases dans le processus d'envoi des Caractéristiques de l’utilisateur et de leur utilisation avec Contentsquare.
- Obtenez les données de votre site.
- Transmettez les données à Contentsquare via l'API Identify.
- Contentsquare stocke les données concernant chaque utilisateur en tant que Caractéristiques de l’utilisateur contre leur user_id.
- Vous pouvez maintenant cibler et filtrer les Sondages par Caractéristiques de l’utilisateur.
Appels à l'API Identify
Avant de pouvoir commencer à faire des appels à l'API Identify, les Caractéristiques de l’utilisateur doivent être activées dans vos paramètres pour chaque site avec lequel vous souhaitez utiliser les Caractéristiques de l’utilisateur.
Activation et désactivation des Caractéristiques de l’utilisateur
Sur votre page des Caractéristiques de l’utilisateur (Paramètres > Caractéristiques de l’utilisateur), trouvez le Site auquel vous souhaitez ajouter des Caractéristiques de l’utilisateur en utilisant le menu déroulant de sélection.
Vous pouvez également désactiver les Caractéristiques de l’utilisateur sur cette page. Une fois que vous avez sélectionné un Site avec les Caractéristiques de l’utilisateur activées, cliquez sur Désactiver les Caractéristiques de l’utilisateur. Une fois que vous avez fait cela, d'autres appels à l'API seront bloqués. Le bouton "Désactiver les Caractéristiques de l’utilisateur" n'apparaîtra que après que les données des caractéristiques de l'utilisateur aient été reçues par Contentsquare, mais pas avant.
Si vous souhaitez empêcher l'envoi des Caractéristiques de l’utilisateur à l'avenir, vous devez retirer le code de l'API Identify de votre site. Une fois le code supprimé de votre site, les Caractéristiques de l’utilisateur collectées précédemment existeront toujours, mais elles ne seront plus mises à jour ou ajoutées à de nouveaux utilisateurs de votre site.
L'appel API
Voici le format d'un appel à l'API Identify :
hj('identify', userId, {
user_attribute: value
});
- Le premier paramètre doit toujours contenir la valeur de chaîne "identify".
- Le deuxième doit être une chaîne contenant l'ID utilisateur pour un utilisateur sur votre site, provenant de votre propre base de données utilisateur, ou null s'il n'est pas connu.
- Le troisième est une série de paires clé-valeur à l'intérieur d'un objet. La clé fournit le nom de l'attribut utilisateur, et la valeur définit à la fois le type d'un attribut utilisateur et sa valeur pour cet utilisateur. Les noms d'attributs utilisateur ont une longueur maximale de 50 caractères.
Les valeurs passées dans cet appel doivent provenir de la base de code de votre propre site. Ces valeurs peuvent être extraites directement de vos serveurs ou générées côté client.
Une fois envoyés à Contentsquare, ces attributs et les valeurs pour chaque utilisateur sont stockés sur les serveurs de Contentsquare. Chaque fois qu'un appel à l'API Identify est effectué, les valeurs stockées sur les serveurs de Contentsquare seront remplacées par les valeurs les plus récentes pour ces attributs.
Vous pouvez consulter tous les attributs envoyés à Contentsquare dans votre page de paramètres des attributs utilisateur. Vous pouvez utiliser la fonctionnalité de recherche de l'utilisateur pour inspecter quelles valeurs ont été passées pour un utilisateur spécifique sur votre site.
Gestion des ID utilisateur
Le deuxième argument passé à Contentsquare via l'appel de l'API Identify doit être un ID utilisateur identifiable de manière unique provenant de la base de données de votre propre site. Les attributs utilisateur sont associés à cet ID utilisateur.
L'ID utilisateur doit être unique par utilisateur mais ne doit pas contenir d'informations personnelles. Il doit également être une valeur qui ne change jamais pour cet utilisateur. Une fois que vous avez défini un ID utilisateur dans Contentsquare, il ne peut pas être changé. S'il change, Contentsquare considérera cela comme un nouvel utilisateur.
Si un ID utilisateur n'est pas connu (en passant une valeur null), alors tout autre attribut utilisateur passé à Contentsquare ne doit pas contenir d'informations personnellement identifiables (PII). Votre capacité à rechercher des attributs utilisateur associés à un utilisateur individuel dépend de votre capacité à rechercher son ID utilisateur. Nous n'avons aucun moyen de récupérer ou de supprimer ces données à moins que vous ne supprimiez l'ensemble du site.
Valeurs des attributs utilisateur
Vous pouvez passer les valeurs suivantes à une clé d'attribut utilisateur en utilisant l'API Identify. Les caractères spéciaux ne peuvent pas être utilisés pour le moment.
Gestion des adresses e-mail
Pour l'instant, il existe une clé d'attribut utilisateur pour les adresses e-mail : e-mail. Les adresses e-mail doivent être passées sous forme de chaînes à e-mail. Par exemple :
hj('identify', userId, {
e-mail: 'test@test.com'
});
Si d'autres attributs utilisateur de type chaîne contiennent une adresse e-mail, ceux-ci seront rejetés, ce qui signifie que vous ne devez utiliser que `e-mail` pour passer des adresses e-mail.
Adresses e-mail et ID utilisateur
l'ID utilisateur peut prendre la forme d'adresses e-mail, donc si la clé primaire de votre base de données pour les utilisateurs est leur adresse e-mail, cela peut être utilisé comme un ID utilisateur. Cela ne devrait être utilisé qu'en dernier recours. Si la clé primaire d'un utilisateur dans votre base de données existe autrement qu'une adresse e-mail, vous devriez utiliser cela.
Parce que les adresses e-mail peuvent généralement changer, si leur adresse e-mail est mise à jour, Contentsquare considérera cet utilisateur comme un utilisateur totalement différent. Cela vous empêcherait d'utiliser la recherche de l'utilisateur sur l'ancienne adresse e-mail, ce qui pourrait enfreindre vos exigences en matière de confidentialité.
Exemples de passage des caractéristiques de l’utilisateur
Identification des clients payants
Voici un exemple, où nous voulons être en mesure de dire à Contentsquare combien d'argent quelqu'un a dépensé sur votre site.
hj('identify', userId, {
total_spend: 500
});Plusieurs attributs peuvent être passés en ajoutant d'autres paires clé-valeur dans l'objet. Peut-être que vous vouliez que Contentsquare sache quand ils sont devenus clients pour la première fois ?
hj('identify', userId, {
total_spend: 500,
first_purchase: '2019-06-20Z'
});
Nous disons ici à Contentsquare que votre utilisateur est devenu client de votre service en utilisant une chaîne de date ISO8601.
Identification des attributs pour les utilisateurs déidentifiés
Parfois, il est utile de suivre des informations sur les utilisateurs de votre site, même s'ils ne sont pas encore utilisateurs ou clients payants. Disons que vous vouliez suivre la source de référence, et la variante de test A-B de la page d'entrée d'un lead potentiel qui vous a contacté :
hj('identify', null, {
ab_test: 'variant-A',
referrer: 'facebook_paid'
});
Cela serait utile si vous vouliez cibler un sondage contre les utilisateurs de la variante-A, ou seulement ceux qui sont venus à vous via des publicités payantes sur Facebook, par exemple.
Gestion des demandes de recherche et de suppression d'utilisateur
Il est possible de rechercher et de supprimer les données d'un utilisateur en utilisant son ID utilisateur. En savoir plus à ce sujet dans notre article Comprendre l'outil de recherche d'utilisateur . Il est important de noter que si vous connaissez l'ID utilisateur d'un utilisateur et son adresse e-mail, vous devriez rechercher ses informations avec les deux. C'est le seul moyen de s'assurer que toutes les informations personnelles concernant cet utilisateur ont été recherchées et supprimées.
Désactivation des caractéristiques de l’utilisateur
Pour empêcher l'envoi de nouvelles caractéristiques de l’utilisateur, vous devez désactiver les caractéristiques de l’utilisateur.
Tant que les caractéristiques de l’utilisateur sont activées sur votre site, si vous souhaitez empêcher leur envoi à l'avenir, vous devez retirer le code pertinent de votre site. Une fois le code supprimé de votre site, les caractéristiques de l’utilisateur précédemment collectées existeront toujours, mais ne seront plus mises à jour ou ajoutées aux nouveaux utilisateurs de votre site.
Suppression des caractéristiques de l’utilisateur
Les caractéristiques de l’utilisateur peuvent être supprimées de la page de gestion des caractéristiques de l’utilisateur en cliquant sur l'icône de la corbeille à droite de l'attribut.
La suppression d'une caractéristique de l’utilisateur ne l'enlèvera pas des sessions ou des réponses existantes qui la contiennent. L'attribut ne sera retiré que du filtrage et du ciblage. N'oubliez pas de retirer l'attribut de l’utilisateur supprimé de tous les appels de l'API Identify, sinon, il réapparaîtra dans la liste.
Lorsqu'un attribut est supprimé, il disparaît immédiatement. Cependant, l'attribut est toujours stocké dans le back-end pendant 7 jours avant d'être définitivement supprimé. Les données associées à l'attribut sont ignorées pendant la période de 7 jours. Cela permet d'éviter l'envoi de données en raison de problèmes de mise en cache.
Si vous souhaitez recréer un attribut qui a été supprimé, vous devrez attendre 7 jours avant que l'attribut puisse être recréé avec succès.
Bonnes pratiques
Quand effectuer des appels API à Identify
Vous devez effectuer des appels à Identify chaque fois que :
- Une page est chargée avec les valeurs les plus récentes (même si elles n'ont pas changé).
- Après un changement d'URL dans les applications à page unique.
- Chaque fois qu'un changement est effectué. Par ex. si vous souhaitez suivre leur dernier achat dans un magasin, vous voudrez mettre à jour cette caractéristique de l’utilisateur une fois qu'un achat a été effectué.
Chaque appel mettra à jour les caractéristiques de l’utilisateur avec les valeurs les plus récentes. Lorsqu'un appel est effectué, mais que les valeurs n'ont pas été mises à jour, la requête réseau ne sera pas envoyée afin d'éviter des requêtes AJAX inutiles.
Combinaison du ciblage des caractéristiques de l’utilisateur avec d'autres déclencheurs pour les sondages
Si vous prévoyez de combiner événements avec le ciblage des caractéristiques de l’utilisateur pour les sondages, vous devez vous assurer que l'appel Identify a eu lieu avant le déclencheur dans votre ordre d'exécution, en tenant compte de tout appel asynchrone à d'autres services. Si le déclencheur est exécuté avant que l'appel API Identify ait terminé son exécution, le sondage ne s'affichera pas.
Mise en file d'attente des appels à l'API avant que le tag de Contentsquare ne soit chargé
Si ce script est ajouté avant votre tag de Contentsquare, il y aura une erreur.
L'objet hj() ne peut pas être accédé tant que le tag de Contentsquare n'a pas été exécuté. Si pour une raison quelconque vous accédez à l'API Identify avant que le tag de Contentsquare n'ait été exécuté, vous pouvez ajouter la ligne de code suivante avant que l'API ne soit appelée :
window.hj=window.hj||function(){(hj.q=hj.q||[]).push(arguments)};