Angemeldete Besucher sicher identifizieren

Wenn ein angemeldeter Kunde den Chat öffnet, sollte Ihr Team wissen, wer er ist. Alles, was Ihre Seite aus dem Browser sendet, kann jedoch vom Benutzer verändert werden. Würde das Widget einer einfachen Benutzer-ID vertrauen, könnte jeder eine fremde ID eingeben und deren Verlauf lesen.

Giov löst das mit einer Signatur. Ihr Server signiert die Benutzer-ID mit einem Geheimnis, das nur Sie und Giov kennen. Die Signatur heißt userHash. Ohne gültige Signatur gilt eine ID nur als Behauptung und wird niemals einem Kontakt zugeordnet.

So funktioniert es

1. Sie erzeugen im Dashboard ein Identitätsgeheimnis und speichern es auf Ihrem Server.
2. Ihr Server berechnet userHash: HMAC-SHA256 der Benutzer-ID, mit dem Geheimnis als Schlüssel, hexadezimal ausgegeben.
3. Ihre Seite übergibt ID und Hash an das Widget.
4. Giov berechnet den Hash erneut und vergleicht. Stimmen beide überein, gehört das Gespräch zu diesem Kunden.

Das Geheimnis verlässt Ihren Server nie. Niemand im Browser kann daher einen gültigen Hash für einen anderen Benutzer erzeugen.

1. Geheimnis erzeugen

1. Öffnen Sie Einstellungen → Chat-Widget → Besucherangaben.
2. Wählen Sie unter Signiergeheimnis die Aktion Geheimnis erzeugen.
3. Kopieren Sie es sofort. Es wird nicht erneut angezeigt. Speichern Sie es im Secret Manager Ihres Servers, etwa als GIOV_IDENTITY_SECRET.

2. userHash auf Ihrem Server berechnen

Verwenden Sie das Geheimnis exakt wie ausgegeben als UTF-8-Text. Decodieren Sie es nicht als Base64. Hashen Sie die Benutzer-ID als Zeichenfolge und geben Sie Hexadezimalzeichen in Kleinschreibung aus.

import { createHmac } from "node:crypto";

// Server only. Read the secret from your server configuration.
const userHash = createHmac("sha256", process.env.GIOV_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");

import hashlib
import hmac
import os

# Server only. Read the secret from your server configuration.
user_hash = hmac.new(
    os.environ["GIOV_IDENTITY_SECRET"].encode("utf-8"),
    str(user.id).encode("utf-8"),
    hashlib.sha256,
).hexdigest()

<?php
// Server only. Read the secret from your server configuration.
$userHash = hash_hmac('sha256', (string) $user->id, getenv('GIOV_IDENTITY_SECRET'));

require "openssl"

user_hash = OpenSSL::HMAC.hexdigest("SHA256", ENV["GIOV_IDENTITY_SECRET"], user.id.to_s)

3. ID und Hash an das Widget übergeben

Geben Sie auf angemeldeten Seiten beide Werte vom Server direkt vor dem Installations-Snippet aus:

<script>
  window.GiovChatSettings = {
    userId: "USER_ID",     // the same id your server hashed
    userHash: "USER_HASH", // computed on your server, never in the browser
    email: "ada@example.com" // optional contact details
  };
</script>
<script src="https://widget.giovchat.app/YOUR_WORKSPACE_ID" async></script>

Sie können email, phone, firstName und lastName im selben Objekt ergänzen. Ihr Team sieht sie am Gespräch. Sobald einer dieser Werte übergeben wird, entfällt das Formular vor dem Chat.

4. Verifizierte Identität verlangen

Sobald Ihr Server überall Hashes sendet, aktivieren Sie Nur signierte IDs akzeptieren unter Einstellungen → Chat-Widget → Besucherangaben. Neue Gespräche mit Benutzer-ID ohne gültigen Hash werden dann abgelehnt. Anonyme Besucher ohne Benutzer-ID können weiterhin chatten.

Was Ihr Team sieht

Fehler, die die Prüfung verhindern

• Abweichende Zeichenfolge hashen. Gehashte ID und übergebene userId müssen Zeichen für Zeichen übereinstimmen. Wandeln Sie numerische IDs an beiden Stellen in Zeichenfolgen um und ergänzen Sie keine Leerzeichen.
• Geheimnis decodieren. Es wird als einfacher Text verwendet. Base64-Decodierung erzeugt einen anderen Schlüssel.
• Werte zu spät setzen. Das Widget liest window.GiovChatSettings einmal beim Start des Loaders. Setzen Sie es vor dem Loader-Script; bei einer Single-Page-App vor dem Einfügen des Loaders.
• Im Browser hashen. Das funktioniert nur, bis jemand das Bundle liest und das Geheimnis findet. Hashen Sie immer auf dem Server.
• Inline-Script blockieren. Erlauben Sie es bei einer Content Security Policy per Nonce oder Hash oder verschieben Sie es in eine externe Datei. Siehe Content Security Policy.
• Zu lange IDs. userId darf höchstens 200 Zeichen enthalten.

Geheimnis wechseln

Wählen Sie bei möglichem Geheimnisverlust Geheimnis wechseln unter Angemeldete Benutzer in Einstellungen → Chat-Widget → Besucherangaben. Das alte Geheimnis wird sofort ungültig; aktualisieren Sie die Serverkonfiguration unmittelbar. Bei aktivem Nur signierte IDs akzeptieren können angemeldete Benutzer keine Gespräche starten, bis Ihr Server das neue Geheimnis nutzt.

Für Apps und Copilot wiederverwenden

Dieselben Werte userId und userHash funktionieren in den mobilen SDKs. Giov Copilot aktiviert sich damit nur für Benutzer, deren Identität Ihr Server bestätigt. Ein Geheimnis deckt alle drei ab.

Die vollständige Referenz mit allen Feldern steht unter Besucher identifizieren.