Identifier les visiteurs et transmettre du contexte

Si votre site sait qui le visite, indiquez-le au chat. Votre équipe voit alors un nom dans l’espace agents au lieu de « Visiteur 4f2a », et des fonctions comme les données clients et le portail client deviennent possibles.

Le principe : le navigateur ne prouve rien. Tout visiteur peut falsifier dans la console ce qu’une page déclare via identify. Un utilisateur n’est considéré comme confirmé qu’avec une signature calculée par votre serveur, au moyen d’un secret qui n’atteint jamais le navigateur.

L’appel dans le navigateur

ReactiveChat('identify', {
  userId:   '4711',
  email:    'kim@example.com',
  name:     'Kim Berger',
  userHash: '9c1f…',
  exp:      1792503600
});

• userId (chaîne, recommandé) – votre identifiant permanent de l’utilisateur. Pas une adresse e-mail, ni un numéro séquentiel susceptible de changer.
• email (chaîne, facultatif) – affiché dans l’espace agents. N’est confirmé que s’il a aussi été signé (ci-dessous).
• name (chaîne, facultatif) – nom affiché dans l’espace agents.
• userHash (chaîne, obligatoire pour la confirmation) – 64 caractères hexadécimaux, calculés sur votre serveur.
• exp (entier, recommandé) – expiration du hachage en secondes Unix, au maximum 24 heures dans le futur.

Les autres champs sont écartés. identify peut être appelé avant le chargement du widget ; il entre dans la file de commandes sans déclencher de chargement anticipé. Les valeurs sont transmises à l’établissement de la connexion ou immédiatement si le widget est déjà connecté.

Le secret

Dans votre compte, sous Projet → Vérification d’identité, vous générez le secret du projet (autorisation : modifier le projet). Il se compose de 64 caractères hexadécimaux et n’est affiché en entier qu’une seule fois, puis uniquement masqué. Placez-le dans l’environnement de votre serveur, jamais dans un script du navigateur, une application ou un dépôt.

Important pour le calcul : la clé HMAC est la chaîne de 64 caractères elle-même, exactement telle qu’elle est affichée, pas les octets décodés à partir de celle-ci.

Calculer la signature

userHash = hex( HMAC_SHA256( secret, userId + "." + exp ) )

Hexadécimal en minuscules, 64 caractères. Avec une adresse e-mail confirmée :

userHash = hex( HMAC_SHA256( secret, userId + "." + exp + "." + email ) )

L’adresse e-mail n’est considérée comme confirmée que dans la seconde forme. Celle-ci exige exp.

PHP :

<?php
$geheim   = getenv('RC_IDENT_SECRET');      // 64 hex characters from the account
$userId   = (string) $kunde->id;
$exp      = time() + 3600;                  // at most 24 h
$userHash = hash_hmac('sha256', $userId . '.' . $exp, $geheim);
?>
<script nonce="<?= $cspNonce ?>">
  ReactiveChat('identify', {
    userId: <?= json_encode($userId) ?>,
    userHash: <?= json_encode($userHash) ?>,
    exp: <?= (int) $exp ?>
  });
</script>

Node.js :

const crypto = require('crypto');

function rcIdentitaet(kunde) {
  const userId = String(kunde.id);
  const exp = Math.floor(Date.now() / 1000) + 3600;
  const userHash = crypto.createHmac('sha256', process.env.RC_IDENT_SECRET)
    .update(userId + '.' + exp)
    .digest('hex');
  return { userId, userHash, exp };
}

Python :

import hmac, hashlib, os, time

def rc_identitaet(kunde_id: str) -> dict:
    exp = int(time.time()) + 3600
    msg = f"{kunde_id}.{exp}".encode()
    key = os.environ["RC_IDENT_SECRET"].encode()   # the hex string as text
    return {"userId": kunde_id, "exp": exp,
            "userHash": hmac.new(key, msg, hashlib.sha256).hexdigest()}

Avec une adresse e-mail (PHP) :

$userHash = hash_hmac('sha256', $userId . '.' . $exp . '.' . $email, $geheim);

L’adresse doit être signée exactement telle que vous la transmettez à identify.

Sans script en ligne (CSP stricte)

Si votre Content Security Policy n’autorise pas les scripts en ligne, produisez les valeurs sous forme de données et appelez identify depuis votre propre fichier de script :

<meta name="rc-ident" content='{"userId":"4711","userHash":"9c1f…","exp":1792503600}'>

// /js/chat-ident.js
var m = document.querySelector('meta[name="rc-ident"]');
if (m) { ReactiveChat('identify', JSON.parse(m.content)); }

Dans les applications monopages, récupérez les trois valeurs auprès de votre serveur via fetch après la connexion.

Ce que le serveur vérifie

• exp est un entier (secondes Unix), se situe dans le futur et au maximum 24 heures à l’avance (plus 5 minutes de tolérance).
• Le hachage correspond à userId + "." + exp (ou à la forme avec e-mail). Les majuscules dans le hachage sont tolérées.
• La comparaison se fait en temps constant.

Un utilisateur est confirmé avec une preuve récente s’il possède un hachage valide et exp. Ce n’est qu’alors qu’il accède aux données clients et au portail client.

Ancienne forme sans exp : userHash = HMAC_SHA256(secret, userId) reste acceptée comme confirmée, mais pas comme récente ; elle suffit pour l’historique des conversations et l’affichage dans l’espace agents, pas pour les données clients. Passez les intégrations existantes à la forme avec exp.

Quand la vérification échoue

Le chat continue de fonctionner, mais anonymement. Le widget reçoit l’erreur auth_failed avec une raison dans detail.reason :

• no_hash – userHash est absent.
• no_secret – aucun secret n’a été configuré pour le projet.
• bad_exp – exp n’est pas un entier valide en secondes (souvent : des millisecondes ont été transmises).
• expired – exp se situe dans le passé (page ouverte depuis longtemps, horloge du serveur incorrecte).
• exp_too_far – exp se situe à plus de 24 heures dans le futur.
• bad_hash – le hachage ne correspond pas : mauvais secret, mauvais ordre, userId signé comme nombre au lieu d’une chaîne, e-mail écrit différemment.

Dans l’onglet Réseau des outils de développement, la raison figure dans la trame error de la connexion WebSocket ; init_ok.identity affiche verified et reason.

Il n’existe aucun réglage « autoriser uniquement les visiteurs confirmés » : les visiteurs non confirmés discutent toujours en tant que visiteurs anonymes.

Rotation du secret

• Générer un nouveau secret : l’ancien reste valable pendant encore 24 heures. Configurez le nouveau sur vos serveurs dans ce délai.
• Supprimer : invalide immédiatement les deux secrets. Tous les utilisateurs sont alors considérés comme non confirmés jusqu’à la configuration d’un nouveau secret.

Changement d’utilisateur et déconnexion

• Si vous appelez identify avec un utilisateur différent (par exemple après un changement de compte dans une SPA), le widget sépare le brouillon de saisie de l’utilisateur précédent.
• Il n’existe aucune commande de déconnexion dédiée. L’identité s’applique uniquement à la page actuellement consultée : après la déconnexion, servez des pages sans identify. La conversation et l’identifiant du visiteur sont conservés dans le navigateur ; si un appareil partagé ne doit plus rien afficher, le visiteur peut supprimer ses données dans le widget.

Transmettre du contexte

Outre l’identité, votre page peut indiquer à l’assistant et à votre équipe ce qui se passe à cet instant, par exemple quel produit est affiché ou ce que contient le panier. Cela se fait via track :

ReactiveChat('track', 'warenkorb', {
  page_type: 'cart',
  cart_value: 129.80,
  cart_items: 3,
  currency: 'EUR'
});

Seuls les champs suivants sont repris ; tout le reste est écarté :

• Page : url, path, title, referrer, page_type, landing_path
• Produit : product_id, variant_id, category, price, currency, in_stock
• Panier : cart_value, cart_items
• Campagne : utm_source, utm_medium, utm_campaign, gclid, msclkid, fbclid
• Signaux : intent, intent_confidence, rage_score, scroll_pct, dwell_ms

Le widget relève déjà lui-même l’adresse, le titre, le référent et les paramètres de campagne à chaque changement de page. Le contexte n’est transmis qu’avec consentement (Intégration de la confidentialité). N’inscrivez pas de données personnelles dans ces champs ; identify est prévu pour cela.

Applications mobiles

Dans une application, transmettez l’identité par JavaScript après le chargement de la WebView, jamais via l’adresse. Là aussi, le hachage est calculé sur votre serveur, pas dans l’application : Applications mobiles.

Suite : Point de terminaison des données clients · SPA et changements de page