Todos los métodos, opciones y eventos automáticos del SDK de JavaScript de LaunchPulse.

El SDK de JavaScript es @basekick-labs/launchpulse — actualmente v0.1.2, licencia MIT, sin dependencias, alrededor de 1,9 kB gzip. Esta página cubre toda la API. Si solo quieres empezar a medir, arranca por Instalación.

Cómo cargar el SDK

El paquete incluye un build ESM en dist/lp.mjs y uno IIFE en dist/lp.js. El build IIFE también lo sirve el collector directamente, y ambos están en unpkg y jsDelivr.

<script src="https://collector.launchpulse.dev/lp.js"></script>
<script>LaunchPulse.init("lp_pub_yourkey");</script>

npm i @basekick-labs/launchpulse

import { LaunchPulse } from "@basekick-labs/launchpulse";

La etiqueta de script define window.LaunchPulse. Después de que corre init(), la instancia también queda disponible como window.lp.

Métodos

Llamada	Comportamiento
`LaunchPulse.init(publicKey, options?)`	Establece la identidad, dispara un `$pageview` inicial, intercepta la navegación de SPA y registra los handlers de envío. Devuelve la instancia y define `window.lp`
`lp.track(name, properties?)`	Envía un evento personalizado. Los nombres que empiezan con `$` se rechazan con una advertencia en consola
`lp.identify(userId)`	Define el user id (se guarda en la cookie) y emite un evento `$identify`
`lp.reset()`	Borra el user id y rota tanto el visitor id como el session id
`lp.track_pageview()`	Envía un `$pageview` manualmente

init(publicKey, options?)

Llámalo una vez por carga de página. Devuelve la instancia, así que puedes guardarla en lugar de usar window.lp:

const lp = LaunchPulse.init("lp_pub_yourkey");
lp.track("signup_started");

Tu clave pública es lp_pub_ seguido de 22 caracteres base58. Está diseñada para viajar en el código del cliente: ponerla en tu HTML o en tu bundle es seguro y es lo esperado. La clave secreta, aparte, es para eventos desde el servidor y nunca debe aparecer en el navegador.

Opciones:

Opción	Tipo	Significado
`collector`	string	URL base del collector. Los eventos van por POST a `${collector}/e`. Defínela solo si haces self-hosting
`cookieDomain`	string	Por ejemplo `.yourapp.com`, para compartir identidad entre subdominios. Normalmente la provee el collector de forma automática. Sin valor, la cookie queda limitada al host
`debug`	boolean	Marca los eventos como debug. Los eventos de debug nunca se cuentan

El collector por defecto es https://collector.launchpulse.dev, así que puedes omitir collector salvo que tengas el tuyo.

Sobre cookieDomain: el SDK no incluye ninguna lista de sufijos públicos, lo que significa que nunca puede asignarle a tu cookie un alcance equivocado como .co.uk. El valor que usa viene del collector, o del que le pases explícitamente.

track(name, properties?)

lp.track("plan_upgraded", { plan: "pro", seats: 3 });

Los nombres de evento que empiezan con $ están reservados. Si pasas uno, el SDK rechaza la llamada y advierte en consola. En Registrar eventos hay recomendaciones de nomenclatura.

Las propiedades las valida el collector, y violar un solo límite rechaza el evento completo:

Límite	Valor
Máximo de propiedades por evento	64
Largo máximo de clave	64 caracteres
Caracteres permitidos en claves	letras, dígitos, `_`, `.`, `-`
Largo máximo de valor string	1024 caracteres
Profundidad máxima de anidamiento	3
Máximo de entradas por arreglo/objeto	32
Máximo de JSON serializado	8192 bytes

Dos claves de propiedad son la excepción a la regla del $: $revenue y $currency. Mira Medir ingresos. Cualquier otra clave de propiedad con $ rechaza el evento.

identify(userId)

lp.identify("user_8f21c");

Define el user id, lo guarda en la cookie y emite un evento $identify. El SDK advierte en consola si el valor parece una dirección de correo: usa un id interno de usuario, nunca datos personales. El detalle completo está en Identificar usuarios.

reset()

lp.reset();

Borra el user id y rota tanto el visitor id como el session id. Llámalo al cerrar sesión y en dispositivos compartidos.

track_pageview()

lp.track_pageview();

Envía un $pageview manualmente. Rara vez lo necesitas: init() dispara uno y la navegación de SPA ya está cubierta.

Eventos automáticos

Hay dos eventos que se envían solos, y son los únicos nombres reservados que acepta el collector:

$pageview se dispara en init() y en la navegación de SPA. El SDK intercepta history.pushState e history.replaceState, más popstate. Las vistas se deduplican por ruta más query string. Esa deduplicación es clave: las SPA — sobre todo Next.js — llaman a replaceState todo el tiempo para manejar estado de la misma página, y disparar en cada llamada inflaría muchísimo tu conteo de vistas.

$identify lo emite identify().

Cualquier otro nombre de evento que empiece con $ es rechazado por el collector.

Transporte

Útil cuando estás depurando en la pestaña de red.

Los eventos se encolan y se envían con navigator.sendBeacon, usando un Blob text/plain. Si el beacon falla, o el payload supera los 60.000 bytes, el SDK cae de vuelta a fetch(..., { keepalive: true }).

El content type text/plain es deliberado. Está en la lista segura de CORS, así que la petición cuenta como “simple” y no necesita preflight. application/json forzaría un preflight que sendBeacon no puede resolver entre orígenes, y tus eventos desaparecerían en silencio.

La cola se vacía ante cualquiera de estas condiciones:

un temporizador de 1 segundo
10 eventos encolados
pagehide
visibilitychange a hidden

El endpoint de lotes del navegador es POST ${collector}/e con un cuerpo { "k": "lp_pub_...", "events": [ ... ] }.

Qué viaja con cada evento

La identidad y la atribución se adjuntan automáticamente, desde la cookie _lp_vid: visitor id, session id, user id si está definido, atribución de primer contacto, atribución de sesión y parámetros UTM. En Identificar usuarios están los campos y las duraciones exactas, y en Fuentes cómo se clasifica la atribución.

La IP del cliente se usa solo para derivar un país y luego se descarta. Nunca se almacena.

Depuración

Usa debug: true para marcar los eventos como debug. Aparecen mientras pruebas, pero nunca se cuentan:

LaunchPulse.init("lp_pub_yourkey", { debug: true });

Para confirmar que están llegando datos reales, usa el registro de eventos. Ten en cuenta que la API de ingesta devuelve un 2xx uniforme incluso para claves desconocidas o revocadas, así que un 200 en la pestaña de red no prueba que tu clave sea válida. Solo verlo en el registro lo prueba.

Si no aparece nada, Solución de problemas repasa las causas habituales.

Referencia del SDK