SDK web

El SDK web de Kixo registra automáticamente clics, páginas vistas, sesiones, errores, profundidad de desplazamiento, Web Vitals, clics de rabia, clics muertos y datos de mapas de calor con una integración de una sola línea. La supervisión de peticiones de red está disponible como opción. Se distribuye como módulo ES nativo y funciona en navegadores modernos.

Instalación

Etiqueta script (CDN)

Añade el fragmento antes de la etiqueta de cierre </head>. Fíjate en type="module": es obligatorio porque el SDK es un módulo ES. La reproducción de sesiones se divide en un bloque de grabación con la misma versión, que solo se carga cuando replay ya está activado, así que el paquete base sigue siendo pequeño mientras replay está desactivado.

html

<script
  type="module"
  src="https://cdn.kixo.io/kixo.min.js?project_id=YOUR_PROJECT_ID&api_key=YOUR_API_KEY">
</script>

Nota

El SDK lee project_id y api_key de la URL del script y se inicializa. Si quieres configurar opciones en el código de la aplicación, quita los parámetros de la URL y llama a Kixo.init({...}); el objeto global Kixo estará disponible cuando se cargue el módulo.

html

<script type="module" src="https://cdn.kixo.io/kixo.min.js"></script>
<script type="module">
  Kixo.init({
    projectId: 'YOUR_PROJECT_ID',
    apiKey:    'YOUR_API_KEY',
  });
</script>

npm

Úsalo cuando quieras configurar opciones en el código de la aplicación en lugar de hacerlo en la URL del script. Expone la misma API Kixo que la integración por CDN.

bash

npm install @kixo.io/web

import Kixo from '@kixo.io/web';

Kixo.init({
  projectId: 'YOUR_PROJECT_ID',
  apiKey: 'YOUR_API_KEY',
});

Plataformas sin código

Si estás creando con un generador con AI como Lovable, Bolt, v0 o Replit, pega el fragmento de la etiqueta script directamente en el chat del generador o en sus ajustes de inyección de código. La mayoría permiten añadir scripts al <head> de tu sitio.

Configuración

La integración de dos líneas usa los valores locales predeterminados de analítica que aparecen abajo. La supervisión de peticiones sigue siendo opcional. Session replay no forma parte de Kixo.init() a propósito: su activación, muestreo, privacidad, duración y opciones de captura se controlan únicamente desde el panel del proyecto.

Kixo.init({
  projectId: 'YOUR_PROJECT_ID',     // required
  apiKey:    'YOUR_API_KEY',         // required

  // Per-tracker toggles — all default to true except network.
  autoTrack: {
    pageViews:   true,
    clicks:      true,
    scrollDepth: true,
    sessions:    true,
    forms:       true,
    network:     false,     // opt in only when you need request telemetry
    errors:      true,
    performance: true,
    rageClicks:  true,
    deadClicks:  true,
  },

  // Heatmap recording (clicks + scroll on by default; mouse-move opt-in).
  heatmap: {
    enabled: true,
    clicks:  true,
    moves:   false,
    scroll:  true,
  },

});

Nota

Los ajustes de Configuración controlada por el proyecto. del Dashboard pueden desactivar rastreadores locales de analítica. Replay no tiene ningún interruptor local de activación: se configura en Settings → Session replay, y el SDK aplica la política más reciente del proyecto en la siguiente actualización de configuración.

Eventos registrados automáticamente

Con la configuración predeterminada, Kixo captura automáticamente estos eventos sin necesidad de código adicional:

page_view — todas las navegaciones (carga inicial + cambios de ruta en SPA)
session_start / session_end
click — todas las interacciones de clic con el selector del elemento
scroll_depth — umbrales del 25 / 50 / 75 / 100 %
rage_click — clics repetidos en el mismo elemento
dead_click — clics en elementos no interactivos
error — excepciones de JavaScript no capturadas + rechazos de promesas
performance — métricas de carga de página y Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — tiempos de solicitud opcionales cuando el seguimiento de red está activado
heatmap_click / scroll — datos de mapas de calor

Consulta la lista completa en Referencia de eventos.

Eventos personalizados

Kixo.track()

Envía un evento personalizado con propiedades opcionales.

Kixo.track('purchase_completed', {
  product_id: 'SKU-123',
  amount: 49.99,
  currency: 'USD',
});

Helpers tipados de eventos

Azúcar sintáctico sobre Kixo.track() para los eventos que Kixo reconoce por nombre (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Estos helpers tipados aportan validación de propiedades en tiempo de compilación y una única fuente de verdad para los nombres de clave; el detector de eventos estándar del backend compara literalmente.

Kixo.trackPurchase({ amount: 49.99, currency: 'USD', productId: 'pro_yearly' });

Kixo.trackSubscriptionStart({
  plan: 'pro',
  amount: 9.99,
  currency: 'USD',
  interval: 'month',
});

Kixo.trackSignup({ method: 'google' });
Kixo.trackTrialStart({ plan: 'pro', days: 14 });
Kixo.trackCancel({ plan: 'pro', reason: 'too_expensive' });
Kixo.trackUpgrade({ fromPlan: 'free', toPlan: 'pro' });
Kixo.trackActivation({ event: 'first_post_published' });
Kixo.trackShare({ channel: 'twitter', contentId: 'post_123' });
Kixo.trackInvite({ channel: 'email', recipientCount: 5 });

Kixo.identify()

Asocia el dispositivo actual a un usuario conocido. Las claves de propiedad estándar reservadas llevan el prefijo $ (convención de Mixpanel), lo que las separa de tus atributos personalizados y las promociona a las columnas de perfil del dashboard. Consulta la Catálogo estándar de propiedades de abajo para ver la lista completa de 37 claves.

Kixo.identify('user_123', {
  $email:  'jane@example.com',     // identity
  $name:   'Jane Doe',              // identity
  $plan:   'pro',                   // subscription pack
  $lifetime_orders: 12,             // e-commerce pack
  signup_source: 'twitter_ad',      // custom trait
});

Kixo.setUserProperty() — etiqueta a un usuario para segmentarlo

Añade al usuario actual atributos arbitrarios de clave/valor. Los valores pueden ser cadenas, números o booleanos; el formato booleano es la forma más limpia de etiqueta a un usuario para poder segmentarlo después, usarlo en campañas de correo o consultarlo en el chat.

// Tag a user as subscribed — instant segment "Subscribed users"
Kixo.setUserProperty('subscribe', true);

// Mark a VIP — used in campaign targeting + chat ("show me VIPs")
Kixo.setUserProperty('vip', true);

// Numeric and string values work too
Kixo.setUserProperty('plan_tier', 'enterprise');
Kixo.setUserProperty('lifetime_orders', 42);

// Bulk-set
Kixo.setUserProperties({ subscribe: true, plan_tier: 'enterprise' });

Las propiedades se guardan en localStorage entre recargas y se adjuntan automáticamente a los eventos posteriores. Puedes usarlas en el chat con indicaciones como "crear una campaña de correo para los usuarios cuyo campo subscribe sea true": Kixo crea el segmento y redacta la plantilla automáticamente. Se borran con Kixo.reset().

Kixo.group()

Asocia al usuario con una empresa u organización.

Kixo.group('company_456', {
  name: 'Acme Inc',
  plan: 'enterprise',
});

Kixo.reset()

Borra la identidad, las superpropiedades y la cola persistida. Llámalo al cerrar sesión para que los eventos posteriores no se atribuyan al usuario anterior.

Kixo.reset();

Catálogo estándar de propiedades

Las claves de propiedad reservadas llevan el prefijo $ para separarlas de tus atributos personalizados. El catálogo de Kixo incluye 37 claves repartidas en 3 bloques universales (identidad, geografía y ciclo de vida) y 5 bloques verticales B2B (suscripción, comercio electrónico, medios, marketplace y fidelización). Define solo las que encajen con tu producto: el panel se adapta y muestra únicamente los bloques que hayas rellenado.

Identidad

Siempre relevante. Define las columnas de la cabecera del perfil.

Clave	Tipo	Descripción
`$email`	cadena	Correo electrónico principal; suele usarse como clave de unión para consolidar identidades.
`$phone`	cadena	Número de teléfono en formato E.164.
`$name`	cadena	Nombre completo para mostrar.
`$first_name`	cadena	Nombre.
`$last_name`	cadena	Apellidos.
`$avatar_url`	cadena	URL completa de la imagen de avatar del usuario.

Geolocalización

Contexto geográfico.

Clave	Tipo	Descripción
`$country`	cadena	Código de país ISO 3166.
`$city`	cadena	Nombre de la ciudad.
`$region`	cadena	Estado o provincia.
`$timezone`	cadena	Zona IANA como `America/Los_Angeles`.
`$language`	cadena	Etiqueta IETF como `en` o `ru-RU`.
`$locale`	cadena	Identificador de configuración regional completo.

Ciclo de vida

Cuándo lo vimos.

Clave	Tipo	Descripción
`$created`	ISO8601	Fecha y hora de registro o creación de la cuenta.
`$last_seen`	ISO8601	Última interacción.

Suscripción

Úsalo si tu producto tiene planes.

Clave	Tipo	Descripción
`$plan`	cadena	Slug del nivel: `free`, `pro`, `enterprise`.
`$subscription_status`	cadena	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Cuándo termina la prueba actual.
`$mrr`	número	Ingresos recurrentes mensuales en la divisa de la cuenta.
`$subscription_started`	ISO8601	Cuándo empezó la suscripción actual.

Comercio electrónico

Úsalo si vendes productos.

Clave	Tipo	Descripción
`$lifetime_orders`	número	Número de pedidos completados.
`$lifetime_revenue`	número	Gasto total.
`$aov`	número	Valor medio del pedido.
`$last_purchase`	ISO8601	Última compra completada correctamente.
`$first_purchase`	ISO8601	Primera compra completada con éxito.
`$cart_abandoned_count`	número	Número total de abandonos de carrito.

Medios

Úsalo si publicas contenido.

Clave	Tipo	Descripción
`$content_tier`	cadena	`free` / `premium` / `paid`.
`$subscribed_categories`	Cadena CSV o lista	Categorías que sigue el usuario.
`$watch_time_total`	número	Tiempo total de visualización en segundos.
`$last_played`	ISO8601	Último inicio de reproducción.

Marketplace

Úsalo si tu producto es una plataforma de dos caras.

Clave	Tipo	Descripción
`$seller_tier`	cadena	Slug del nivel del vendedor.
`$buyer_tier`	cadena	Slug del nivel del comprador.
`$listings_count`	número	Anuncios activos del usuario.
`$reviews_count`	número	Reseñas recibidas por el usuario.
`$verified`	booleano	Estado de KYC.

Fidelización

Úsalo para programas de fidelización y recompensas.

Clave	Tipo	Descripción
`$loyalty_points`	número	Saldo actual de puntos canjeables.
`$vip_level`	cadena	Slug del nivel VIP.
`$referral_count`	número	Referencias correctas atribuidas a este usuario.

Consejo

¿No aparece tu caso? Usa claves sin prefijo para los atributos personalizados. Se muestran en el panel de atributos personalizados del dashboard sin llenar de ruido las columnas de perfil. Los 5 bloques verticales anteriores son propuestas para las estructuras B2B más habituales; la terminología específica de cada cliente (por ejemplo, shipping_plan) se deja sin prefijo.

Superpropiedades

Pares clave/valor por sesión que se adjuntan automáticamente a todos los eventos salientes. A diferencia de los atributos de identify(), que describen la identidad, las superpropiedades describen el contexto de la sesión: variante A/B activa, variante de compilación, feature flags activadas o referencia de afiliado. Se guardan en localStorage entre recargas y se borran con reset(). Si hay colisión de claves, las properties por evento de track() siempre tienen prioridad.

Kixo.setSuperProperty('build_flavor', 'beta');
Kixo.setSuperProperties({ ab_variant: 'B', referrer_campaign: 'autumn-launch' });

// Sugar for A/B tracking — keys as 'experiment_<id>' so backend
// can run direct WHERE filters on experiment analysis.
Kixo.setExperimentVariant('checkout_v2', 'variant_a');

Kixo.unsetSuperProperty('build_flavor');
Kixo.clearSuperProperties();

Mapas de calor

La grabación de mapas de calor está activada por defecto: clics y profundidad de desplazamiento, ambos con un muestreo del 100 %. El movimiento del ratón es opcional (genera mucho volumen; actívalo por página solo si resulta útil).

Kixo.init({
  projectId: 'YOUR_PROJECT_ID',
  apiKey:    'YOUR_API_KEY',
  heatmap:   { moves: true },  // turn on full-resolution mouse-move
});

Replay de sesiones

Session replay registra una instantánea del DOM de rrweb y un flujo de mutaciones para que el panel pueda reconstruir la página como una sesión navegable junto al rastro de eventos. Es una reconstrucción del DOM, no una grabación de pantalla en vídeo. Replay está desactivado por defecto. Actívalo para el proyecto en Dashboard → Ajustes → Reproducción de sesiones; no hace falta cambiar el código de la aplicación. Cuando se activa, la grabadora se descarga en un chunk independiente con la misma versión.

Nota

El panel es la fuente de verdad. Ahí puedes configurar Enable replay, Mask inputs, la duración máxima y los controles avanzados de captura. captureOnCellular se guarda en la misma política de proyecto para iOS y Android; los navegadores no exponen una señal fiable para distinguir entre Wi‑Fi y datos móviles, así que el SDK web informa de esa restricción nativa y la ignora.

Qué se enmascara

Replay está diseñado para activarse con seguridad. Hay tres capas de protección del contenido sensible, todas activadas por defecto:

El enmascarado de campos se controla por proyecto. — mientras la opción Enmascarar campos del Dashboard esté activada (valor por defecto), los caracteres escritos se sustituyen por asteriscos antes de salir del navegador. Desactívala solo si tienes una necesidad concreta y de baja sensibilidad; los campos de identidad, autenticación y pago seguirán enmascarados.
El atributo data-kixo-mask bloquea un elemento y todo su subárbol. Úsalo en cualquier contenedor que pueda incluir contenido personal o confidencial; la reproducción mostrará un marcador de posición, no el texto ni el contenido del DOM de ese subárbol.
html
```
<div data-kixo-mask>
  
  
</div>
```
Los campos sensibles siempre se enmascaran. — los campos que parezcan contraseñas, números de tarjeta, CVV, SSN, secretos o tokens (por type, name, id o autocomplete) se enmascaran aunque la opción Enmascarar campos del proyecto esté desactivada. El texto visible y los atributos serializados del DOM también pasan por el sanitizador de PII de Kixo antes de enviarse.

Recopilación de datos

El SDK captura los rastreadores activados en la integración y en la configuración del proyecto, además de los eventos y propiedades que envía tu aplicación.

Dónde se guardan las grabaciones

El SDK comprime con gzip los eventos de rrweb en segmentos acotados, pide a Kixo una URL de subida firmada para el proyecto y sube esos segmentos directamente al almacenamiento de replay. Abre la sesión reconstruida en Replay → Sesiones; enlaza con el rastro analítico de esa misma sesión.

Nota

Replay está sujeto a tu plan. El número de sesiones que se capturan y conservan depende del plan de tu proyecto; en los planes más básicos, Kixo sigue registrando metadatos de sesión ligeros para que la sesión aparezca en tus listas y análisis.

Flags de funcionalidad

Consulta los valores de los flags en tiempo de ejecución con Kixo.getFeatureFlag().

const variant = Kixo.getFeatureFlag('new_checkout');

if (variant === 'enabled') {
  showNewCheckout();
} else {
  showLegacyCheckout();
}

Entrega y comportamiento sin conexión

El SDK pone los eventos en cola localmente, los envía por lotes y reintenta los fallos transitorios con backoff. Si la recogida se pausa desde la configuración del proyecto, los eventos nuevos no se envían hasta que se vuelva a activar.

Diagnóstico

Instantánea de estado de solo lectura, útil para depurar en las herramientas de desarrollo por qué no están llegando los eventos.

const diag = Kixo.diagnostics();
console.log(diag);