Nutzeridentifikation

Durch die Identifikation von Nutzern werden anonyme Chat-Sitzungen mit echten Nutzerprofilen verknüpft.

Wie es funktioniert

Wenn Sie Respondo.identify() aufrufen, werden die angegebenen Felder an die Konversation angehängt. Alle Felder sind optional — übergeben Sie nur diejenigen, die Sie haben. Sie können beispielsweise nur userId ohne E-Mail oder Name senden. Mitarbeiter sehen diese Daten im Detailbereich der Konversation.

Parameter#

Eigenschaft	Typ	Erforderlich	Beschreibung
email	string	optional	E-Mail-Adresse des Nutzers
name	string	optional	Anzeigename
userId	string	optional	Ihre interne Nutzer- oder Anzeige-ID — wird unverändert im Dashboard angezeigt
userHash	string	optional	HMAC-SHA256-Signatur zur Identitätsverifizierung
metadata	object	optional	Schlüssel-Wert-Paare benutzerdefinierter Felder (plan, company usw.)
properties	object	optional	Benutzerdefinierte Kontakteigenschaften, die in den Agent-Einstellungen definiert sind. Schlüssel müssen mit den Eigenschaftsdefinitionen übereinstimmen. Werte werden mit dem Präfix `cp_` gespeichert und sind im Posteingang filterbar.

Beispiel: Single-Page-Appjavascript

// Nach erfolgreicher Anmeldung
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: {                        // benutzerdefinierte Kontakteigenschaften
      account_type: user.accountType,    // müssen mit Schlüsseln aus den Agent-Einstellungen übereinstimmen
      industry: user.industry,
      contract_tier: user.tier
    }
  });
}

Mit dem Standard-Installations-Snippet können Sie identify() jederzeit aufrufen — Aufrufe, die erfolgen, bevor widget.js fertig geladen ist, werden vom Snippet in eine Warteschlange gestellt und nach der Initialisierung des Widgets automatisch abgespielt. Identitätsdaten gehen nur dann verloren (mit einer Konsolenwarnung), wenn Sie widget.js selbst laden und identify() aufrufen, bevor jemals init() aufgerufen wurde — rufen Sie bei manuellen Setups immer zuerst init() auf.

Anonyme Besucher#

Wenn Sie identify() nicht aufrufen, weist das Widget automatisch eine dauerhafte Besucher-ID zu, die im localStorage gespeichert wird (Schlüssel respondoai_visitor_id). Im Dashboard erscheint die Konversation als Guest · Web widget.

Modus	Dashboard-Anzeige	HMAC erforderlich
Kein `identify()`	Guest · Web widget	Nein
`identify({ email, name })`	Name + E-Mail angezeigt	Nein — außer die Identitätsverifizierung ist aktiviert; dann werden unsignierte E-Mail/Name stillschweigend entfernt und die Sitzung bleibt anonym
`identify({ userId })`	userId unverändert angezeigt	Nein — außer die Identitätsverifizierung ist aktiviert; dann ist ein gültiger `userHash` erforderlich, sonst wird die Identität entfernt
`identify({ userId, userHash })`	Verifizierte Nutzeridentität	Ja — kryptografisch verifiziert

Wenn die Identitätsverifizierung für den Kanal aktiviert ist, wird jedes identify(), das E-Mail oder userId ohne gültigen userHash überträgt, serverseitig entfernt und der Besucher bleibt anonym — siehe Identitätsverifizierung (HMAC) unten.

Die Besucher-ID bleibt über Sitzungen hinweg im selben Browser erhalten. Sie wird niemals als authentifizierte Identität an Respondo gesendet — sie dient ausschließlich der Kontinuität anonymer Konversationen.

Identifikation nur mit userId (ohne E-Mail oder Name)#

Wenn Ihre Plattform keine E-Mail-Adressen oder Namen der Nutzer hat — Sie beispielsweise nur eine interne Anzeige-ID besitzen — können Sie einfach nur userId übergeben. Keine weiteren Felder sind erforderlich. Das Dashboard zeigt die userId unverändert in den Konversationsdetails an.

userId + metadata (ohne E-Mail oder Name)javascript

// Ihre Plattform hat nur eine Anzeige-ID — das genügt
Respondo.identify({
  userId: user.displayId,      // z. B. „USR-4821“ — im Dashboard angezeigt
  metadata: {                  // optionaler zusätzlicher Kontext
    plan: 'premium',
    region: 'eu-west'
  }
});
// Keine E-Mail und kein Name nötig — das Widget funktioniert allein mit userId

Um das Fälschen der userId zu verhindern, kombinieren Sie sie mit userHash (siehe Identitätsverifizierung unten). Ohne HMAC kann jeder eine beliebige userId aus der Browserkonsole übergeben.

Google Tag Manager / verzögertes identify()#

Beim Einbetten über GTM sind die Nutzerdaten beim Laden der Seite möglicherweise noch nicht verfügbar. Zwei Ansätze:

Option A: localStorageKey (kein JS erforderlich)javascript

// Wenn Ihre Plattform die Nutzer-ID bereits in den localStorage schreibt:
Respondo.init({
  agentId: 'YOUR_AGENT_ID',
  localStorageKey: 'myapp_user_id'  // liest localStorage.getItem('myapp_user_id') automatisch
});
// Kein identify()-Aufruf nötig — das Widget übernimmt die userId von selbst

Option B: verzögertes identify() über dataLayerjavascript

// 1. Widget sofort initialisieren (GTM-Tag)
Respondo.init({ agentId: 'YOUR_AGENT_ID' });

// 2. Später, wenn Nutzerdaten erscheinen (z. B. aus dataLayer oder Ihrer 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 wird nur verwendet, wenn nicht bereits eine userId über identify() gesetzt wurde. Explizite identify()-Aufrufe haben immer Vorrang.

Identitätsverifizierung (HMAC)#

Ohne Verifizierung könnte jeder einen Nutzer imitieren, indem er eine gefälschte userId oder email übergibt. Die Identitätsverifizierung verwendet HMAC-SHA256, um kryptografisch zu beweisen, dass die Identität des Nutzers von Ihrem Server gesetzt wurde und nicht durch clientseitigen Code.

Wie es funktioniert#

Aktivieren Sie die Identitätsverifizierung in Ihren Kanaleinstellungen — Sie erhalten einen geheimen Schlüssel.
Berechnen Sie auf Ihrem Server HMAC-SHA256(secret, userId) — das Secret ist der Schlüssel, die userId die Nachricht — und senden Sie das Ergebnis an das Frontend. Wenn Sie Nutzer ausschließlich per E-Mail identifizieren (ohne userId), signieren Sie stattdessen die E-Mail: Signiert wird die userId, wenn sie gesetzt ist, andernfalls die E-Mail. Übergeben Sie beides, wird die userId signiert; sie hat Vorrang.
Übergeben Sie den Hash als userHash in Respondo.identify().
Respondo verifiziert den Hash serverseitig. Ist er ungültig, wird die Identität entfernt und der Nutzer als anonym behandelt.

Geben Sie Ihren geheimen Schlüssel niemals im Frontend-Code preis. Der HMAC muss auf Ihrem Backend berechnet werden.

Sobald die Verifizierung aktiviert ist, muss jedes identify(), das userId oder email überträgt, einen gültigen userHash enthalten — andernfalls werden die Identitätsfelder entfernt und der Besucher als anonym behandelt.

Serverseitige Beispiele#

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

// In Ihrem API-Endpunkt:
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()

# In Ihrer View / Ihrem Endpunkt:
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))
}

Verwendung im Frontend#

Mit Identitätsverifizierungjavascript

// Den Hash von IHREM Server abrufen
const { userHash } = await fetch('/api/respondo-hash').then(r => r.json());

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