Analytics in React

Installation

1. 1Install the SDK

   In Vite, variables exposed to the browser start with VITE_.

   npm install @racoelho/analytics

   VITE_ANALISA_SITE_KEY=YOUR_SITE_KEY

2. 2Create the instance in a module

   Importing the module creates the SDK exactly once; any component can import analytics afterwards.

   import { Analytics } from '@racoelho/analytics'
   
   // one instance for the whole app; the constructor sends the first pageview
   export const analytics = new Analytics({
     siteKey: import.meta.env.VITE_ANALISA_SITE_KEY,
   })

3. 3Count route changes

   A component with no UI that calls pageview() whenever the path changes.

   import { useEffect } from 'react'
   import { useLocation } from 'react-router-dom'
   import { analytics } from './analytics'
   
   export function RouteTracker() {
     const { pathname } = useLocation()
     useEffect(() => {
       // on every route change; the SDK drops the repeat on first load
       analytics.pageview()
     }, [pathname])
     return null
   }

   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>
     )
   }

Events and goals

Import analytics and call track(name, properties), or use the built-in helpers (signup, addToCart, purchase, formSubmit…).

import { analytics } from './analytics'

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

// built-in SDK helpers
analytics.signup('email')
analytics.purchase('order-123', 99.9, 'BRL')

In the dashboard, create an event goal with the same name (plan_selected, purchase…) and build funnels from those steps.

Page navigation

The SDK sends the first-load pageview but does not detect navigation without a reload — hence the RouteTracker above. The SDK records the path (pathname), so changing only the query string isn’t a new page, and a repeated pageview for the same path within 2.5 seconds is dropped.

Check that it works

1. Open the published site in a normal window, with no ad blocker.
2. In your browser devtools, Network tab, filter by v1/i: you should see a POST with status 200 within 3 seconds (or when you leave the page).
3. In the dashboard, events show up in about 30 seconds.
4. Click an internal link: a new page_view shows up in the next POST.

Troubleshooting

siteKey is required in the console

The variable wasn’t read. Check the VITE_ prefix and restart the dev server after creating .env.

The request returns 403 (origin_not_allowed)

Your domain isn’t in Allowed origins in the site settings. Add the exact origin — with https://, with and without www, plus test addresses like http://localhost:3000 if you want to measure in development.

No request shows up in the Network tab

The SDK honors Do Not Track by default: if your browser sends DNT, nothing is sent. Test in another browser or profile. Ad blockers can also block the script.

Pageviews show up twice

The SDK was initialized twice (for example, pasted in the theme and also added by a plugin). Keep a single instance per page.