Telemetria

Telemetria de adoção do Makuco UI — o que é coletado, como habilitar restrita a desenvolvimento, e como desabilitar.

O Makuco UI expõe uma telemetria opcional de adoção, exportada diretamente de @db1/makuco-ui-core. Ela responde perguntas como "quais projetos já migraram para a versão X" ou "vale continuar investindo no wrapper Angular" — não mede frequência de uso, nem props ou valores configurados nos componentes.

O que é coletado

Campo	Origem
`projectName`	Passado explicitamente em `initTelemetry({ projectName })`.
`makucoVersion`	Versão instalada de `@db1/makuco-ui-core`, injetada em build-time.
`framework`	`'react'`, `'angular'` ou `'unknown'` — auto-detectado via fingerprint no DOM (Fiber/Ivy).
`components`	Nomes canônicos (`mk-button`, `mk-input`, …) dos componentes montados na sessão.

Nenhum dado de usuário, prop ou valor configurado é coletado — só o fato de que um componente foi montado.

Como funciona

Cada componente mk-* chama trackComponentUsage no próprio componentDidLoad. Os nomes vão se acumulando em memória (sem uma requisição por componente) e são enviados de uma vez, via navigator.sendBeacon, quando a aba perde visibilidade ou é fechada (visibilitychange para hidden, ou pagehide). Isso mantém o custo de rede em um envio por sessão de aba, não um por componente.

Se a aba estiver offline no momento do envio, o lote fica retido e é reenviado na próxima tentativa de flush — nada é descartado silenciosamente.

Habilitando

import { initTelemetry } from '@db1/makuco-ui-core';

initTelemetry({ projectName: 'meu-app' });

projectName é obrigatório — sem ele (ou com uma chamada a initTelemetry que nunca aconteceu), nenhum evento é enfileirado ou enviado. framework pode ser passado explicitamente para pular a auto-detecção via DOM, mas normalmente não é necessário.

Guarda de ambiente

Não existe detecção embutida de ambiente dev/prod — essa distinção é responsabilidade do consumidor. Importe o subpath por trás de uma guarda que restrinja a chamada a desenvolvimento, o que também permite ao seu bundler fazer dead-code elimination do módulo inteiro no bundle de produção (mesmo padrão usado pelo MUI X e pelo Next.js):

if (process.env.NODE_ENV !== 'production') {
  import('@db1/makuco-ui-core').then(({ initTelemetry }) => {
    initTelemetry({ projectName: 'meu-app' });
  });
}

Por que a guarda não vive dentro do pacote

packages/core é publicado pré-compilado — é o build do próprio Stencil, não o do seu app, que primeiro veria um process.env.NODE_ENV embutido no pacote, congelando o resultado para sempre no artefato publicado. A guarda só funciona no ponto de import do seu projeto.

Opt-out

Independente da guarda de ambiente, a coleta desliga sozinha nos seguintes casos:

Condição	Motivo
`process.env.CI` ou `process.env.TF_BUILD` presente	Evita ruído de pipelines (Azure DevOps, GitHub Actions).
`process.env.DO_NOT_TRACK` presente	Convenção consentwg/do-not-track.
Fora de um ambiente com `document` (SSR, build-time)	Mesmo padrão usado pelo serviço de `toast`.

process.env em app bundlado

Essas três checagens só têm efeito em contexto Node real (CI, SSR, scripts de build, testes) — a maioria dos bundlers de browser não expõe um process global de verdade em nenhum modo. Para produção de verdade no browser, a defesa é a guarda de ambiente da seção anterior.

Referência

Função	Assinatura	Descrição
`initTelemetry`	`(options: { projectName: string; framework?: 'react' \| 'angular' }) => void`	Inicializa a telemetria. Chame uma única vez, o mais perto possível do bootstrap da aplicação.