Web SDK

O Kixo Web SDK rexistra automaticamente clics, vistas de páxina, sesións, erros, profundidade de desprazamento, web vitals, rage-clicks, dead-clicks e datos de mapas de calor cunha integración dunha soa liña. A supervisión das peticións de rede está dispoñible como opción voluntaria. Distribúese como módulo ES nativo e funciona en navegadores modernos.

Instalación

Etiqueta script (CDN)

Engade o fragmento antes da etiqueta de peche </head>. Fíxate en type="module": é obrigatorio porque o SDK é un módulo ES. A reprodución de sesións vai separada nun chunk do gravador coa mesma versión, que só se carga despois de activar replay; así o bundle base segue sendo pequeno mentres 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

O SDK le project_id e api_key da URL do script e inicialízase. Se queres configurar opcións no código da aplicación, elimina os parámetros da URL e chama a Kixo.init({...}); o obxecto global Kixo está dispoñible cando o módulo remata de cargar.

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

Usa isto cando queiras configurar opcións no código da aplicación en vez de facelo pola URL do script. Expón a mesma API Kixo ca a 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 sen código

Se estás creando cun constructor con AI como Lovable, Bolt, v0 ou Replit, pega o fragmento coa etiqueta script directamente no chat do constructor ou na súa configuración de inxección de código. A maioría destes construtores permiten engadir scripts ao <head> do teu sitio.

Configuración

A integración de dúas liñas usa os valores locais por defecto de analítica que aparecen abaixo. A supervisión de peticións segue sendo voluntaria. A reprodución de sesións queda fóra de Kixo.init() a propósito: a activación, a mostraxe, a privacidade, a duración e a configuración de captura dependen exclusivamente do dashboard do proxecto.

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

Os axustes do dashboard de Configuración controlada polo proxecto. poden desactivar rastrexadores locais de analítica. Replay non ten ningunha marca local de activación positiva: configúrao en Settings → Session replay, e o SDK aplicará a política máis recente do proxecto na seguinte actualización da configuración.

Eventos rexistrados automaticamente

Coa configuración por defecto, Kixo captura automaticamente estes eventos sen necesidade de código adicional:

page_view — cada navegación (carga inicial + cambios de ruta SPA)
session_start / session_end
click — todas as interaccións de clic co selector do elemento
scroll_depth — limiares do 25 / 50 / 75 / 100 %
rage_click — clics repetidos no mesmo elemento
dead_click — clics en elementos non interactivos
error — excepcións de JavaScript non capturadas + rexeitamentos de promesas
performance — métricas de carga da páxina e Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — tempos de solicitude opcionais cando o seguimento de rede está activado
heatmap_click / scroll — datos do mapa de calor

Consulta a lista completa en Referencia de eventos.

Eventos personalizados

Kixo.track()

Envía un evento personalizado con propiedades opcionais.

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

Axudantes tipados para eventos

Atallo sobre Kixo.track() para os eventos que Kixo recoñece polo nome (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Estes wrappers tipados achegan validación de propiedades en compilación e unha única fonte de verdade para os nomes das claves; o detector de eventos estándar do backend fai a correspondencia literal.

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 o dispositivo actual cun usuario coñecido. As claves estándar reservadas levan o prefixo $ (convención de Mixpanel) para separarse dos teus atributos personalizados e promocionarse ás columnas de perfil do dashboard; consulta o Catálogo estándar de propiedades máis abaixo para ver a 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 un usuario para segmentación

Engade atributos clave/valor arbitrarios ao usuario actual. Os valores poden ser cadeas, números ou booleanos; a forma booleana é a máis limpa para etiquetar un usuario e poder segmentalo despois en segmentos, campañas de email ou consultas de 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' });

As propiedades persisten en localStorage entre recargas e engádense automaticamente aos eventos seguintes. Podes usalas no chat con instrucións como "crear unha campaña de correo electrónico para usuarios onde subscribe sexa true": Kixo crea o segmento e redacta a plantilla automaticamente. Límpanse con Kixo.reset().

Kixo.group()

Asocia o usuario a unha empresa ou organización.

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

Kixo.reset()

Borra a identidade, as superpropiedades e a cola persistida. Chama a isto ao pechar sesión para que os eventos posteriores non se atribúan ao usuario anterior.

Kixo.reset();

Catálogo estándar de propiedades

As claves de propiedade reservadas levan o prefixo $ para separarse dos teus atributos personalizados. O catálogo de Kixo inclúe 37 claves repartidas en 3 paquetes universais (identidade, xeografía e ciclo de vida) e 5 paquetes verticais B2B (subscrición, e-commerce, media, marketplace e fidelización). Define as que se apliquen ao teu produto: o dashboard adáptase e só mostra os paquetes que estean cubertos.

Identidade

Sempre relevante. Define as columnas da cabeceira do perfil.

Clave	Tipo	Descrición
`$email`	cadea	Correo electrónico principal, a miúdo usado como clave de fusión para unir identidades.
`$phone`	cadea	Número de teléfono E.164.
`$name`	cadea	Nome completo para mostrar.
`$first_name`	cadea	Nome.
`$last_name`	cadea	Apelidos.
`$avatar_url`	cadea	URL completa da imaxe de avatar do usuario.

Geo

Contexto xeográfico.

Clave	Tipo	Descrición
`$country`	cadea	Código de país segundo ISO 3166.
`$city`	cadea	Nome da cidade.
`$region`	cadea	Estado ou provincia.
`$timezone`	cadea	Zona IANA como `America/Los_Angeles`.
`$language`	cadea	Etiqueta IETF como `en` ou `ru-RU`.
`$locale`	cadea	Identificador de configuración rexional completo.

Ciclo de vida

Cando o vimos.

Clave	Tipo	Descrición
`$created`	ISO8601	Momento do rexistro ou da creación da conta.
`$last_seen`	ISO8601	Momento da última interacción.

Subscrición

Defíneo se o teu produto ten plans.

Clave	Tipo	Descrición
`$plan`	cadea	Slug do nivel: `free`, `pro`, `enterprise`.
`$subscription_status`	cadea	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Cando caduca a proba actual.
`$mrr`	número	Ingresos recorrentes mensuais na moeda da conta.
`$subscription_started`	ISO8601	Cando comezou a subscrición actual.

E-commerce

Defíneo se vendes produtos.

Clave	Tipo	Descrición
`$lifetime_orders`	número	Número de pedidos completados.
`$lifetime_revenue`	número	Gasto total.
`$aov`	número	Valor medio do pedido.
`$last_purchase`	ISO8601	Compra completada máis recente.
`$first_purchase`	ISO8601	Primeira compra completada.
`$cart_abandoned_count`	número	Número total de abandonos do carriño.

Media

Defíneo se publicas contido.

Clave	Tipo	Descrición
`$content_tier`	cadea	`free` / `premium` / `paid`.
`$subscribed_categories`	Cadea CSV ou array	Categorías que segue o usuario.
`$watch_time_total`	número	Tempo total de reprodución en segundos.
`$last_played`	ISO8601	Inicio de reprodución máis recente.

Marketplace

Defíneo se o teu produto é unha plataforma de dúas partes.

Clave	Tipo	Descrición
`$seller_tier`	cadea	Slug do nivel do vendedor.
`$buyer_tier`	cadea	Slug do nivel no lado comprador.
`$listings_count`	número	Anuncios activos do usuario.
`$reviews_count`	número	Valoracións recibidas polo usuario.
`$verified`	boolean	Estado de KYC.

Fidelización

Defíneo se tes programas de participación e recompensas.

Clave	Tipo	Descrición
`$loyalty_points`	número	Saldo actual de puntos canxeables.
`$vip_level`	cadea	Slug do nivel VIP.
`$referral_count`	número	Referencias completadas con éxito atribuídas a este usuario.

Consello

Non ves o teu patrón? Usa claves simples para os atributos personalizados. Aparecen no panel Custom Traits do dashboard sen contaminar as columnas do perfil. Os 5 paquetes verticais de enriba son propostas orientadas ás formas B2B máis habituais; a terminoloxía específica de cada cliente (por exemplo, shipping_plan) queda sen prefixo.

Superpropiedades

Pares clave/valor de sesión que se engaden automaticamente a cada evento saínte. A diferenza dos atributos identify() (que describen a identidade), as superpropiedades describen o contexto da sesión: a variante A/B activa, o tipo de compilación, as feature flags activadas ou a referencia do afiliado. Persístense en localStorage entre recargas e límpanse con reset(). Se hai conflito de clave, as properties do evento en track() sempre teñen prioridade.

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

A gravación de mapas de calor está activada por defecto: clics e profundidade de desprazamento, ambos con mostraxe do 100 %. O movemento do rato actívase de forma explícita (xera moito volume; actívao por páxina se compensa).

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

Reprodución de sesións

A reprodución de sesións grava unha instantánea do DOM de rrweb e un fluxo de mutacións para que o dashboard poida reconstruír a páxina como unha sesión navegable xunto ao rastro de eventos. É unha reconstrución do DOM, non unha gravación de vídeo da pantalla. Replay está desactivado por defecto. Actívao para o proxecto en Panel → Configuración → Repetición de sesións; non fai falla ningún cambio no código da aplicación. Unha vez activado, o gravador descárgase nun chunk separado coa mesma versión.

Nota

O dashboard é a fonte de verdade. Aí podes definir Enable replay, Mask inputs, a duración máxima e os controis avanzados de captura. captureOnCellular gárdase na mesma política de proxecto para iOS e Android; os navegadores non expoñen un sinal fiable para distinguir Wi‑Fi de rede móbil, así que o Web SDK informa desa restrición e ignóraa porque só existe en nativo.

Que se enmascara

Replay está deseñado para poder activarse con seguridade. Hai tres capas de protección do contido sensible, todas activadas por defecto:

O enmascaramento dos campos de entrada contrólase por proxecto — mentres a opción Enmascarar campos do Dashboard estea activada (o valor predeterminado), os caracteres escritos substitúense por asteriscos antes de saíren do navegador. Desactívaa só para unha necesidade concreta e pouco sensible; os campos de identidade, autenticación e pagamento seguen enmascarados.
O atributo data-kixo-mask bloquea un elemento e toda a súa subárbore. Póñeo en calquera contedor que poida incluír contido persoal ou confidencial; a reprodución mostra un marcador de posición, non o texto nin o contido do DOM desa subárbore.
html
```
<div data-kixo-mask>
  
  
</div>
```
Os campos sensibles sempre se enmascaran — os campos que parecen conter un contrasinal, número de tarxeta, CVV, SSN, segredo ou token (polo type, name, id ou autocomplete) enmascáranse mesmo cando a opción Enmascarar campos do proxecto está desactivada. O texto visible e os atributos serializados do DOM tamén pasan polo saneador de PII de Kixo antes de enviarse.

Recollida de datos

O SDK captura os rastrexadores activados na túa integración e na configuración do proxecto, ademais dos eventos e das propiedades que envía a aplicación.

Onde van as gravacións

O SDK comprime con gzip os eventos de rrweb en segmentos acoutados, pídelle a Kixo unha URL de subida asinada e limitada ao proxecto, e sobe eses segmentos directamente ao almacenamento de replay. Abre a sesión reconstruída en Repetición → Sesións; enlaza co rastro analítico da mesma sesión.

Nota

Replay depende do teu plan. O número de sesións que se capturan e se conservan depende do plan do teu proxecto; nos niveis máis baixos, Kixo segue rexistrando metadatos lixeiro da sesión para que apareza nas listas e na analítica.

Bandeiras de funcionalidades

Comproba os valores das flags en tempo de execución con Kixo.getFeatureFlag().

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

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

Entrega e funcionamento sen conexión

O SDK garda os eventos nunha cola local, envíaos por lotes e reintenta os fallos transitorios con backoff. Se a recollida se pausa desde a configuración do proxecto, os eventos novos non se envían ata que se reactive.

Diagnóstico

Instantánea de estado de só lectura, útil para depurar en dev tools por que non están chegando os eventos.

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