Identificazione degli utenti

L’identificazione degli utenti collega le sessioni di chat anonime ai profili utente reali.

Come funziona

Quando chiami Respondo.identify(), i campi forniti vengono associati alla conversazione. Tutti i campi sono facoltativi — passa solo quelli che hai. Ad esempio, puoi inviare solo userId senza email o nome. Gli agenti di supporto vedono questi dati nel pannello dei dettagli della conversazione.

Parametri#

Proprietà	Tipo	Obbligatorio	Descrizione
email	string	facoltativo	Indirizzo email dell’utente
name	string	facoltativo	Nome visualizzato
userId	string	facoltativo	Il tuo ID utente interno o ID visualizzato — mostrato così com’è nella dashboard
userHash	string	facoltativo	Firma HMAC-SHA256 per la verifica dell’identità
metadata	object	facoltativo	Coppie chiave-valore di campi personalizzati (plan, company, ecc.)
properties	object	facoltativo	Proprietà di contatto personalizzate definite in Agent Settings. Le chiavi devono corrispondere alle definizioni delle proprietà. I valori vengono memorizzati con il prefisso `cp_` e sono filtrabili nell’Inbox.

Esempio: Single Page Appjavascript

// Dopo un accesso riuscito
async function onLogin(user) {
  await authenticateUser(user);

  Respondo.identify({
    email: user.email,
    name: user.fullName,
    userId: user.id,
    metadata: {
      plan: user.subscription.plan,
      company: user.company.name,
      role: user.role,
      signedUp: user.createdAt
    },
    properties: {                        // proprietà di contatto personalizzate
      account_type: user.accountType,    // devono corrispondere alle chiavi di Agent Settings
      industry: user.industry,
      contract_tier: user.tier
    }
  });
}

Con lo snippet di installazione standard puoi chiamare identify() in qualsiasi momento — le chiamate effettuate prima che widget.js finisca di caricarsi vengono messe in coda dallo snippet e rieseguite automaticamente non appena il widget si inizializza. I dati di identità vengono scartati (con un avviso in console) solo se carichi widget.js per conto tuo e chiami identify() senza aver mai chiamato init() — nelle configurazioni manuali chiama sempre prima init().

Visitatori anonimi#

Se non chiami identify(), il widget assegna automaticamente un visitor ID persistente memorizzato in localStorage (chiave respondoai_visitor_id). Nella dashboard, la conversazione appare come Guest · Web widget.

Modalità	Visualizzazione nella dashboard	HMAC richiesto
Nessun `identify()`	Guest · Web widget	No
`identify({ email, name })`	Nome + email mostrati	No — a meno che la Verifica dell’identità non sia abilitata; in tal caso email e nome non firmati vengono rimossi silenziosamente e la sessione resta anonima
`identify({ userId })`	userId mostrato così com’è	No — a meno che la Verifica dell’identità non sia abilitata; in tal caso è richiesto uno `userHash` valido, altrimenti l’identità viene rimossa
`identify({ userId, userHash })`	Identità utente verificata	Sì — verificata crittograficamente

Quando la Verifica dell’identità è abilitata per il canale, qualsiasi identify() che trasporta email o userId senza uno userHash valido viene ripulito lato server e il visitatore resta anonimo — vedi Verifica dell’identità (HMAC) più sotto.

Il visitor ID persiste tra le sessioni sullo stesso browser. Non viene mai inviato a Respondo come identità autenticata — serve solo per la continuità delle conversazioni anonime.

Identificazione con solo userId (senza email o nome)#

Se la tua piattaforma non dispone di email o nomi utente — ad esempio, hai solo un ID visualizzato interno — puoi passare solo userId. Non sono necessari altri campi. La dashboard mostrerà lo userId così com’è nei dettagli della conversazione.

userId + metadata (senza email o nome)javascript

// La tua piattaforma ha solo un ID visualizzato — è sufficiente
Respondo.identify({
  userId: user.displayId,      // es. "USR-4821" — mostrato nella dashboard
  metadata: {                  // contesto aggiuntivo facoltativo
    plan: 'premium',
    region: 'eu-west'
  }
});
// Nessuna email o nome necessari — il widget funziona con il solo userId

Per prevenire la falsificazione dello userId, abbinalo a userHash (vedi Verifica dell’identità più sotto). Senza HMAC, chiunque può passare qualsiasi userId dalla console del browser.

Google Tag Manager / identify() differito#

Quando si integra tramite GTM, i dati dell’utente potrebbero non essere disponibili al caricamento della pagina. Due approcci:

Opzione A: localStorageKey (nessun JS necessario)javascript

// Se la tua piattaforma scrive già l'ID utente in localStorage:
Respondo.init({
  agentId: 'YOUR_AGENT_ID',
  localStorageKey: 'myapp_user_id'  // legge automaticamente localStorage.getItem('myapp_user_id')
});
// Nessuna chiamata a identify() necessaria — il widget rileva lo userId da solo

Opzione B: identify() differito tramite dataLayerjavascript

// 1. Inizializza subito il widget (tag GTM)
Respondo.init({ agentId: 'YOUR_AGENT_ID' });

// 2. Più tardi, quando compaiono i dati utente (es. dal dataLayer o dalla tua app):
var waitForUser = setInterval(function() {
  var uid = localStorage.getItem('myapp_user_id');
  if (uid && window.Respondo && typeof window.Respondo.identify === 'function') {
    clearInterval(waitForUser);
    Respondo.identify({ userId: uid });
  }
}, 500);

localStorageKey viene usato solo se nessun userId è già stato impostato tramite identify(). Le chiamate esplicite a identify() hanno sempre la precedenza.

Verifica dell’identità (HMAC)#

Senza verifica, chiunque potrebbe impersonare un utente passando uno userId o un’ email falsi. La Verifica dell’identità usa HMAC-SHA256 per dimostrare crittograficamente che l’identità dell’utente è stata impostata dal tuo server, non da codice lato client.

Come funziona#

Abilita la Verifica dell’identità nelle impostazioni del tuo canale — otterrai una chiave segreta.
Sul tuo server, calcola HMAC-SHA256(secret, userId) — il secret è la chiave, lo userId è il messaggio — e invia il risultato al frontend. Se identifichi gli utenti solo tramite email (senza userId), firma invece l’email: il payload firmato è lo userId quando è impostato, altrimenti l’email. Se li passi entrambi, firma lo userId; ha la priorità.
Passa l’hash come userHash in Respondo.identify().
Respondo verifica l’hash lato server. Se non è valido, l’identità viene rimossa e l’utente viene trattato come anonimo.

Non esporre mai la tua chiave segreta nel codice frontend. L’HMAC deve essere calcolato sul tuo backend.

Una volta abilitata la verifica, ogni identify() che trasporta userId o email deve includere uno userHash valido — altrimenti i campi di identità vengono rimossi e il visitatore viene trattato come anonimo.

Esempi lato server#

Node.jsjavascript

const crypto = require('crypto');

const SECRET = process.env.RESPONDO_IDENTITY_SECRET;

function generateUserHash(userId) {
  return crypto
    .createHmac('sha256', SECRET)
    .update(userId)
    .digest('hex');
}

// Nel tuo endpoint API:
app.get('/api/respondo-hash', (req, res) => {
  const hash = generateUserHash(req.user.id);
  res.json({ userHash: hash });
});

Pythonpython

import hmac, hashlib, os

SECRET = os.environ['RESPONDO_IDENTITY_SECRET']

def generate_user_hash(user_id: str) -> str:
    return hmac.new(
        SECRET.encode(),
        user_id.encode(),
        hashlib.sha256
    ).hexdigest()

# Nella tua view / endpoint:
user_hash = generate_user_hash(request.user.id)

Gogo

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func GenerateUserHash(userID, secret string) string {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(userID))
    return hex.EncodeToString(mac.Sum(nil))
}

Uso lato frontend#

Con la Verifica dell'identitàjavascript

// Recupera l'hash dal TUO server
const { userHash } = await fetch('/api/respondo-hash').then(r => r.json());

Respondo.identify({
  email: user.email,
  name: user.name,
  userId: user.id,
  userHash: userHash  // firma HMAC-SHA256
});