Identificare i visitatori e trasmettere il contesto

Se il Suo sito web sa chi è presente, lo comunichi alla chat. Il Suo team vede così un nome nel pannello operatori invece di «Visitatore 4f2a» e diventano possibili funzioni come i dati dei clienti e il portale clienti.

Il principio: il browser non dimostra nulla. Qualsiasi dichiarazione della pagina tramite identify può essere falsificata da ogni visitatore nella console. Un utente viene considerato confermato solo con una firma calcolata dal Suo server, usando un segreto che non raggiunge mai il browser.

La chiamata nel browser

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

• userId (stringa, consigliato) – il Suo ID permanente per l’utente. Non un indirizzo e-mail, né un numero progressivo che può cambiare.
• email (stringa, facoltativo) – mostrato nel pannello operatori. È confermato solo se anch’esso è stato firmato (sotto).
• name (stringa, facoltativo) – nome visualizzato nel pannello operatori.
• userHash (stringa, obbligatorio per la conferma) – 64 caratteri esadecimali, calcolati sul Suo server.
• exp (intero, consigliato) – scadenza dell’hash in secondi Unix, al massimo 24 ore nel futuro.

Gli altri campi vengono scartati. identify può precedere il caricamento del widget; viene messo in coda e non attiva il caricamento anticipato. I valori vengono trasmessi quando si stabilisce la connessione e, se il widget è già connesso, immediatamente.

Il segreto

Nell’account, in Progetto → Verifica dell’identità, generi il segreto del progetto (permesso: modificare il progetto). È composto da 64 caratteri esadecimali e viene mostrato per intero esattamente una volta, in seguito solo mascherato. Lo inserisca nell’ambiente del Suo server: mai in uno script nel browser, in un’app o in un repository.

Importante per il calcolo: la chiave HMAC è la stringa stessa di 64 caratteri, esattamente come mostrata, non i byte decodificati da essa.

Calcolare la firma

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

Esadecimale minuscolo, 64 caratteri. Con un indirizzo e-mail confermato:

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

Solo nella seconda forma l’indirizzo e-mail viene considerato confermato. Richiede 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()}

Con un indirizzo e-mail (PHP):

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

L’indirizzo deve essere firmato esattamente come viene passato a identify.

Senza script inline (CSP rigorosa)

Se la Sua Content Security Policy non consente script inline, inserisca i valori come dati e chiami identify da un Suo file 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)); }

Nelle app a pagina singola, recuperi i tre valori dal Suo server tramite fetch dopo l’accesso.

Che cosa verifica il server

• exp è un intero (secondi Unix), si trova nel futuro e dista al massimo 24 ore (più 5 minuti di tolleranza).
• L’hash corrisponde a userId + "." + exp (o alla forma con e-mail). Le lettere maiuscole nell’hash sono tollerate.
• Il confronto avviene a tempo costante.

Un utente è confermato e con verifica recente se ha un hash valido e exp. Solo allora può accedere ai dati dei clienti e al portale clienti.

Forma precedente senza exp: userHash = HMAC_SHA256(secret, userId) è ancora accettato come confermato, ma non come verifica recente: basta per la cronologia delle conversazioni e la visualizzazione nel pannello operatori, non per i dati dei clienti. Aggiorni le integrazioni esistenti alla forma con exp.

Quando la verifica fallisce

La chat continua a funzionare, ma in forma anonima. Il widget riceve l’errore auth_failed con il motivo in detail.reason:

• no_hash – manca userHash.
• no_secret – non è stato configurato alcun segreto per il progetto.
• bad_exp – exp non è un intero valido in secondi (spesso sono stati passati millisecondi).
• expired – exp è nel passato (pagina aperta da molto tempo, orologio del server errato).
• exp_too_far – exp dista più di 24 ore nel futuro.
• bad_hash – l’hash non corrisponde: segreto errato, ordine errato, userId firmato come numero invece che come stringa, e-mail scritta diversamente.

Nella scheda Rete degli strumenti per sviluppatori, il motivo si trova nella trama error della connessione WebSocket; init_ok.identity mostra verified e reason.

Non esiste un’impostazione «consenti solo visitatori confermati»: i visitatori non confermati chattano sempre come anonimi.

Ruotare il segreto

• Genera nuovo segreto: quello precedente rimane valido per altre 24 ore. Inserisca quello nuovo sui Suoi server entro questo periodo.
• Rimuovi: rende entrambi immediatamente non validi. Tutti gli utenti vengono quindi considerati non confermati finché non viene configurato un nuovo segreto.

Cambiare utente e uscire

• Se chiama identify con un utente diverso (ad esempio dopo il cambio di account in una SPA), il widget separa la bozza del messaggio da quella dell’utente precedente.
• Non esiste un comando dedicato per uscire. L’identità vale solo per la visualizzazione corrente della pagina: dopo l’uscita, fornisca pagine senza identify. Conversazione e ID del visitatore rimangono nel browser; se su un dispositivo condiviso non deve più essere visibile nulla, il visitatore può eliminare i propri dati nel widget.

Trasmettere il contesto

Oltre all’identità, la Sua pagina può comunicare all’assistente e al Suo team che cosa sta succedendo in quel momento, ad esempio quale prodotto viene mostrato o che cosa c’è nel carrello. Questo avviene tramite track:

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

Vengono acquisiti solo questi campi; tutto il resto viene scartato:

• Pagina: url, path, title, referrer, page_type, landing_path
• Prodotto: product_id, variant_id, category, price, currency, in_stock
• Carrello: cart_value, cart_items
• Campagna: utm_source, utm_medium, utm_campaign, gclid, msclkid, fbclid
• Segnali: intent, intent_confidence, rage_score, scroll_pct, dwell_ms

Il widget registra già autonomamente indirizzo, titolo, referrer e parametri della campagna a ogni cambio di pagina. Il contesto viene trasmesso solo con il consenso (Integrazione della protezione dei dati). Non inserisca dati personali in questi campi: a questo serve identify.

App mobili

In un’app, trasmetta l’identità tramite JavaScript dopo il caricamento della WebView, mai tramite l’indirizzo. Anche qui l’hash viene calcolato sul Suo server, non nell’app: App mobili.

Prosegua: Endpoint per i dati dei clienti · SPA e cambi di pagina