Eventos e propriedades
Eventos são imutáveis
Seção intitulada “Eventos são imutáveis”Um evento congela suas propriedades no momento da captura. Nada o reescreve depois — nem merges de identidade, nem atualizações de traits, nem decisões de enforcement. Se o plano de uma pessoa muda, a pessoa muda; os eventos que ela enviou enquanto estava no plano antigo continuam dizendo o plano antigo. Essa é a divisão: eventos são história, pessoas são estado.
Todo evento carrega:
| Campo | O que é |
|---|---|
uuid |
UUID v7 gerado pelo cliente. A chave de idempotência: o pipeline deduplica por ela, e é por isso que retries em qualquer camada são seguros |
event |
O nome. Seus nomes são livres; nomes com prefixo $ são do sistema |
distinct_id |
Quem o executou, conforme conhecido no momento da captura |
properties |
JSON arbitrário. O Kilden nunca o valida nem o tipa — o envelope é tipado, o payload é seu por design |
timestamp |
Quando aconteceu (fornecido pelo cliente, corrigido para desvio de relógio usando o sent_at do batch) |
O namespace $
Seção intitulada “O namespace $”Nomes que começam com $ — eventos e propriedades — são reservados para o sistema. O SDK avisa em modo debug se você fizer track() de um deles, mas o entrega mesmo assim: o namespace é uma convenção, nunca um motivo para descartar seus dados.
Eventos de sistema que você verá no seu stream:
| Evento | Emitido por |
|---|---|
$pageview, $pageleave |
SDK, automaticamente (incluindo mudanças de rota em SPAs) |
$autocapture |
Autocapture: cliques, submits, changes, descritos por $event_type e $elements |
$identify |
identify() — carrega $anon_distinct_id para a vinculação de identidade |
$set, $set_once |
Atualizações de traits da pessoa |
$feature_flag_called |
Primeira leitura de flag por sessão — $flag_key, $flag_value (exposições) |
$session_recording_started |
Início de gravação de replay |
$email_sent, $email_delivered, $email_opened, $email_clicked, $email_bounced, $email_complained |
Campanhas e os webhooks do provedor de email |
Propriedades de contexto carimbadas em todo evento do SDK: $current_url, $referrer, $session_id, $device_type, $screen_width, $screen_height, $lib, $lib_version, $utm_source, $utm_medium, $utm_campaign, $utm_term, $utm_content.
Um único caminho de escrita
Seção intitulada “Um único caminho de escrita”Todo evento — navegador, backend, webhook de email, até os eventos internos do próprio Kilden — entra pelo mesmo endpoint de capture e pelo mesmo pipeline. Não há portas laterais, e é isso que faz as garantias (dedup, resolução de identidade, níveis de confiança) valerem para tudo de maneira uniforme.
Sessões
Seção intitulada “Sessões”O SDK mantém $session_id (UUID v7) em todo evento, rotacionando-o após 30 minutos de inatividade. Sessões amarram eventos, dedupe de exposições de feature flags e session replay — uma gravação sempre pode ser cruzada 1:1 com os eventos da sua sessão.