Google Tag Manager (GTM) fait partie des solutions recommandées pour déployer le script de suivi Positive User sur votre site web. Une fois le script installé, Positive User commence à suivre automatiquement les visiteurs, crée des fiches de contact et vous permet d’enrichir ces profils avec les données utiles à votre activité.
Ce guide couvre trois points :
L’installation du script d’implémentation de base ;
L’identification des contacts à l’aide d’un ID de contact ;
L’enrichissement de la configuration avec des données de contact et des callbacks supplémentaires.
Un espace de travail Positive User actif.
Les informations de clé d’espace de travail et de sous-domaine (dans “Paramètres de l'espace de travail” → “API & Intégrations” → section “Configuration et intégrations”).
Un accès au conteneur GTM installé sur votre site web.
Une stratégie de gestion des cookies/du consentement déjà mise en place.
Le script d’implémentation initialise un objet de configuration (window.civchat) puis charge le fichier “widget.js”. En passant par GTM, vous pouvez le déployer, le mettre à jour ou le désactiver sans modifier le code de votre site à chaque fois.
Récupérer votre clé d’espace de travail et votre sous-domaine
Dans votre espace de travail Positive User, accédez à “Paramètres de l'espace de travail” → “API & Intégrations” → “Configuration et intégrations” pour récupérer votre clé d’espace de travail, puis notez votre sous-domaine d’espace de travail (par exemple : yourapp.user.com).
Créer un tag HTML personnalisé dans GTM
Connectez-vous à votre conteneur GTM puis accédez à “Balises” → “Nouvelle” → “Configuration de la balise" → “HTML personnalisée” et collez le script ci-dessous. Remplacez YOUR_KEY par la clé d’espace de travail récupérée à l’étape 1, puis remplacez yourapp.user.com par le sous-domaine de votre espace de travail :
<script data-cfasync="false" type="text/javascript">
window.civchat = {
apiKey: 'YOUR_KEY'
};
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Définir le déclencheur dans le conteneur GTM
Dans la section “Déclenchement”, choisissez le déclencheur adapté à votre configuration de consentement - généralement un événement “cookie_consent_update” (ou son équivalent). Ainsi, le script se charge uniquement après l’acceptation des cookies par le visiteur. Si vous ne disposez pas d’une couche de gestion du consentement, vous pouvez commencer avec le déclencheur ”Page vue” → “Toutes les pages vues”.
Enregistrer, prévisualiser et publier
Nommez la balise (par exemple : “Positive User - Tracking Script”), cliquez sur “Enregistrer”, puis lancez le mode “Prévisualiser” de GTM afin de vérifier que le tag se déclenche correctement et que le widget se charge. Une fois la vérification effectuée, soumettez et publiez le conteneur GTM.
typeof UE === 'object' && typeof userengage === 'function'. Si le résultat est true, cela signifie que Positive User est prêt.
Par défaut, Positive User suit les visiteurs de façon anonyme grâce à un cookie (__ca__chat). Pour transformer un visiteur anonyme en contact identifié - et conserver son historique cohérent entre différents appareils et sessions - transmettez un ID de contact via le champ “user_id” (attribut) dans “window.civchat”.
Choisir le bon ID de contact
L’ID de contact à utiliser dépend de la manière dont votre entreprise identifie ses utilisateurs. Il n’existe pas de format unique recommandé : l’essentiel est d’utiliser un identifiant stable et unique, transmis de façon cohérente sur l’ensemble de vos points de contact. Les trois options les plus couramment utilisées sont :
ID de base de données interne : l’option la plus stable, car elle ne change jamais même si le contact modifie son adresse email. C’est celle utilisée dans les exemples de cet article.
Adresse email en minuscules : simple à mettre en place et facile à lire dans l’espace de travail, mais liée à l’adresse email actuelle du contact.
Hash SHA-256 de l’adresse email en minuscules : offre le même niveau d’unicité que l’email, sans transmettre de données personnelles brutes via GTM ou les variables du navigateur.
Pour en savoir plus sur les ID, consultez notre article dédié. [LINK]
L’ID de contact doit être disponible au moment où “window.civchat” est défini - donc avant le chargement de “widget.js”. L’approche standard consiste à le récupérer depuis le dataLayer (couche de données) alimenté par votre site pour les contacts connectés, puis à l’affecter conditionnellement à l’objet civchat.
Trouver l’ID de contact dans votre dataLayer
Sur la plupart des plateformes e-commerce (Magento, Shopify, WooCommerce, PrestaShop, etc.), le dataLayer contient déjà des informations sur le client connecté - notamment un ID client, une adresse email et des informations de profil de base. Aucun développement JavaScript spécifique n’est nécessaire : il suffit cund’identifier la clé du dataLayer contenant la valeur que vous souhaitez utiliser comme ID de contact.
Pour vérifier les données disponibles :
Ouvrez GTM et cliquez sur “Prévisualiser” en haut à droite.
Saisissez l’URL de votre site web puis connectez-vous avec un compte client de test dans la fenêtre de prévisualisation.
Dans GTM Tag Assistant, ouvrez l’onglet “Data Layer” sur n’importe quel événement.
Recherchez un objet contenant des informations utilisateur ou client. Les clés les plus fréquentes sont : “visitorId”, “user_id”, “customerId” ou des variantes similaires.
Créer ou réutiliser une variable dataLayer dans GTM
Dans GTM, accédez à “Variables” et vérifiez si une variable correspondant à votre ID client existe déjà - dans les conteneurs configurés par une agence ou pour une intégration analytique existante, c’est souvent le cas. Recherchez une variable de type “Data Layer Variable” pointant vers des clés comme “customer_id” ou “user_id”. Si une variable existe déjà, vous pouvez la réutiliser et passer directement à l’étape suivante.
Sinon, accédez à “Variables” → “Nouvelle” → “Variable de couche de données” puis créez-en une. Dans le champ “Nom de le couche de données”, saisissez exactement le nom de la clé trouvée dans votre dataLayer (par exemple : “customer_id”). Donnez un nom explicite à la variable, comme “DLV - user_id”.
Mettre à jour la balise
Modifiez la balise HTML personnalisée et attribuez l’ID de contact de manière conditionnelle, afin qu’elle soit ajoutée uniquement lorsque le visiteur est connecté :
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY'
};
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Lorsque “user_id” est présent, Positive User l’utilise comme identifiant principal. Si cet ID existe déjà dans votre espace de travail, le suivi bascule vers la fiche du contact correspondante. Sinon, l’ID est associé à la session anonyme en cours et un nouveau contact est créé.
Une fois le contact identifié, vous pouvez enrichir sa fiche avec des attributs supplémentaires. Transmettez ces valeurs au niveau racine de l’objet de configuration civchat, au même niveau que “user_id” :
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY'
};
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
civchatConfig.email = {{DLV - user_email}};
civchatConfig.first_name = {{DLV - user_first_name}};
civchatConfig.last_name = {{DLV - user_last_name}};
civchatConfig.phone_number = {{DLV - user_phone}};
// Custom attributes go at the same level
civchatConfig.plan_type = {{DLV - user_plan}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Quelques points importants à retenir :
Attributs standards et attributs personnalisés : Les attributs standards (comme “Email”, “Phone number”, “Gender” ou “Status”) sont reconnus automatiquement par Positive User. Les attributs personnalisés (comme “Abonnement”) doivent déjà exister dans l’espace de travail. Créez-les au préalable dans la section appropriée. (Consultez l’article “Comment créer un attribut personnalisé ?”)
Le format est important : Choisissez toujours un type d’attribut adapté, car il détermine les possibilités de filtrage disponibles par la suite. Pour consulter la liste complète des règles de formatage, référez-vous à la documentation développeur ou à l’article “Qu'est-ce qu'un attribut ?”.
Les valeurs remplacent les données existantes : tout attribut transmis ici remplacera la valeur déjà enregistrée sur la fiche du contact. Transmettez uniquement les attributs dont vous disposez réellement d’une valeur - c’est pourquoi ils sont placés dans le bloc “if” ci-dessus.
Les callbacks permettent à votre code de réagir à ce qui se passe dans le widget de chat Positive User — par exemple lorsque le widget est complètement chargé ou lorsqu’un nouveau message est reçu. Ils sont définis comme des fonctions dans le même objet de configuration civchat, au même niveau que apiKey et user_id.
Callbacks disponibles
Le SDK Positive User expose les callbacks suivants :
onLoad : exécuté une fois le script et les ressources du widget entièrement chargés. Utile pour déclencher d’autres balises GTM dépendant du SDK Positive User.
onMessage : exécuté chaque fois qu’un message de chat est reçu. L’objet message contient un indicateur “isAdmin” indiquant si le message provient d’un utilisateur/automatisation (true) ou du contact (false).
onOpen / onClose : exécutés lorsque le widget de chat est ouvert ou réduit.
onPayloadReceived : exécuté lorsque le widget reçoit une payload depuis le module d'automatisation “Send Code”.
Consultez la documentation développeur pour la liste complète.
Le script ci-dessous montre une configuration complète combinant tous les éléments présentés dans ce guide : callback onLoad, ID de contact, adresse email et données de contact supplémentaires. Vous pouvez l’utiliser comme base pour votre environnement de production :
<script data-cfasync="false" type="text/javascript">
var civchatConfig = {
apiKey: 'YOUR_KEY',
// Notify GTM once the widget is fully loaded
onLoad: function() {
dataLayer.push({ event: 'Positive User - Widget Ready' });
}
};
// Identify the contact and pass their data only when logged in
if ({{DLV - user_id}}) {
civchatConfig.user_id = {{DLV - user_id}};
civchatConfig.email = {{DLV - user_email}};
civchatConfig.first_name = {{DLV - user_first_name}};
civchatConfig.last_name = {{DLV - user_last_name}};
civchatConfig.phone_number = {{DLV - user_phone}};
civchatConfig.plan_type = {{DLV - user_plan}};
}
window.civchat = civchatConfig;
</script>
<script data-cfasync="false" src="https://yourapp.user.com/widget.js"></script>
Dans GTM, vous pouvez ensuite créer un déclencheur “Événement personnalisé” écoutant l’événement “Positive User - Widget Ready” et l’utiliser sur toutes les balises nécessitant la disponibilité du SDK Positive User.
GTM est pratique, mais ajoute une couche supplémentaire entre votre site web et Positive User. Si le script ne semble pas se déclencher :
Vérifiez avec le mode “Prévisualiser” de GTM que la balise s’exécute bien sur la page.
Assurez-vous que le conteneur GTM est publié (ou “envoyé”) et pas uniquement enregistré.
Vérifiez la console du navigateur afin d’identifier d’éventuelles erreurs JavaScript empêchant l’exécution du script.
Vérifiez que les bloqueurs de publicité, outils de gestion du consentement ou votre CSP ne bloquent pas GTM ou le domaine Positive User.
Vérifiez que les variables du dataLayer se résolvent correctement en mode “Prévisualiser” - si une variable est vide, le champ correspondant dans “civchat” sera également vide.
Comment configurer un widget de chat ?
Comprendre les identifiants