Guia de tracking

Onde iniciar o coletor de analytics no Next.js, Vue/Nuxt e TanStack — sem quebrar o SSR.

Client

O tracking roda só no browser. Use a tag de script para zero dependências, ou crie uma instância de DataxamasTracking no escopo do módulo e chame start() quando o app montar.

app/layout.tsx

import Script from "next/script";

export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en">
      <body>
        {children}

        <Script
          src="https://dataxamas.izakdvlpr.com/dataxamas.js"
          data-website-id="YOUR_WEBSITE_ID_HERE"
          data-allow-localhost="true"
        />
      </body>
    </html>
  );
}

components/dataxamas-provider.tsx

"use client";

import { DataxamasTracking } from "dataxamas";
import { useEffect } from "react";

// Module scope: one instance for the whole app, never re-created on render.
const tracking = new DataxamasTracking({
  websiteId: process.env.NEXT_PUBLIC_DATAXAMAS_WEBSITE_ID as string,
});

export function DataxamasProvider() {
  useEffect(() => {
    tracking.start();
  }, []);

  return null;
}

app/layout.tsx

import { DataxamasProvider } from "@/components/dataxamas-provider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}

        <DataxamasProvider />
      </body>
    </html>
  );
}

O tracking precisa apenas do websiteId — nenhum token de API. O endpoint de ingest é público, então nada secreto vai para o seu bundle. Logs e captura de erros precisam de token; veja os guias de Logs e Exceptions.

Navegação client-side já está coberta: o coletor verifica o path atual a cada 500 ms e envia um PAGE_VIEW a cada mudança, então transições do App Router, do vue-router e do TanStack Router funcionam.

start() é um no-op silencioso em localhost e 127.0.0.1 a menos que você passe allowLocalhost: true (ou data-allow-localhost="true" na tag de script). É por isso que nada aparece em desenvolvimento.

Servidor

Não existe tracking no servidor. Chamar start() fora do browser lança erro, então mantenha a chamada dentro de um efeito, de um plugin browser-only ou atrás de um guard de window.

ssr.ts

// Throws: "DataxamasTracking: This SDK can only be used in a browser environment."
tracking.start();

// Next.js — inside a "use client" component effect
useEffect(() => {
  tracking.start();
}, []);

// Nuxt — plugins/dataxamas.client.ts, the .client suffix is browser-only
// TanStack Start — useEffect in __root.tsx, or the client entry file

// Anywhere else, guard it by hand
if (typeof window !== "undefined") tracking.start();

Criar a instância é seguro em qualquer lugar — só o start() exige browser. Comparação completa: Browser vs Servidor.

AnteriorBrowser vs Servidor PróximoLogs