Eventos pelo servidor
Envie eventos de negócio com identidade, data e ID lógico estáveis.
Enviar um evento
Use analytics:write. O siteId do corpo precisa corresponder ao site da rota, e a URL deve pertencer a um hostname autorizado do site.
import { Pulsant } from '@pulsant/sdk';
const pulsant = new Pulsant({
baseUrl: 'https://api.pulsant.app',
key: process.env.PULSANT_SECRET_KEY!,
siteId: process.env.PULSANT_SITE_ID!,
});
await pulsant.track({
id: 'signup_123456',
name: 'signup',
url: 'https://seusite.com/cadastro',
sessionId: 'session_123456',
properties: { plan: 'basic' },
});Disponibilidade do SDK
@pulsant/sdk é um pacote local do monorepo. Para um backend externo, use HTTP; não há instalação npm pública anunciada neste guia.
Campos e limites
Nome e propriedades devem representar a ação de negócio, sem dados pessoais ou conteúdo de formulários.
| Campo | Regra |
|---|---|
| id | ID lógico estável de 8 a 128 caracteres; reutilize no retry |
| sessionId | Sessão observada; não gere outra por evento |
| occurredAt | ISO 8601; até 72 horas atrás ou 5 minutos no futuro |
| name | Até 80 caracteres |
| properties | Até 32 propriedades primitivas; texto até 500 caracteres |
| Evento completo | Até 8 KiB |
Eventos no navegador
Para eventos de interface, use o tracker instalado no site. Ele cuida da sessão e envia as informações permitidas pelas configurações do site.
await window.pulsant?.('track', 'signup', { plan: 'basic' }, { id: 'signup_123456' });Retries sem duplicação
Reenvie o mesmo ID para a mesma ação. A resposta da coleta informa accepted, duplicate e id. Um evento novo deve receber um novo ID.
{
"accepted": true,
"duplicate": false,
"id": "signup_123456"
}