Identifica a los visitantes con sesión iniciada de forma segura

Cuando un cliente con sesión iniciada abre tu chat, tu equipo debería saber quién es. Pero cualquier cosa que tu página envíe desde el navegador puede ser editada por quien la esté usando. Si el widget confiara en un simple ID de usuario, cualquiera podría escribir el ID de otra persona y leer su historial.

Giov lo resuelve con una firma. Tu servidor firma el ID del usuario con un secreto que solo conocen tú y Giov. La firma se llama userHash. Sin una válida, un ID de usuario se trata como una afirmación y nunca se vincula a un contacto.

Cómo funciona

1. Generas un secreto de identidad en el panel y lo guardas en tu servidor.
2. Tu servidor calcula userHash: el HMAC-SHA256 del ID de usuario, con el secreto como clave, en hexadecimal.
3. Tu página pasa el ID y el hash al widget.
4. Giov vuelve a calcular el hash y lo compara. Si coinciden, la conversación pertenece a ese cliente.

El secreto nunca sale de tu servidor, así que nadie en el navegador puede producir un hash válido para otro usuario.

1. Genera el secreto

1. Abre Configuración → Widget de chat → Datos del visitante.
2. En Secreto de firma, selecciona Generar secreto.
3. Cópialo de inmediato. No volverás a verlo. Guárdalo en el gestor de secretos de tu servidor, por ejemplo como GIOV_IDENTITY_SECRET.

2. Calcula userHash en tu servidor

Usa el secreto exactamente como se emitió, como texto UTF-8. No lo decodifiques de base64. Aplica el hash al ID de usuario como cadena de texto y devuelve hexadecimal en minúsculas.

import { createHmac } from "node:crypto";

// Solo en el servidor. Lee el secreto de la configuración de tu servidor.
const userHash = createHmac("sha256", process.env.GIOV_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");

import hashlib
import hmac
import os

# Solo en el servidor. Lee el secreto de la configuración de tu servidor.
user_hash = hmac.new(
    os.environ["GIOV_IDENTITY_SECRET"].encode("utf-8"),
    str(user.id).encode("utf-8"),
    hashlib.sha256,
).hexdigest()

<?php
// Solo en el servidor. Lee el secreto de la configuración de tu servidor.
$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. Pasa el ID y el hash al widget

En las páginas con sesión iniciada, genera ambos valores desde tu servidor, justo antes del fragmento de instalación:

<script>
  window.GiovChatSettings = {
    userId: "USER_ID",     // el mismo id que calculó tu servidor
    userHash: "USER_HASH", // calculado en tu servidor, nunca en el navegador
    email: "ada@example.com" // datos de contacto opcionales
  };
</script>
<script src="https://widget.giovchat.app/YOUR_WORKSPACE_ID" async></script>

Puedes añadir email, phone, firstName y lastName al mismo objeto. Tu equipo los ve junto a la conversación, y pasar cualquiera de ellos omite el formulario previo al chat.

4. Exige una identidad verificada

Cuando tu servidor envíe hashes en todas partes, activa Aceptar solo IDs firmados en Configuración → Widget de chat → Datos del visitante. Las conversaciones nuevas que envíen un ID de usuario sin un hash válido se rechazarán. Los visitantes anónimos, que no envían ningún ID de usuario, aún pueden iniciar un chat.

Qué ve tu equipo

Errores que rompen la verificación

• Aplicar el hash a una cadena distinta. El ID al que aplicas el hash y el userId que envías deben coincidir carácter por carácter. Convierte los IDs numéricos a cadenas en ambos sitios y no añadas espacios.
• Decodificar el secreto. Se usa como texto plano. Decodificarlo de base64 produce una clave distinta.
• Definir los valores demasiado tarde. El widget lee window.GiovChatSettings una sola vez, cuando se ejecuta el cargador. Defínelo antes del script del cargador. En una aplicación de una sola página, defínelo antes de añadir el cargador.
• Calcular el hash en el navegador. Funciona hasta que alguien lee tu bundle y encuentra el secreto. Calcula siempre el hash en el servidor.
• Bloquear el script en línea. Si tu sitio tiene una Content Security Policy, permite el script en línea con un nonce o un hash, o muévelo a un archivo externo. Consulta Content Security Policy.
• IDs demasiado largos. userId puede tener como máximo 200 caracteres.

Rota el secreto

Selecciona Rotar secreto en Usuarios con sesión iniciada dentro de Configuración → Widget de chat → Datos del visitante si el secreto pudo haberse filtrado. El secreto anterior deja de funcionar al instante, así que actualiza la configuración de tu servidor de inmediato. Si Aceptar solo IDs firmados está activado, los usuarios con sesión iniciada no podrán iniciar conversaciones hasta que tu servidor use el nuevo secreto.

Reutilízalo para apps y Copilot

El mismo userId y userHash funcionan en los SDK móviles, y Giov Copilot los usa para activarse solo con los usuarios que tu servidor avala. Un solo secreto cubre los tres.

La referencia completa, con todos los campos, está en Identificar visitantes.