Dokumentacja

Identyfikacja użytkowników

Identyfikacja użytkowników łączy anonimowe sesje czatu z rzeczywistymi profilami.

Jak to działa

Gdy wywołasz Respondo.identify(), podane pola zostają dołączone do rozmowy. Wszystkie pola są opcjonalne — przekaż tylko te, które masz. Na przykład możesz wysłać sam userId bez adresu e-mail czy imienia. Operatorzy wsparcia widzą te dane w panelu szczegółów rozmowy.

Parametry

WłaściwośćTypWymaganeOpis
emailstringopcjonalneAdres e-mail użytkownika
namestringopcjonalneNazwa wyświetlana
userIdstringopcjonalneTwój wewnętrzny identyfikator użytkownika lub identyfikator wyświetlany — pokazywany bez zmian w panelu
userHashstringopcjonalnePodpis HMAC-SHA256 do weryfikacji tożsamości
metadataobjectopcjonalnePary klucz-wartość pól niestandardowych (plan, firma itp.)
propertiesobjectopcjonalneNiestandardowe właściwości kontaktu zdefiniowane w ustawieniach agenta. Klucze muszą odpowiadać definicjom właściwości. Wartości są zapisywane z prefiksem cp_ i można je filtrować w skrzynce odbiorczej.
Przykład: aplikacja jednostronicowa (SPA)javascript
// Po pomyślnym zalogowaniu
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: {                        // niestandardowe właściwości kontaktu
      account_type: user.accountType,    // muszą odpowiadać kluczom z ustawień agenta
      industry: user.industry,
      contract_tier: user.tier
    }
  });
}
Ze standardowym fragmentem instalacyjnym możesz wywoływać identify() w dowolnym momencie — wywołania wykonane, zanim widget.js skończy się ładować, są kolejkowane przez fragment i odtwarzane automatycznie po zainicjalizowaniu widgetu. Dane tożsamości są odrzucane (z ostrzeżeniem w konsoli) tylko wtedy, gdy ładujesz widget.js samodzielnie i wywołasz identify(), zanim kiedykolwiek wywołasz init() — w konfiguracjach ręcznych zawsze najpierw wywołuj init().

Anonimowi odwiedzający

Jeśli nie wywołasz identify(), widget automatycznie przypisze trwały identyfikator odwiedzającego przechowywany w localStorage (klucz respondoai_visitor_id). W panelu rozmowa pojawia się jako Guest · Web widget.

TrybWidok w paneluWymagany HMAC
Bez identify()Guest · Web widgetNie
identify({ email, name })Wyświetlane imię + e-mailNie — chyba że włączono Weryfikację tożsamości; wtedy niepodpisane e-mail/imię są po cichu usuwane, a sesja pozostaje anonimowa
identify({ userId })userId wyświetlany bez zmianNie — chyba że włączono Weryfikację tożsamości; wtedy wymagany jest prawidłowy userHash, w przeciwnym razie tożsamość jest usuwana
identify({ userId, userHash })Zweryfikowana tożsamość użytkownikaTak — zweryfikowana kryptograficznie

Gdy dla kanału włączona jest Weryfikacja tożsamości, każde identify() niosące e-mail lub userId bez prawidłowego userHash jest czyszczone po stronie serwera, a odwiedzający pozostaje anonimowy — zobacz Weryfikacja tożsamości (HMAC) poniżej.

Identyfikator odwiedzającego jest zachowywany między sesjami w tej samej przeglądarce. Nigdy nie jest wysyłany do Respondo jako uwierzytelniona tożsamość — służy wyłącznie do ciągłości anonimowej rozmowy.

Identyfikacja tylko przez userId (bez e-maila i imienia)

Jeśli Twoja platforma nie ma adresów e-mail ani imion użytkowników — na przykład masz tylko wewnętrzny identyfikator wyświetlany — możesz przekazać sam userId. Żadne inne pola nie są potrzebne. Panel pokaże userId bez zmian w szczegółach rozmowy.

userId + metadata (bez e-maila i imienia)javascript
// Twoja platforma ma tylko identyfikator wyświetlany — to wystarczy
Respondo.identify({
  userId: user.displayId,      // np. "USR-4821" — pokazywany w panelu
  metadata: {                  // opcjonalny dodatkowy kontekst
    plan: 'premium',
    region: 'eu-west'
  }
});
// E-mail ani imię nie są potrzebne — widget działa z samym userId
Aby zapobiec podszywaniu się pod userId, połącz go z userHash (zobacz Weryfikacja tożsamości poniżej). Bez HMAC każdy może przekazać dowolny userId z konsoli przeglądarki.

Google Tag Manager / odroczone identify()

Przy osadzaniu przez GTM dane użytkownika mogą być niedostępne w momencie ładowania strony. Dwa podejścia:

Opcja A: localStorageKey (bez pisania JS)javascript
// Jeśli Twoja platforma już zapisuje identyfikator użytkownika do localStorage:
Respondo.init({
  agentId: 'YOUR_AGENT_ID',
  localStorageKey: 'myapp_user_id'  // automatycznie odczytuje localStorage.getItem('myapp_user_id')
});
// Wywołanie identify() nie jest potrzebne — widget sam pobiera userId
Opcja B: odroczone identify() przez dataLayerjavascript
// 1. Zainicjalizuj widget od razu (tag GTM)
Respondo.init({ agentId: 'YOUR_AGENT_ID' });

// 2. Później, gdy pojawią się dane użytkownika (np. z dataLayer lub z Twojej aplikacji):
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 jest używany tylko wtedy, gdy żaden userId nie został jeszcze ustawiony przez identify(). Jawne wywołania identify() zawsze mają pierwszeństwo.

Weryfikacja tożsamości (HMAC)

Bez weryfikacji każdy mógłby podszyć się pod użytkownika, przekazując fałszywy userId lub email. Weryfikacja tożsamości wykorzystuje HMAC-SHA256, aby kryptograficznie udowodnić, że tożsamość użytkownika została ustawiona przez Twój serwer, a nie przez kod po stronie klienta.

Jak to działa

  1. Włącz weryfikację tożsamości w ustawieniach kanału — otrzymasz tajny klucz.
  2. Na swoim serwerze oblicz HMAC-SHA256(secret, userId) — sekret jest kluczem, userId wiadomością — i wyślij wynik do frontendu. Jeśli identyfikujesz użytkowników tylko po e-mailu (bez userId), podpisz zamiast tego e-mail: podpisywanym ładunkiem jest userId, gdy jest ustawiony, w przeciwnym razie e-mail. Jeśli przekazujesz oba, podpisz userId — ma priorytet.
  3. Przekaż hash jako userHash w Respondo.identify().
  4. Respondo weryfikuje hash po stronie serwera. Jeśli jest nieprawidłowy, tożsamość zostaje usunięta, a użytkownik jest traktowany jako anonimowy.
Nigdy nie ujawniaj tajnego klucza w kodzie frontendu. HMAC musi być obliczany na Twoim backendzie.
Po włączeniu weryfikacji każde identify() niosące userId lub email musi zawierać prawidłowy userHash — w przeciwnym razie pola tożsamości są usuwane, a odwiedzający jest traktowany jako anonimowy.

Przykłady po stronie serwera

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

// W Twoim endpointcie API:
app.get('/api/respondo-hash', (req, res) => {
  const hash = generateUserHash(req.user.id);
  res.json({ userHash: hash });
});
Python
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()

# W Twoim widoku / endpointcie:
user_hash = generate_user_hash(request.user.id)
Go
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))
}

Użycie na frontendzie

Z weryfikacją tożsamościjavascript
// Pobierz hash z TWOJEGO serwera
const { userHash } = await fetch('/api/respondo-hash').then(r => r.json());

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