Identifier les visiteurs connectés en toute sécurité

Quand un client connecté ouvre votre chat, votre équipe doit savoir qui il est. Mais tout ce que votre page envoie depuis le navigateur peut être modifié par la personne qui l’utilise. Si le widget faisait confiance à un simple ID utilisateur, n’importe qui pourrait saisir l’ID d’une autre personne et lire son historique.

Giov résout ce problème avec une signature. Votre serveur signe l’ID de l’utilisateur avec un secret que seuls vous et Giov connaissez. Cette signature s’appelle userHash. Sans signature valide, un ID utilisateur est traité comme une simple déclaration et n’est jamais lié à un contact.

Comment ça marche

1. Vous générez un secret d’identité dans le tableau de bord et vous le stockez sur votre serveur.
2. Votre serveur calcule userHash : le HMAC-SHA256 de l’ID utilisateur, avec le secret comme clé, en hexadécimal.
3. Votre page transmet l’ID et le hash au widget.
4. Giov recalcule le hash et le compare. S’ils correspondent, la conversation appartient à ce client.

Le secret ne quitte jamais votre serveur : personne dans le navigateur ne peut donc produire un hash valide pour un autre utilisateur.

1. Générer le secret

1. Ouvrez Paramètres → Widget de chat → Infos visiteur.
2. Sous Secret de signature, sélectionnez Générer un secret.
3. Copiez-le immédiatement. Vous ne le reverrez plus. Stockez-le dans le gestionnaire de secrets de votre serveur, par exemple sous le nom GIOV_IDENTITY_SECRET.

2. Calculer userHash sur votre serveur

Utilisez le secret exactement tel qu’il a été émis, comme du texte UTF-8. Ne le décodez pas depuis base64. Hachez l’ID utilisateur comme une chaîne de caractères et produisez de l’hexadécimal en minuscules.

import { createHmac } from "node:crypto";

// Server only. Read the secret from your server configuration.
const userHash = createHmac("sha256", process.env.GIOV_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");

import hashlib
import hmac
import os

# Server only. Read the secret from your server configuration.
user_hash = hmac.new(
    os.environ["GIOV_IDENTITY_SECRET"].encode("utf-8"),
    str(user.id).encode("utf-8"),
    hashlib.sha256,
).hexdigest()

<?php
// Server only. Read the secret from your server configuration.
$userHash = hash_hmac('sha256', (string) $user->id, getenv('GIOV_IDENTITY_SECRET'));

require "openssl"

user_hash = OpenSSL::HMAC.hexdigest("SHA256", ENV["GIOV_IDENTITY_SECRET"], user.id.to_s)

3. Transmettre l’ID et le hash au widget

Sur les pages connectées, affichez les deux valeurs depuis votre serveur, juste avant le snippet d’installation :

<script>
  window.GiovChatSettings = {
    userId: "USER_ID",     // the same id your server hashed
    userHash: "USER_HASH", // computed on your server, never in the browser
    email: "ada@example.com" // optional contact details
  };
</script>
<script src="https://widget.giovchat.app/YOUR_WORKSPACE_ID" async></script>

Vous pouvez ajouter email, phone, firstName et lastName au même objet. Votre équipe les voit avec la conversation, et en transmettre un seul suffit à ignorer le formulaire préalable au chat.

4. Exiger une identité vérifiée

Une fois que votre serveur envoie des hashes partout, activez N'accepter que les ID signés dans Paramètres → Widget de chat → Infos visiteur. Les nouvelles conversations qui envoient un ID utilisateur sans hash valide sont alors rejetées. Les visiteurs anonymes, qui n’envoient aucun ID utilisateur, peuvent toujours démarrer un chat.

Ce que voit votre équipe

Les erreurs qui cassent la vérification

• Hacher une chaîne différente. L’ID que vous hachez et le userId que vous envoyez doivent correspondre caractère pour caractère. Convertissez les ID numériques en chaînes aux deux endroits, et n’ajoutez pas d’espaces.
• Décoder le secret. Il s’utilise comme du texte brut. Le décoder depuis base64 produit une clé différente.
• Définir les valeurs trop tard. Le widget lit window.GiovChatSettings une seule fois, quand le loader s’exécute. Définissez-le avant le script du loader. Dans une application monopage, définissez-le avant d’ajouter le loader.
• Hacher dans le navigateur. Cela fonctionne jusqu’à ce que quelqu’un lise votre bundle et y trouve le secret. Hachez toujours côté serveur.
• Bloquer le script en ligne. Si votre site a une politique de sécurité du contenu (CSP), autorisez le script en ligne avec un nonce ou un hash, ou déplacez-le dans un fichier externe. Voir Content Security Policy.
• ID trop longs. userId ne peut pas dépasser 200 caractères.

Renouveler le secret

Sélectionnez Renouveler le secret sous Utilisateurs connectés dans Paramètres → Widget de chat → Infos visiteur si le secret a pu fuiter. L’ancien secret cesse de fonctionner immédiatement : mettez donc à jour la configuration de votre serveur sans attendre. Si N'accepter que les ID signés est activé, les utilisateurs connectés ne peuvent pas démarrer de conversations tant que votre serveur n’utilise pas le nouveau secret.

Le réutiliser pour les applications et Copilot

Les mêmes userId et userHash fonctionnent dans les SDK mobiles, et Giov Copilot les utilise pour ne s’activer que pour les utilisateurs dont votre serveur se porte garant. Un seul secret couvre les trois.

La référence complète, avec chaque champ, se trouve dans Identifier les visiteurs.