Rastreando eventos

track()

kilden.track('checkout_completed', { plan: 'pro', total: 49.9 });

track(event: string, properties?: Properties, options?: TrackOptions): void

track retorna void, não uma Promise — os eventos são enfileirados e enviados em batch em segundo plano. Se você precisa aguardar a entrega (raro; o SDK já faz flush no unload da página), chame flush().

• properties é um objeto JSON (Record<string, JsonValue>). O Kilden nunca valida nem tipa suas properties — o envelope do evento é tipado, o payload é seu.
• options.timestamp (Date | string) retroage o evento. Sem ele, o evento é carimbado no momento em que track é chamado, e o servidor corrige o desvio do relógio do cliente.
• Nomes de eventos não têm schema. Uma única convenção é aplicada de forma branda: nomes começando com $ são reservados para eventos de sistema do Kilden. Enviar um deles via track registra um aviso em modo debug, mas o evento é enviado mesmo assim — o SDK nunca quebra suas chamadas.

Todo evento inclui automaticamente properties de contexto: $current_url, $referrer, $session_id, $device_type, $screen_width, $screen_height, $lib, $lib_version, e $utm_source / $utm_medium / $utm_campaign / $utm_term / $utm_content extraídas da URL. Veja Eventos e properties.

O payload do evento

Este é o formato de um evento ao entrar na fila — e como beforeSend e os plugins o enxergam:

interface EventPayload {
  uuid: string;          // UUID v7, gerado pelo SDK
  event: string;
  distinct_id: string;
  properties: Properties; // $-properties de contexto já mescladas
  timestamp: string;      // ISO 8601
}

Super properties: register() / unregister()

Super properties são persistidas e mescladas em todos os eventos subsequentes:

kilden.register({ app_version: '3.2.0', experiment_wave: 'q3' });
kilden.unregister('experiment_wave');

Elas sobrevivem a reloads (na persistence configurada) e são limpas por reset().

flush()

await kilden.flush();

Envia agora tudo o que está na fila. O único método do client que retorna uma Promise.

Lendo identificadores

kilden.getDistinctId(); // "anon_018f..." ou o id do seu usuário após identify()
kilden.getSessionId();  // $session_id atual (rotaciona após 30 min de inatividade)

Opt-out

kilden.optOut();       // persistido: interrompe toda captura e tráfego de rede
kilden.optIn();        // reativa
kilden.hasOptedOut();  // boolean

Com opt-out ativo, nada é capturado nem enviado, incluindo o carregamento de feature flags via /decide (valores de flags já em cache continuam respondendo).

group() — reservado

group(groupType: string, groupKey: string, properties?: Properties): void

O analytics de grupos B2B faz parte da superfície congelada mas ainda não está disponível: chamar group() é um no-op seguro que registra um aviso em modo debug. Ele existe para que o snippet de instalação nunca precise mudar quando o recurso for lançado.