Web SDK

O Kixo Web SDK recolhe automaticamente cliques, visualizações de página, sessões, erros, profundidade de scroll, web vitals, rage-clicks, dead-clicks e dados de mapa de calor com uma integração de uma linha. A monitorização de pedidos de rede está disponível por opt-in. É distribuído como módulo ES nativo e funciona em browsers modernos.

Instalação

Tag script (CDN)

Adicione o snippet antes da tag de fecho </head>. Repare em type="module" — é obrigatório porque o SDK é um módulo ES. A reprodução de sessão é separada num chunk do recorder com a versão correspondente, que só é carregado depois de a reprodução ser ativada, para o bundle base se manter pequeno enquanto a reprodução estiver desligada.

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 lê project_id e api_key do URL do script e inicializa-se. Para configurar opções no código da aplicação, remova os parâmetros do URL e chame Kixo.init({...}) — o objeto global Kixo fica disponível assim que o módulo carregar.

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

Use esta opção quando quiser configurar opções no código da aplicação em vez de o fazer pelo URL do script. Expõe a mesma API Kixo que a integração 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 sem código

Se estiver a criar com uma plataforma com AI como Lovable, Bolt, v0 ou Replit, cole o snippet da tag script diretamente no chat da plataforma ou nas definições de injeção de código. A maioria destas plataformas permite adicionar scripts ao <head> do seu site.

Configuração

A integração de duas linhas usa as predefinições locais de analítica abaixo. A monitorização de pedidos continua a ser opcional. O replay de sessão fica intencionalmente fora de Kixo.init(): a ativação, a amostragem, a privacidade, a duração e as definições de captura vêm apenas do dashboard do projeto.

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

Configuração controlada pelo projeto. As definições do Dashboard podem desativar rastreadores de analítica locais. A reprodução não tem qualquer opção local de ativação explícita: configure-a em Settings → Session replay, e o SDK aplica a política mais recente do projeto na próxima atualização da configuração.

Eventos recolhidos automaticamente

Com a configuração por defeito, a Kixo recolhe automaticamente estes eventos sem código adicional:

page_view — todas as navegações (carregamento inicial + mudanças de rota em SPA)
session_start / session_end
click — todas as interações de clique com o seletor do elemento
scroll_depth — limiares de 25 / 50 / 75 / 100 %
rage_click — cliques repetidos no mesmo elemento
dead_click — cliques em elementos não interativos
error — exceções de JavaScript não capturadas + rejeições de promises
performance — métricas de carregamento da página e Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — tempos dos pedidos, opcionalmente, quando a monitorização de rede está ativada
heatmap_click / scroll — dados de mapa de calor

Consulte a lista completa em Referência de eventos.

Eventos personalizados

Kixo.track()

Envie um evento personalizado com propriedades opcionais.

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

Helpers de eventos tipados

Abstração sobre Kixo.track() para os eventos que a Kixo reconhece pelo nome (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Estes wrappers tipados dão validação de propriedades em tempo de compilação e uma única fonte de verdade para os nomes das chaves — o detetor de eventos padrão no backend faz correspondência 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()

Associe o dispositivo atual a um utilizador conhecido. As chaves de propriedade reservadas usam o prefixo $ (convenção Mixpanel), para ficarem separadas dos seus traits personalizados e passarem para as colunas de perfil do dashboard — consulte o Catálogo de propriedades padrão abaixo para ver a lista completa das 37 chaves.

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() — marcar um utilizador para segmentação

Associe atributos arbitrários de chave/valor ao utilizador atual. Os valores podem ser strings, números ou booleanos — a forma booleana é a forma mais simples de etiqueta um utilizador para segmentação posterior em segmentos, campanhas de email ou consultas no 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 propriedades persistem em localStorage entre recarregamentos e são anexadas automaticamente aos eventos seguintes. Pode usá-las no chat com pedidos como "criar uma campanha de email para utilizadores em que subscribe é true" — Kixo cria automaticamente um segmento e um rascunho do modelo. São limpas em Kixo.reset().

Kixo.group()

Associe o utilizador a uma empresa ou organização.

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

Kixo.reset()

Limpe a identidade, as superpropriedades e a fila persistida. Chame isto no logout para que os eventos seguintes não sejam atribuídos ao utilizador anterior.

Kixo.reset();

Catálogo de propriedades padrão

As chaves de propriedade reservadas usam o prefixo $, para ficarem separadas dos seus atributos personalizados. O catálogo da Kixo abrange 37 chaves em 3 pacotes universais (identidade, geografia, ciclo de vida) e 5 pacotes verticais B2B (subscrição, comércio eletrónico, media, marketplace, fidelização). Defina apenas as que se aplicam ao seu produto — o dashboard adapta-se e mostra só os pacotes que preencher.

Identidade

Sempre relevante. Define as colunas do cabeçalho do perfil.

Chave	Tipo	Descrição
`$email`	cadeia de caracteres	Email principal, muitas vezes usado como chave de junção na consolidação de identidades.
`$phone`	cadeia de caracteres	Número de telefone E.164.
`$name`	cadeia de caracteres	Nome completo apresentado.
`$first_name`	cadeia de caracteres	Nome próprio.
`$last_name`	cadeia de caracteres	Apelido.
`$avatar_url`	cadeia de caracteres	URL completo da imagem de avatar do utilizador.

Geo

Contexto geográfico.

Chave	Tipo	Descrição
`$country`	cadeia de caracteres	Código do país segundo a ISO 3166.
`$city`	cadeia de caracteres	Nome da cidade.
`$region`	cadeia de caracteres	Estado ou província.
`$timezone`	cadeia de caracteres	Zona IANA, como `America/Los_Angeles`.
`$language`	cadeia de caracteres	Tag IETF, como `en` ou `ru-RU`.
`$locale`	cadeia de caracteres	Identificador completo de locale.

Ciclo de vida

Quando o vimos.

Chave	Tipo	Descrição
`$created`	ISO8601	Data e hora de registo ou criação da conta.
`$last_seen`	ISO8601	Momento da última interação.

Subscrição

Defina se o seu produto tem planos.

Chave	Tipo	Descrição
`$plan`	cadeia de caracteres	Slug do nível — `free`, `pro`, `enterprise`.
`$subscription_status`	cadeia de caracteres	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Quando termina o período experimental atual.
`$mrr`	número	Receita recorrente mensal na moeda da conta.
`$subscription_started`	ISO8601	Quando começou a subscrição atual.

Comércio eletrónico

Defina se vende produtos.

Chave	Tipo	Descrição
`$lifetime_orders`	número	Número de encomendas concluídas.
`$lifetime_revenue`	número	Despesa total.
`$aov`	número	Valor médio da encomenda.
`$last_purchase`	ISO8601	Compra concluída mais recente.
`$first_purchase`	ISO8601	Primeira compra bem-sucedida.
`$cart_abandoned_count`	número	Total acumulado de abandonos de carrinho.

Media

Defina se publica conteúdo.

Chave	Tipo	Descrição
`$content_tier`	cadeia de caracteres	`free` / `premium` / `paid`.
`$subscribed_categories`	string CSV ou array	Categorias seguidas pelo utilizador.
`$watch_time_total`	número	Tempo total de visualização em segundos.
`$last_played`	ISO8601	Início de reprodução mais recente.

Marketplace

Defina se a sua plataforma é bilateral.

Chave	Tipo	Descrição
`$seller_tier`	cadeia de caracteres	Slug do nível do lado do vendedor.
`$buyer_tier`	cadeia de caracteres	Slug do escalão do lado do comprador.
`$listings_count`	número	Anúncios ativos do utilizador.
`$reviews_count`	número	Avaliações recebidas pelo utilizador.
`$verified`	boolean	Estado de KYC.

Fidelização

Defina para programas de engagement e recompensas.

Chave	Tipo	Descrição
`$loyalty_points`	número	Saldo atual de pontos resgatáveis.
`$vip_level`	cadeia de caracteres	Slug do nível VIP.
`$referral_count`	número	Recomendações bem-sucedidas atribuídas a este utilizador.

Sugestão

Não encontra o padrão certo? Use chaves simples para traits personalizados. Surgem no painel Custom Traits do dashboard sem poluírem as colunas de perfil. Os 5 conjuntos verticais acima são sugestões para os formatos B2B mais comuns — a terminologia específica de cada cliente (por exemplo, shipping_plan) fica sem prefixo.

Superpropriedades

Pares chave-valor por sessão, anexados automaticamente a todos os eventos enviados. Ao contrário dos atributos identify() (que descrevem a identidade), as superpropriedades descrevem o contexto da sessão — variante A/B ativa, variante de build, feature flags com opt-in, referência de afiliado. Ficam persistidas em localStorage entre recarregamentos; são limpas em reset(). Em caso de colisão de chave, as properties por evento em track() prevalecem sempre.

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 gravação de mapa de calor está ativada por predefinição — cliques e profundidade de scroll, ambos com amostragem de 100 %. O movimento do rato é opt-in (gera muito volume; ative por página se fizer sentido).

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

Reprodução de sessão

O replay de sessão grava um instantâneo do DOM do rrweb e o fluxo de mutações, para que o dashboard possa reconstruir a página como uma sessão navegável, juntamente com o rasto de eventos. Trata-se de uma reconstrução do DOM, não de uma gravação de vídeo do ecrã. O Replay está desativado por defeito. Ative-o para o projeto em Painel → Definições → Reprodução de sessão; não é necessária qualquer alteração ao código da aplicação. Quando é ativado, o gravador é carregado a partir de um chunk separado, com a versão correspondente, depois de o replay ser ativado.

Nota

O dashboard é a fonte de verdade. Aí, pode definir Enable replay, Mask inputs, a duração máxima e os controlos avançados de captura. captureOnCellular fica guardado na mesma política de projeto para iOS e Android; os browsers não expõem um sinal fiável de Wi‑Fi face a rede móvel, por isso o SDK Web assinala e ignora essa restrição, que é exclusiva das apps nativas.

O que é mascarado

O Replay foi concebido para ser seguro de ativar. Há três camadas de proteção para conteúdo sensível, todas ativas por defeito:

O mascaramento dos campos é controlado pelo projeto — enquanto a definição Mascarar campos do Dashboard estiver ativada (predefinição), os caracteres introduzidos são substituídos por asteriscos antes de saírem do browser. Desative-a apenas para um caso específico e pouco sensível; os campos de identidade, autenticação e pagamento continuam mascarados.
O atributo data-kixo-mask bloqueia um elemento e toda a respetiva subárvore. Aplique-o a qualquer contentor que possa conter dados pessoais ou conteúdo confidencial; a reprodução mostra um marcador de posição, não o texto nem o conteúdo do DOM dessa subárvore.
html
```
<div data-kixo-mask>
  
  
</div>
```
Os campos sensíveis são sempre mascarados — os campos que pareçam conter palavra-passe, número de cartão, CVV, SSN, segredo ou token (por type, name, id ou autocomplete) são mascarados mesmo quando a definição Mascarar campos do projeto está desativada. O texto visível e os atributos serializados do DOM também passam pelo sanitizador de PII da Kixo antes do envio.

Recolha de dados

O SDK recolhe os trackers ativados na integração e nas definições do projeto, além dos eventos e propriedades enviados pela sua aplicação.

Para onde vão as gravações

O SDK comprime os eventos rrweb com gzip em segmentos limitados, pede à Kixo um URL de upload assinado e restrito ao projeto, e envia esses segmentos diretamente para o armazenamento de replay. Abra a sessão reconstruída em Replay → Sessões; aí encontrará a ligação para o rasto analítico dessa mesma sessão.

Nota

O Replay depende do seu plano. O número de sessões captadas e retidas depende do plano do projeto; nos escalões mais baixos, a Kixo continua a registar metadados de sessão leves para que a sessão apareça nas listas e na analítica.

Flags de funcionalidades

Verifique os valores das flags em tempo de execução com Kixo.getFeatureFlag().

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

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

Entrega e comportamento offline

O SDK coloca os eventos numa fila local, envia-os em lotes e repete tentativas em falhas transitórias com backoff. Se a recolha for suspensa nas definições do projeto, os novos eventos não são enviados até a recolha voltar a ser ativada.

Diagnóstico

Instantâneo do estado, só de leitura — útil para depurar, nas ferramentas de desenvolvimento, casos como «porque é que os meus eventos não estão a chegar?».

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