Tracking de eventos

track()

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

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

track devuelve void, no una Promise — los eventos se encolan y se envían en batches en segundo plano. Si necesitas esperar la entrega (raro; el SDK ya hace flush al descargar la página), llama a flush().

• properties es un objeto JSON (Record<string, JsonValue>). Kilden nunca valida ni tipea tus properties — el sobre del evento está tipado, el payload es tuyo.
• options.timestamp (Date | string) retro-fecha el evento. Sin él, el evento se marca cuando se llama a track, y el servidor corrige el desfase del reloj del cliente.
• Los nombres de eventos no tienen schema. Una sola convención se aplica de forma suave: los nombres que empiezan con $ están reservados para eventos del sistema de Kilden. Enviar uno desde track loguea un warning en modo debug pero el evento se envía igual — el SDK nunca rompe tus llamadas.

Cada evento incluye automáticamente properties de contexto: $current_url, $referrer, $session_id, $device_type, $screen_width, $screen_height, $lib, $lib_version, y $utm_source / $utm_medium / $utm_campaign / $utm_term / $utm_content parseadas de la URL. Ver Eventos y properties.

El payload del evento

Esta es la forma de un evento al entrar a la cola — y como lo ven beforeSend y los plugins:

interface EventPayload {
  uuid: string;          // UUID v7, generado por el SDK
  event: string;
  distinct_id: string;
  properties: Properties; // las $-properties de contexto ya vienen mezcladas
  timestamp: string;      // ISO 8601
}

Super properties: register() / unregister()

Las super properties se persisten y se mezclan en cada evento posterior:

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

Sobreviven recargas (en la persistence configurada) y se limpian con reset().

flush()

await kilden.flush();

Envía todo lo que hay en la cola ahora. El único método del cliente que devuelve una Promise.

Leer identificadores

kilden.getDistinctId(); // "anon_018f..." o tu user id después de identify()
kilden.getSessionId();  // el $session_id actual (rota tras 30 min de inactividad)

Opt-out

kilden.optOut();       // persistido: detiene toda captura y tráfico de red
kilden.optIn();        // reactivar
kilden.hasOptedOut();  // boolean

Con el opt-out activo no se captura ni se envía nada, incluidas las cargas de feature flags desde /decide (los valores de flags ya cacheados siguen respondiendo).

group() — reservado

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

El analytics de grupos B2B es parte de la superficie congelada pero aún no está disponible: llamar a group() es un no-op seguro que loguea un warning en modo debug. Existe para que el snippet de instalación nunca tenga que cambiar cuando se lance.