Identifique visitantes conectados com segurança

Quando um cliente conectado abre o seu chat, sua equipe deveria saber quem ele é. Mas qualquer coisa que a sua página envia pelo navegador pode ser editada por quem a está usando. Se o widget confiasse em um simples ID de usuário, qualquer pessoa poderia digitar o ID de outra e ler o histórico dela.

O Giov resolve isso com uma assinatura. Seu servidor assina o ID do usuário com um segredo que só você e o Giov conhecem. Essa assinatura se chama userHash. Sem uma assinatura válida, um ID de usuário é tratado como uma simples alegação e nunca é vinculado a um contato.

Como funciona

1. Você gera um segredo de identidade no painel e o guarda no seu servidor.
2. Seu servidor calcula o userHash: o HMAC-SHA256 do ID do usuário, com o segredo como chave, em hexadecimal.
3. Sua página passa o ID e o hash para o widget.
4. O Giov recalcula o hash e compara. Se forem iguais, a conversa pertence àquele cliente.

O segredo nunca sai do seu servidor, então ninguém no navegador consegue produzir um hash válido para outro usuário.

1. Gere o segredo

1. Abra Configurações → Widget de chat → Dados do visitante.
2. Em Segredo de assinatura, selecione Gerar segredo.
3. Copie-o imediatamente. Você não poderá vê-lo de novo. Guarde-o no gerenciador de segredos do seu servidor, por exemplo como GIOV_IDENTITY_SECRET.

2. Calcule o userHash no seu servidor

Use o segredo exatamente como foi emitido, como texto UTF-8. Não o decodifique de base64. Faça o hash do ID do usuário como string e gere o resultado em hexadecimal minúsculo.

import { createHmac } from "node:crypto";

// Somente no servidor. Leia o segredo da configuração do seu servidor.
const userHash = createHmac("sha256", process.env.GIOV_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");

import hashlib
import hmac
import os

# Somente no servidor. Leia o segredo da configuração do seu servidor.
user_hash = hmac.new(
    os.environ["GIOV_IDENTITY_SECRET"].encode("utf-8"),
    str(user.id).encode("utf-8"),
    hashlib.sha256,
).hexdigest()

<?php
// Somente no servidor. Leia o segredo da configuração do seu 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. Passe o ID e o hash para o widget

Nas páginas de usuários conectados, renderize os dois valores a partir do seu servidor, logo antes do snippet de instalação:

<script>
  window.GiovChatSettings = {
    userId: "USER_ID",     // o mesmo id que o seu servidor usou no hash
    userHash: "USER_HASH", // calculado no seu servidor, nunca no navegador
    email: "ada@example.com" // dados de contato opcionais
  };
</script>
<script src="https://widget.giovchat.app/YOUR_WORKSPACE_ID" async></script>

Você pode adicionar email, phone, firstName e lastName ao mesmo objeto. Sua equipe os vê junto com a conversa, e passar qualquer um deles dispensa o formulário que antecede o chat.

4. Exija uma identidade verificada

Quando o seu servidor estiver enviando hashes em todo lugar, ative Aceitar só IDs assinados em Configurações → Widget de chat → Dados do visitante. As novas conversas que enviam um ID de usuário sem um hash válido passam a ser rejeitadas. Visitantes anônimos, que não enviam ID de usuário, ainda podem iniciar um chat.

O que sua equipe vê

Erros que quebram a verificação

• Fazer o hash de uma string diferente. O ID cujo hash você calcula e o userId que você envia precisam ser idênticos, caractere por caractere. Converta IDs numéricos em strings nos dois lugares e não adicione espaços.
• Decodificar o segredo. Ele é usado como texto simples. Decodificá-lo de base64 produz uma chave diferente.
• Definir os valores tarde demais. O widget lê window.GiovChatSettings uma única vez, quando o loader é executado. Defina-o antes do script do loader. Em um aplicativo de página única, defina-o antes de adicionar o loader.
• Calcular o hash no navegador. Funciona até alguém ler o seu bundle e encontrar o segredo. Calcule sempre o hash no servidor.
• Bloquear o script inline. Se o seu site tem uma Content Security Policy, permita o script inline com um nonce ou hash, ou mova-o para um arquivo externo. Veja Content Security Policy.
• IDs longos demais. O userId pode ter no máximo 200 caracteres.

Rotacione o segredo

Selecione Rotacionar segredo em Usuários conectados, em Configurações → Widget de chat → Dados do visitante, se o segredo pode ter vazado. O segredo antigo deixa de funcionar imediatamente, então atualize a configuração do seu servidor sem demora. Se Aceitar só IDs assinados estiver ativado, os usuários conectados não poderão iniciar conversas até que o seu servidor use o novo segredo.

Reaproveite-o em apps e no Copilot

O mesmo userId e userHash funcionam nos SDKs para dispositivos móveis, e o Giov Copilot os usa para ser ativado somente para os usuários que o seu servidor garante. Um segredo cobre os três.

A referência completa, com todos os campos, está em Identificar visitantes.