Instalação

Situação no projeto

Implementado. O cadastro fica em Aplicativos (/app/aplicativos). Não existe pacote npm: o SDK é o arquivo frontend/static/t.js, servido pelo próprio painel.

Objetivo

Ligar um site ao TermoTracing com uma linha de HTML, sem build nem dependência, e confirmar na hora que os eventos estão chegando.

Entradas e saídas

Ponto	Descrição
Entrada	Nome, domínios autorizados, franquia mensal e comportamento ao estourar
Saída	Aplicativo com a chave pública e o snippet pronto para colar
Próximo passo	O primeiro evento preenche `primeiro_evento_em` e o selo muda de "Aguardando" para "Recebendo"

Etapas

1. Cadastrar o aplicativo

Campo	Regra
Nome	Obrigatório
Domínios	Origens que podem enviar eventos. Aceitam porta (`localhost:51110`) e curinga (`.termotubos.com.br` vale para a raiz e os subdomínios). Lista vazia bloqueia tudo*
Franquia mensal	Eventos aceitos incluídos no ciclo. Padrão 100.000, maior que zero
Ao estourar	`COBRAR_EXCEDENTE` (padrão, continua ingerindo) ou `PARAR_INGESTAO` (recusa até o próximo ciclo)

A chave é gerada pelo backend no formato pk_live_ + 32 hexadecimais. Ela é pública: fica no HTML do site.

2. Colar o snippet

O painel mostra o snippet com a chave e os endereços do ambiente:

<script src="https://tracing.termotubos.com.br/t.js" data-key="pk_live_…" data-endpoint="https://api-tracing.termotubos.com.br/evento/ingestao" async></script>

html

Cole antes de </head> em todas as páginas do site.

3. Esperar o primeiro evento

Depois de criar, abre a gaveta Instalação e primeiro evento. Ela consulta o aplicativo a cada 3 segundos e, quando primeiro_evento_em é preenchido, leva para a Visão geral.

O que o t.js captura

Tipo	Quando
`ERRO_JS` e `PROMISE_REJEITADA`	Erro não tratado e promise rejeitada sem `catch`
`CONSOLE`	`console.error` e `console.warn`
`REQUISICAO`	`fetch` e XHR, com método, status e duração
`NAVEGACAO`	Carga da página, `pushState`, `popstate` e `hashchange`
`CLIQUE`	Seletor e texto do elemento. Campos de formulário e `[data-privado]` viram `••••`
`DESEMPENHO`	`CARREGAMENTO`, `TTFB`, `LCP`, `INP` (a partir de 200 ms) e `CLS` na saída
`PULSO`	A cada 30 segundos com a aba visível
`SAIDA`	No `pagehide`
`IDENTIFICACAO` e `PERSONALIZADO`	Chamadas da API do script

API do script

Chamada	O que faz
`window.telemetria.identify(id, atributos)`	Liga a sessão ao `usuario_id` do sistema do cliente
`window.telemetria.event(nome, dados)`	Envia um evento `PERSONALIZADO`
`window.telemetria.enviarAgora()`	Força o envio da fila
`window.telemetria.encerrar()`	Para a captura

Chamadas feitas antes do script carregar podem ir para a fila window.telemetria.q.

Como o script envia

Identificação: anonimo_id no localStorage (telemetria_anonimo) e a sessão da aba no sessionStorage (telemetria_sessao).
Fila no localStorage, até 1.000 eventos. Se uma aba fecha, outra adota a fila parada há mais de 30 segundos.
Envio a cada 5 segundos, em lotes de até 200 eventos com gzip. Em 408, 429 e 5xx tenta de novo com espera de 5 a 60 segundos; outros 4xx descartam o lote.
Ao fechar a página, sendBeacon com até 60 eventos.
Tipos não essenciais têm teto de 600 por minuto no navegador.

Sugerir alterações nesta página

Atualizado em 2026/10/07 00:30

Nesta página

Objetivo Entradas e saídas Etapas 1. Cadastrar o aplicativo 2. Colar o snippet 3. Esperar o primeiro evento O que o t.js captura API do script Como o script envia