fg-tracker-browser

SDK de navegador do FG Track (CONTRATO.md §24). Sem dependências, ESM, ~6 KB. Captura erros não tratados com os últimos breadcrumbs (cliques, navegação, console, fetch), o usuário logado, a página e a release; opcionalmente liga o fetch do front ao trace da API (traceparent).

import { init } from 'fg-tracker-browser';

const tracker = init({
  apiKey: 'stk_...',                         // chave do projeto (só ingere; pode ser pública)
  endpoint: 'https://<api-do-fg-tracker>',     // URL da API mostrada em Conectar
  serviceName: 'phase-web',
  release: import.meta.env.VITE_RELEASE,     // o mesmo valor enviado com os source maps
  environment: 'production',
  tracesSampleRate: 0.2,                     // 20% dos fetches viram traces
  propagateTraceTo: ['api.phasia.studio'],   // quem recebe traceparent (default: mesma origem)
  ignoreErrors: [/ResizeObserver loop/],
});

tracker.setUser({ id: user.id, email: user.email });
tracker.captureException(err, { stage: 'checkout' });
tracker.captureMessage('cupom aplicado', 'info');
tracker.addBreadcrumb({ type: 'custom', message: 'modal aberto' });

| opção | default | descrição | |---|---|---| | apiKey, endpoint | — | sem apiKey o SDK vira no-op (com aviso) | | serviceName, release, environment, user, attributes | — | vão em todo evento | | sampleRate | 1 | fração de erros enviados | | tracesSampleRate | 0 | fração de fetches que geram um trace (browser → http.client) | | propagateTraceTo | mesma origem | hosts/prefixos/RegExp que recebem traceparent | | ignoreErrors | [] | name: message (string/RegExp) ignorados | | beforeSend | — | (event) => event \| null | | breadcrumbs | tudo ligado | { click, navigation, console, fetch } | | maxBreadcrumbs | 30 | anel de breadcrumbs | | captureGlobalErrors | true | window.onerror + unhandledrejection | | flushIntervalMs | 1500 | envio em lote (keepalive; sendBeacon ao sair da página) | | analytics | false | liga visitantes anônimos + pageviews (§25). Quem não passa a opção não muda nada | | trackPageviews | = analytics | pageviews automáticos (carga inicial, pushState/replaceState/popstate) | | consent | 'granted' | 'pending' guarda em memória sem cookies até setConsent('granted'); 'denied' descarta | | cookieDomain | — | ex.: .fortground.com.br para o mesmo visitante entre subdomínios | | sanitizePath | normalizePath | (path) => string \| null antes do envio (null não registra) |

Cada erro vira um span kind: 'browser', name: page:/rota/:id, com attributes.breadcrumbs — o painel mostra "O que o usuário fez antes" no trace e a issue nasce agrupada por assinatura, com usuário afetado e release.

Tráfego (pageviews)

const tracker = init({ apiKey: 'stk_...', endpoint: 'https://<api-do-fg-tracker>',     // URL da API mostrada em Conectar serviceName: 'meu-site', analytics: true });
tracker.identify(user.id);        // liga o visitante ao usuário (a API guarda só sha256 com sal do projeto)
tracker.page('/checkout/sucesso'); // pageview manual (dedupe com o automático pela URL)
tracker.setConsent('granted');     // quando o banner de cookies for aceito (se iniciou com consent: 'pending')

• Visitante: 128 bits aleatórios no cookie first-party fgt_vid (1 ano, SameSite=Lax, Secure em https), com fallback em localStorage. Sessão: fgt_sid, renovada a cada evento e trocada após 30 min sem atividade.
• Payload (analytics[] no POST /v1/ingest): { type: 'pageview', url (caminho normalizado + só utm_*), title?, referrer (só a origem externa), utm_source/medium/campaign/term/content, screen (mobile/tablet/desktop), locale, visitor_id, session_id, ts, user_id? } e { type: 'identify', user_id, visitor_id, session_id, ts }.
• navigator.doNotTrack === '1' desliga a analytics (erros continuam). Nenhuma PII: query string, hash, e-mail e títulos não são guardados pela API.
• Instalação em Next.js App Router: docs/instalar-pageviews.md.

Source maps

Suba os .map da release no deploy (e apague-os do bundle público):

FG_TRACKER_KEY=stk_... FG_TRACKER_URL=https://<api-do-fg-tracker> \
  npx -p fg-tracker-sdk fg-tracker-sourcemaps --dir dist --release "phase-web@$GITHUB_SHA" --url-prefix "~/assets"
find dist -name '*.map' -delete

A ingestão traduz app-3f2a1c.js:1:48213 para src/checkout/Cart.tsx:42:11: o culpado da issue e os commits suspeitos passam a apontar para o código-fonte.

O endpoint é obrigatório: use a URL da API mostrada no painel em Conectar. O endereço de produção da API é https://tracker-api.fortground.com.br (o antigo track-api.fortground.com.br continua respondendo). O SDK envia a chave no header x-fg-tracker-key (e em ?key= no sendBeacon).

Cadastre a origem do site em Configurações → Geral → Domínios permitidos do projeto (ex.: https://www.seusite.com.br, https://*.seusite.com.br, http://localhost:3000); sem isso o navegador bloqueia o envio por CORS. TRACK_INGEST_ORIGINS na API continua como fallback global.

Migração de stread-track-browser

O pacote foi renomeado de stread-track-browser (nunca publicado no npm; usado via workspace/tarball) para fg-tracker-browser (mesma versão, 0.2.0, primeira publicação). Nomes antigos continuam funcionando e serão removidos na 1.0.

| antigo | novo | compatibilidade | |---|---|---| | pacote stread-track-browser | fg-tracker-browser | mesma API (init, createBrowserTracker); troque só o import | | header x-stread-track-key | x-fg-tracker-key | a API aceita os dois (e ?key=); o CORS libera os dois | | CLI stread-track-sourcemaps (do SDK Node) | fg-tracker-sourcemaps (fg-tracker-sdk) | alias obsoleto mantido | | STREAD_TRACK_KEY/STREAD_TRACK_URL/STREAD_TRACK_RELEASE no CI | FG_TRACKER_KEY/FG_TRACKER_URL/FG_TRACKER_RELEASE | o nome antigo é fallback | | prefixo de log [stread-track-browser] | [fg-tracker-browser] | — |

Cookies (fgt_vid, fgt_sid) e o formato do payload não mudaram: visitantes e sessões continuam os mesmos após a troca.

Build e testes

pnpm --filter fg-tracker-browser build   # dist/
pnpm --filter fg-tracker-browser test    # node:test com window/document falsos