Autenticação de usuários

O widget precisa saber quem está enviando uma sugestão ou abrindo um chamado. Existem dois jeitos de identificar essa pessoa: modo com login (SSO), quando você já sabe quem é o usuário no seu site, e modo visitante, quando não há login e a pessoa se identifica com o próprio email.

Os dois modos podem conviver: sites com área logada usam SSO; visitantes de páginas públicas (landing, blog, documentação) usam o modo visitante. Um site sem sistema de login pode usar só o modo visitante.

Modo com login (SSO via JWT)

Se o seu site já autentica o usuário, você pode repassar essa identidade ao widget para liberar recursos personalizados como votação e histórico de tickets sem pedir nada à pessoa.

Como funciona

Você gera um JWT no seu servidor, assinado com a chave secreta do seu app (HMAC-SHA256). Esse token é passado para o widget pelo atributo data-user-token na tag do script.

Na primeira chamada de inicialização do widget, um registro de usuário é criado automaticamente a partir dos claims do token.

Claims do token

Claim	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador único do usuário no seu sistema.
name	string	Não	Nome de exibição do usuário.
email	string	Não	E-mail do usuário.
avatar_url	string	Não	URL do avatar do usuário.

Gerando o token

A chave secreta (sk_live_...) é encontrada na página de detalhes do app. Nunca exponha a chave secreta no frontend: gere o token sempre no servidor.

PHP

use Firebase\JWT\JWT;

$token = JWT::encode([
    'id' => (string) $user->id,
    'name' => $user->name,
    'email' => $user->email,
], $secretKey, 'HS256');

Node.js

const jwt = require('jsonwebtoken');

const token = jwt.sign({
    id: String(user.id),
    name: user.name,
    email: user.email,
}, secretKey, { algorithm: 'HS256' });

Python

import jwt

token = jwt.encode({
    "id": str(user.id),
    "name": user.name,
    "email": user.email,
}, secret_key, algorithm="HS256")

Usando no widget

Passe o token gerado no atributo data-user-token:

<script
  src="https://pliic.com/widget/v1.js"
  data-app-key="pk_live_xxx"
  data-user-token="eyJhbGciOiJIUzI1NiJ9..."
  async
></script>

Enquanto o data-user-token estiver presente, o widget sempre usa o modo com login, mesmo que o modo visitante esteja habilitado no app.

Modo visitante (verificação por email)

Se o site não envia data-user-token, o widget abre em modo visitante. É o que acontece automaticamente em qualquer site sem sistema de login, ou nas páginas públicas de um site que também tem áreas logadas.

O que a pessoa vê

1. Tela inicial com um subtítulo curto e três entradas: Ver sugestões e votar (abre o mural público, visível mesmo sem nenhuma identificação), Sugerir melhoria (abre o formulário de nova sugestão) e Falar com o suporte (abre um chamado novo ou, se a pessoa já tem chamados, a lista deles). As entradas aparecem conforme os módulos habilitados no app.
2. A pessoa preenche a sugestão ou o chamado normalmente. O email só é pedido no momento de enviar: o rascunho não se perde nesse meio-tempo, e é nesse passo que aparece o aviso de que o email é usado só para acompanhar as respostas.
3. Um código de 6 dígitos é enviado para esse email, válido por 15 minutos. A pessoa digita o código no widget para confirmar. As telas de email e código têm um botão de voltar, caso ela queira corrigir o endereço.
4. Depois de verificado, o registro é salvo automaticamente, sem precisar clicar em enviar de novo.

Quem já enviou algo antes mas não tem sessão ativa (outro navegador ou dispositivo, por exemplo) encontra o link discreto “Já enviou algo? Acessar seus registros” no rodapé da tela inicial.

Só depois da verificação é que a sugestão, o chamado ou o voto realmente é registrado. Enquanto isso, votar, comentar, enviar sugestões e abrir chamados ficam bloqueados para quem ainda não verificou o email.

Sessão do visitante

Depois de verificar o email uma vez, a pessoa não precisa repetir o código a cada visita: o navegador guarda uma sessão válida por 30 dias, renovada automaticamente a cada uso. A tela inicial é sempre a mesma, com sessão ativa ou não: o que muda é que a pessoa já vê os próprios registros ao entrar em Sugestões ou Suporte, sem precisar verificar o email de novo.

Se a mesma pessoa acessar de outro navegador ou dispositivo, ela verifica o email novamente, e cai nos mesmos registros, porque a identidade é o email, não o dispositivo.

Se você gerar uma nova chave secreta para o app (rotacionar a chave), todas as sessões de visitante existentes são encerradas, e as pessoas precisam verificar o email de novo na próxima ação.

Ativando ou desativando

O modo visitante vem ligado por padrão. Para mudar, vá em Apps → seu app → aba Widget → seção “Identidade do visitante” e use o campo “Permitir visitantes por email (código OTP)”.

Desligado, o widget vira um mural de sugestões só leitura para quem não tem data-user-token: dá para ver as sugestões existentes, mas não para votar, comentar, sugerir ou abrir chamado, só o modo com login pode escrever.

Marcando seu chamado como resolvido

Enquanto o chamado estiver aberto ou pendente, aparece na conversa o botão Marcar como resolvido. Use esse botão quando você já resolveu o problema por conta própria e não precisa mais que a equipe continue acompanhando.

Ao confirmar, o chamado passa para o status resolvido, e a equipe vê no histórico da conversa que foi você quem marcou dessa forma, não um atendente.

Um chamado resolvido continua aceitando resposta: se você escrever de novo na conversa, ele reabre automaticamente e volta a aparecer como pendente para a equipe. Não existe botão de reabrir, porque a própria resposta já cumpre esse papel.

Já um chamado encerrado é definitivo. Ele não aceita mais respostas e não reabre, mesmo que você escreva de novo.

Esse mesmo comportamento vale para os chamados abertos pelo botão Precisa de ajuda?, dentro do próprio painel do Pliic.

Qual modo usar

• Site com login: use o modo com login (SSO). A experiência é mais rápida (sem pedir email/código) e cada ação já fica ligada à conta certa.
• Site sem login, ou páginas públicas: deixe o modo visitante ligado (padrão). Qualquer pessoa consegue contribuir sem precisar criar conta no seu produto.
• Quer só receber feedback de usuários logados: desligue o modo visitante. O widget vira board de leitura para anônimos.

Próximos passos

• API de eventos: controle o widget via JavaScript
• Solução de problemas: quando algo não funciona