fg-tracker-browser 0.12.1 → 0.14.0

package/dist/types.d.ts

@@ -101,6 +101,53 @@ export interface BrowserOptions {
      * não depende de `analytics`, `consent` nem Do Not Track. `true` = `{ sampleRate: 1, softNavigations: true }`.
      */
     webVitals?: boolean | WebVitalsOptions;
+    /**
+     * Eventos automáticos de navegação e engajamento (docs/trafego-eventos.md): tempo ativo por
+     * visualização, marcos de rolagem, navegação SPA e volta do bfcache, links externos, downloads,
+     * ações declaradas com `data-fg-event` e formulários marcados com `data-fg-form`. Default `false`.
+     * Só valem com `analytics` ligada, sob o mesmo consentimento e Do Not Track dos pageviews; não criam
+     * pageviews nem sessões. `true` liga todos; um objeto desliga os que vierem `false`.
+     * `track()` e `conversion()` funcionam com `analytics`, mesmo sem esta opção.
+     */
+    events?: boolean | EventsOptions;
+}
+export interface EventsOptions {
+    /** `page_engagement`: tempo ativo (página visível, em foco e com interação nos últimos 30 s), em ms. */
+    engagement?: boolean;
+    /** `scroll`: marcos de 25, 50, 75 e 90% da página, uma vez cada por visualização. */
+    scroll?: boolean;
+    /** `navigation`: navegação SPA (com a rota de origem) e volta do bfcache. */
+    navigation?: boolean;
+    /** `outbound_click`: clique em link para outro site (só o host). */
+    outboundLinks?: boolean;
+    /** `file_download`: clique em link de arquivo (só a extensão). `extensions` substitui a lista padrão. */
+    downloads?: boolean | {
+        extensions?: string[];
+    };
+    /** Cliques em elementos com `data-fg-event="nome"` (e até 5 `data-fg-prop-<chave>`). */
+    actions?: boolean;
+    /** `form_start` e `form_submit` dos `<form data-fg-form="id">`: nunca lê valores nem campos. */
+    forms?: boolean;
+}
+/** Valor de atributo de evento: texto curto, número finito ou booleano. */
+export type EventPropValue = string | number | boolean;
+export type EventProps = Record<string, EventPropValue>;
+/** `auto` (SDK), `action` (`data-fg-event`), `custom` (`track`) ou `conversion` (`conversion`). */
+export type TrafficEventKind = 'auto' | 'action' | 'custom' | 'conversion';
+export interface TrackOptions {
+    /** Número do evento (quantidade, duração…), finito. */
+    value?: number;
+    /**
+     * Identificador estável da ocorrência (ex.: id do pedido, sem dado pessoal): o mesmo `name` + `id`
+     * gera o mesmo `event_id`, e a API grava uma vez dentro da janela de dedupe de 48 h (recarga da
+     * página de sucesso, clique duplo).
+     */
+    id?: string;
+}
+export interface ConversionOptions extends TrackOptions {
+    /** Moeda ISO 4217 (`BRL`), só com `value`. */
+    currency?: string;
+    props?: EventProps;
 }
 export interface WebVitalsOptions {
     /** Fração das cargas de documento medidas (sorteio por carga; as navegações SPA seguem a carga). Default 1. */
@@ -145,7 +192,36 @@ export interface IdentifyEvent {
     session_id: string;
     ts: string;
 }
-export type AnalyticsEvent = PageviewEvent | IdentifyEvent;
+/**
+ * Evento de navegação, engajamento, ação ou conversão (`analytics[]`, docs/trafego-eventos.md). Ligado
+ * à visualização (`pageview_id`) e à sessão do pageview; nunca conta como pageview.
+ */
+export interface TrafficEvent {
+    type: 'event';
+    /** 32 hex (aleatório, ou derivado de `name` + `id`): o reenvio não duplica (dedupe na API). */
+    event_id: string;
+    kind: TrafficEventKind;
+    /** `snake_case`, 1–64 caracteres. */
+    name: string;
+    /** Rota saneada da visualização (`sanitizePath`), sem query nem fragmento. */
+    url: string;
+    /** Visualização a que o evento pertence: o `event_id` do pageview dela. */
+    pageview_id: string;
+    /** View dos Web Vitals e dos spans da mesma página (`attributes['view.id']`), quando medida. */
+    view_id?: string;
+    value?: number;
+    currency?: string;
+    props?: EventProps;
+    screen: 'mobile' | 'tablet' | 'desktop' | null;
+    visitor_id: string;
+    session_id: string;
+    user_id?: string;
+    ts: string;
+    service?: string;
+    environment?: string;
+    release?: string;
+}
+export type AnalyticsEvent = PageviewEvent | IdentifyEvent | TrafficEvent;
 /** Como a view começou: carga do documento (tipo do Navigation Timing), volta do bfcache ou navegação SPA. */
 export type WebVitalsNavigationType = 'navigate' | 'reload' | 'back_forward' | 'prerender' | 'restore' | 'soft';
 /**
@@ -238,8 +314,18 @@ export interface BrowserTracker {
     page(path?: string): void;
     /** Liga o visitante anônimo ao usuário logado (`null` desliga). O id é guardado só como hash na API. */
     identify(userId: string | number | null): void;
-    /** Atualiza o consentimento de analytics; `granted` libera a fila retida em `pending`. */
+    /** Atualiza o consentimento de analytics; `granted` libera a fila retida em `pending`; `denied` descarta também os eventos (`track`, automáticos) que não saíram. */
     setConsent(consent: Consent): void;
+    /**
+     * Evento próprio (`kind: 'custom'`) da visualização atual. Ignorado sem `analytics`, com Do Not Track
+     * ou `consent: denied`; retido como os pageviews em `pending`. Nome `snake_case`; até 10 atributos.
+     */
+    track(name: string, props?: EventProps, options?: TrackOptions): void;
+    /**
+     * Conversão concluída (`kind: 'conversion'`): chame só depois do sucesso da operação de negócio
+     * (pagamento aprovado, cadastro criado), não no clique ou no envio do formulário.
+     */
+    conversion(name: string, options?: ConversionOptions): void;
     /** Remove os listeners globais e o patch do fetch. */
     close(): void;
     readonly breadcrumbs: readonly Breadcrumb[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fg-tracker-browser",
-  "version": "0.12.1",
-  "description": "SDK de navegador do FG Tracker: erros não tratados, breadcrumbs (cliques, navegação, console, fetch, XHR), usuário, release, propagação de trace para a API e Web Vitals",
+  "version": "0.14.0",
+  "description": "SDK de navegador do FG Tracker: erros não tratados, breadcrumbs (cliques, navegação, console, fetch, XHR), usuário, release, propagação de trace para a API, Web Vitals e eventos de navegação e engajamento",
   "license": "UNLICENSED",
   "homepage": "https://github.com/FORTGROUND/fg-tracker/tree/main/packages/browser#readme",
   "repository": {