Guia de integração

Analytics no React

Para apps React de página única (Vite, Create React App). Uma instância do SDK num módulo e um componente que avisa cada troca de rota.

Antes de começar

Um app React com React Router v6 ou mais novo (para outro roteador, a ideia é a mesma).
A site_key e o domínio (e o endereço do servidor de dev, se quiser medir local) em Allowed origins.

Instalação

1Instale o SDK
No Vite, variáveis expostas ao navegador começam com VITE_.
```
npm install @racoelho/analytics
```
.env
```
VITE_ANALISA_SITE_KEY=YOUR_SITE_KEY
```

2Crie a instância num módulo

Importar o módulo cria o SDK uma vez só; qualquer componente pode importar analytics depois.

src/analytics.ts

import { Analytics } from '@racoelho/analytics'

// uma instância para o app inteiro; o construtor já envia a primeira pageview
export const analytics = new Analytics({
  siteKey: import.meta.env.VITE_ANALISA_SITE_KEY,
})

3Conte as trocas de rota

Um componente sem tela que chama pageview() sempre que o caminho muda.

src/route-tracker.tsx

import { useEffect } from 'react'
import { useLocation } from 'react-router-dom'
import { analytics } from './analytics'

export function RouteTracker() {
  const { pathname } = useLocation()
  useEffect(() => {
    // a cada troca de rota; a repetição da primeira carga é descartada pelo SDK
    analytics.pageview()
  }, [pathname])
  return null
}

src/App.tsx

import { BrowserRouter, Routes, Route } from 'react-router-dom'
import { RouteTracker } from './route-tracker'

export default function App() {
  return (
    <BrowserRouter>
      <RouteTracker />
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/pricing" element={<Pricing />} />
      </Routes>
    </BrowserRouter>
  )
}

Eventos e metas

Importe analytics e chame track(nome, propriedades), ou use os atalhos prontos (signup, addToCart, purchase, formSubmit…).

src/pricing-card.tsx

import { analytics } from './analytics'

export function PricingCard({ plan }: { plan: string }) {
  return (
    <button onClick={() => analytics.track('plan_selected', { plan })}>
      Assinar
    </button>
  )
}

// atalhos prontos do SDK
analytics.signup('email')
analytics.purchase('order-123', 99.9, 'BRL')

No painel, crie uma meta do tipo evento com o mesmo nome (plan_selected, purchase…) e monte funis com esses passos.

Navegação entre páginas

O SDK envia a pageview da primeira carga, mas não detecta navegação sem recarregar. Por isso o RouteTracker acima. O SDK registra o caminho (pathname), então mudar só a query string não conta como nova página, e a pageview repetida do mesmo caminho em menos de 2,5 segundos é descartada.

Confira se está funcionando

Abra o site publicado numa janela comum, sem bloqueador de anúncios.
Nas ferramentas do navegador, aba Network, filtre por v1/i: deve aparecer um POST com status 200 em até 3 segundos (ou quando você sai da página).
No painel, os eventos aparecem em cerca de 30 segundos.
Clique num link interno: um novo page_view aparece no POST seguinte.

Problemas comuns

siteKey is required no console: A variável não foi lida. Confira o prefixo VITE_ e reinicie o servidor de desenvolvimento depois de criar o .env.
A requisição volta 403 (origin_not_allowed): O domínio não está em Allowed origins nas configurações do site. Cadastre a origem exata — com https://, com e sem www, e endereços de teste como http://localhost:3000 se quiser medir em desenvolvimento.
Nenhuma requisição aparece na aba Network: O SDK respeita o Do Not Track por padrão: se o seu navegador envia DNT, nada é enviado. Teste em outro navegador ou perfil. Bloqueadores de anúncio também podem barrar o script.
As pageviews aparecem em dobro: O SDK foi inicializado duas vezes (por exemplo, o script colado no tema e também por um plugin). Mantenha uma única instância por página.

Crie sua conta e pegue a site_key

Grátis até 10 mil eventos por mês, sem cartão.

Criar conta grátis