Tracker API (Go Fiber)¶

Base URL: http://localhost:8282 Tecnologia: Go Fiber 2 Autenticacao: Nenhuma (endpoints publicos)

Swagger

Documentacao interativa disponivel em GET /swagger/*.

Tracking de Eventos¶

Enviar Eventos¶

POST /assets

Endpoint principal do SDK. Recebe dados comportamentais do usuario a cada ~5 segundos.

Request Body:

{
  "sessionId": "abc123-session-id",
  "clientId": "660e8400-e29b-41d4-a716-446655440000",
  "url": "https://minha-lp.com/oferta",
  "path": "/oferta",
  "referrer": "https://google.com",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "campanha-1",
  "mouseX": 450,
  "mouseY": 320,
  "mouseVelocity": 12.5,
  "scrollVelocity": 3.2,
  "maxScrollDepth": 65,
  "idleTime": 2.3,
  "pageVisibility": "visible",
  "lastClickedTag": "BUTTON",
  "sessionTime": 45.2,
  "sessionOutcome": "",
  "targetClicked": "",
  "sessionStartedAt": 1705312200000,
  "windowFocused": true,
  "focusChanges": 2
}

Campo	Tipo	Descricao
`sessionId`	string	Identificador unico da sessao
`clientId`	string (UUID)	ID do datasource (landing page)
`url`	string	URL completa da pagina
`path`	string	Path da pagina
`referrer`	string	URL de origem
`utm_source`	string	UTM source
`utm_medium`	string	UTM medium
`utm_campaign`	string	UTM campaign
`mouseX`	int	Posicao X do mouse
`mouseY`	int	Posicao Y do mouse
`mouseVelocity`	float	Velocidade do mouse (px/s)
`scrollVelocity`	float	Velocidade de scroll (px/s)
`maxScrollDepth`	int	Profundidade maxima de scroll (0-100%)
`idleTime`	float	Tempo ocioso (segundos)
`pageVisibility`	string	Estado da aba (`visible`/`hidden`)
`lastClickedTag`	string	Tag HTML do ultimo elemento clicado
`sessionTime`	float	Tempo total na pagina (segundos)
`sessionOutcome`	string	Resultado da sessao
`targetClicked`	string	Seletor do alvo clicado
`sessionStartedAt`	int64	Timestamp de inicio da sessao (ms)
`modalDisplayedAt`	int64	Timestamp de exibicao do modal (ms)
`modalClosedAt`	int64	Timestamp de fechamento do modal (ms)
`modalInteraction`	string	Tipo de interacao com o modal
`windowFocused`	bool	Se a janela esta em foco
`focusChanges`	int	Numero de trocas de foco

Response 200 OK:

{
  "status": "ok"
}

Logica de predicao

Quando sessionTime >= seconds_exit (configurado na Action do datasource), o Tracker chama automaticamente a Models API (POST /api/v1/predict). Se o resultado indicar should_trigger = true, o modal e enviado via WebSocket para a sessao.

WebSocket¶

Canal de Comunicacao¶

WS /channel

Conexao WebSocket para receber modais em tempo real.

Parametros de conexao:

Parametro	Tipo	Descricao
`sessionId`	query string	ID da sessao para receber modais

Exemplo de conexao:

const ws = new WebSocket('ws://localhost:8282/channel?sessionId=abc123');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // data.modal_html contém o HTML do modal
  document.body.innerHTML += data.modal_html;
};

Mensagem recebida:

{
  "type": "modal",
  "modal_html": "<div class='modal'>...</div>",
  "probability": 0.15,
  "session_id": "abc123"
}

Trigger Manual¶

POST /trigger-decision

Dispara manualmente um modal para uma sessao especifica.

Request Body:

{
  "sessionId": "abc123-session-id"
}

Analytics¶

Todas as Sessoes¶

GET /api/analytics/all

Retorna todas as sessoes de todos os clientes.

Sessoes por Cliente¶

GET /api/analytics/{clientId}/all

Parametro	Tipo	Descricao
`clientId`	string (path)	UUID do datasource

Retorna todas as sessoes de um datasource.

Overview de Sessoes¶

GET /api/analytics/{clientId}/overview

Parametro	Tipo	Descricao
`clientId`	string (path)	UUID do datasource

Retorna metricas gerais: total de sessoes, conversoes, taxa de conversao, tempo medio.

Response 200 OK:

{
  "totalSessions": 15420,
  "totalConversions": 1850,
  "conversionRate": 12.0,
  "avgSessionTime": 42.5
}

Series Temporais de Sessoes¶

GET /api/analytics/{clientId}/sessions

Parametro	Tipo	Descricao
`clientId`	string (path)	UUID do datasource

Retorna dados de sessoes agrupados por periodo para graficos.

Series Temporais de Conversoes¶

GET /api/analytics/{clientId}/conversions

Parametro	Tipo	Descricao
`clientId`	string (path)	UUID do datasource

Retorna dados de conversoes agrupados por periodo para graficos.

Health & Metricas¶

Health Check Completo¶

GET /health

Verifica saude de todos os componentes: MongoDB, FastAPI e WebSocket.

Response 200 OK:

{
  "status": "healthy",
  "components": {
    "mongodb": "up",
    "fastapi": "up",
    "websocket": "up"
  }
}

Readiness Probe¶

GET /health/ready

Probe de readiness para Kubernetes/Railway.

Liveness Probe¶

GET /health/live

Probe de liveness para Kubernetes/Railway.

Metricas Prometheus¶

GET /metrics

Retorna metricas no formato Prometheus.

Outros¶

Ping¶

GET /

Response: "pong"

SDK (Arquivos Estaticos)¶

GET /sdk/*

Serve os arquivos do Tracker SDK JavaScript.

Pagina de Teste¶

GET /test

Serve uma pagina HTML de teste para validar o SDK.