Bezoekers identificeren en context doorgeven

Als uw website weet wie er is, vertel dat dan aan de chat. Uw team ziet in het agentenpaneel dan een naam in plaats van “Bezoeker 4f2a” en functies zoals klantgegevens en het klantportaal worden daardoor pas mogelijk.

Het principe: de browser bewijst niets. Alles wat een pagina via identify beweert, kan elke bezoeker in de console vervalsen. Een gebruiker geldt alleen als bevestigd met een handtekening die uw server heeft berekend met een geheim dat nooit de browser bereikt.

De aanroep in de browser

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

• userId (string, aanbevolen) — uw eigen blijvende ID voor de gebruiker. Geen e-mailadres, geen volgnummer dat kan veranderen.
• email (string, optioneel) — getoond in het agentenpaneel. Alleen bevestigd als het ook is ondertekend (hieronder).
• name (string, optioneel) — weergavenaam in het agentenpaneel.
• userHash (string, vereist voor bevestiging) — 64 hextekens, berekend op uw server.
• exp (integer, aanbevolen) — vervaltijd van de hash in Unix-seconden, maximaal 24 uur in de toekomst.

Andere velden worden verworpen. identify mag worden aangeroepen voordat de widget geladen is; de aanroep gaat in de wachtrij en veroorzaakt geen vroegtijdig laden. De waarden gaan mee bij het verbinden en, als de widget al verbonden is, direct.

Het geheim

In uw account onder Project → Identiteitsverificatie genereert u het geheim van het project (recht: project bewerken). Het bestaat uit 64 hextekens en wordt precies één keer volledig getoond, daarna alleen gemaskeerd. Zet het in de omgeving van uw server — nooit in een browserscript, een app of een repository.

Belangrijk voor de berekening: de HMAC-sleutel is de string van 64 tekens zelf, precies zoals getoond — niet de daaruit gedecodeerde bytes.

De handtekening berekenen

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

Hex in kleine letters, 64 tekens. Met een bevestigd e-mailadres:

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

Alleen in de tweede vorm geldt het e-mailadres als bevestigd. Daarvoor is exp vereist.

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()}

Met een e-mailadres (PHP):

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

Het adres moet precies worden ondertekend zoals u het aan identify doorgeeft.

Zonder inline script (strenge CSP)

Als uw Content Security Policy geen inline scripts toestaat, voert u de waarden als gegevens uit en roept u identify vanuit een eigen scriptbestand aan:

<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)); }

In single-page-apps haalt u de drie waarden na het aanmelden met fetch bij uw server op.

Wat de server controleert

• exp is een geheel getal (Unix-seconden), ligt in de toekomst en maximaal 24 uur vooruit (plus 5 minuten tolerantie).
• De hash komt overeen met userId + "." + exp (of de vorm met e-mail). Hoofdletters in de hash worden geaccepteerd.
• De vergelijking gebeurt in constante tijd.

Bevestigd en actueel is een gebruiker met een geldige hash en exp. Alleen dan krijgt die klantgegevens en het klantportaal.

Oudere vorm zonder exp: userHash = HMAC_SHA256(secret, userId) wordt nog steeds als bevestigd geaccepteerd, maar niet als actueel — voldoende voor de gespreksgeschiedenis en weergave in het agentenpaneel, niet voor klantgegevens. Zet bestaande integraties om naar de vorm met exp.

Als de controle mislukt

De chat blijft werken, maar anoniem. De widget ontvangt de fout auth_failed met een reden in detail.reason:

• no_hash — userHash ontbreekt.
• no_secret — voor het project is geen geheim ingesteld.
• bad_exp — exp is geen geldig geheel getal in seconden (vaak: milliseconden doorgegeven).
• expired — exp ligt in het verleden (pagina lang open, onjuiste serverklok).
• exp_too_far — exp ligt meer dan 24 uur in de toekomst.
• bad_hash — de hash komt niet overeen: verkeerd geheim, verkeerde volgorde, userId als getal in plaats van string ondertekend, e-mail anders geschreven.

Op het netwerktabblad van de ontwikkelaarstools staat de reden in het frame error van de WebSocket-verbinding; init_ok.identity toont verified en reason.

Er is geen instelling “alleen bevestigde bezoekers toestaan”: onbevestigde bezoekers chatten altijd anoniem.

Het geheim vernieuwen

• Nieuw geheim genereren: het vorige blijft nog 24 uur geldig. Voer het nieuwe binnen die tijd op uw servers in.
• Verwijderen: maakt beide direct ongeldig. Alle gebruikers gelden dan als onbevestigd totdat een nieuw geheim is ingesteld.

Gebruiker wisselen en afmelden

• Als u identify met een andere gebruiker aanroept (bijvoorbeeld na wisselen van account in een SPA), scheidt de widget het invoerconcept van de vorige gebruiker.
• Er is geen aparte afmeldopdracht. De identiteit geldt alleen voor het huidige paginabezoek: lever na het afmelden pagina’s zonder identify. Gesprek en bezoekers-ID blijven in de browser bewaard; als een gedeeld apparaat niets meer mag tonen, kan de bezoeker de gegevens in de widget verwijderen.

Context doorgeven

Naast de identiteit kan uw pagina de assistent en uw team vertellen wat er nu gebeurt — bijvoorbeeld welk product wordt getoond of wat in de winkelmand zit. Dat werkt via track:

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

Alleen deze velden worden overgenomen; al het overige wordt verworpen:

• Pagina: url, path, title, referrer, page_type, landing_path
• Product: product_id, variant_id, category, price, currency, in_stock
• Winkelmand: cart_value, cart_items
• Campagne: utm_source, utm_medium, utm_campaign, gclid, msclkid, fbclid
• Signalen: intent, intent_confidence, rage_score, scroll_pct, dwell_ms

Adres, titel, referrer en campagneparameters legt de widget sowieso bij elke paginawisseling zelf vast. Context wordt alleen met toestemming doorgestuurd (Privacyintegratie). Zet geen persoonsgegevens in deze velden — daarvoor is identify bedoeld.

Mobiele apps

In een app geeft u de identiteit na het laden van de WebView via JavaScript door, nooit via het adres. Ook hier wordt de hash op uw server berekend, niet in de app: Mobiele apps.

Volgende: Klantgegevensendpoint · SPA en paginawisselingen