React.js

Add Analytiq to your React app in one file. Works with Vite and Create React App.

Before starting: Get your API key from the Settings page

What you’ll need

• React app (Vite or Create React App)
• Your Analytiq API key
• An existing auth state (like useAuth(), a useState, or a Context)

---

Step 1 — Install the SDK

npm install analytiq

---

Step 2 — Create src/analytics.jsx (One-time setup)

Create a new file in your src/ folder called analytics.jsx. This is the only place Analytiq is configured. You never touch it again after this.

JavaScript (analytics.jsx)

src/analytics.jsx

import { Analytiq, identify, reset, track } from 'analytiq/react'
import { useEffect } from 'react'

// Import YOUR app's authentication hook here
import { useAuth } from './context/AuthContext'

export function AnalyticsProvider({ children }) {
  const { user } = useAuth()

  // Bridges your Auth system to the Analytics SDK
  useEffect(() => {
    if (user) {
      identify(user)
    } else {
      reset()
    }
  }, [user])

  return (
    <>
      <Analytiq apiKey={import.meta.env.VITE_ANALYTIQ_KEY} />
      {children}
    </>
  )
}

// Re-export so other files import from here, not from the package directly
export { track }

TypeScript (analytics.tsx)

src/analytics.tsx

import { Analytiq, identify, reset, track } from 'analytiq/react'
import { useEffect } from 'react'
import { useAuth } from './context/AuthContext'

export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
  const { user } = useAuth()

  useEffect(() => {
    if (user) {
      identify(user)
    } else {
      reset()
    }
  }, [user])

  return (
    <>
      <Analytiq apiKey={import.meta.env.VITE_ANALYTIQ_KEY as string} />
      {children}
    </>
  )
}

export { track }

Add your API key to .env:

VITE_ANALYTIQ_KEY=pk_live_your_actual_key_here

---

Step 3 — Wrap your app with AnalyticsProvider

Open src/App.jsx (or App.tsx) and wrap your existing app with the provider you just created. Make sure it goes inside your Auth provider.

src/App.jsx

import { BrowserRouter, Routes, Route } from 'react-router-dom'
import { AuthProvider } from './context/AuthContext'
import { AnalyticsProvider } from './analytics.jsx'  // Import your new file

function App() {
  return (
    <AuthProvider>
      <AnalyticsProvider>      {/* Wrap your app here */}
        <BrowserRouter>
          <Routes>
            <Route path="/" element={<Home />} />
            <Route path="/dashboard" element={<Dashboard />} />
          </Routes>
        </BrowserRouter>
      </AnalyticsProvider>
    </AuthProvider>
  )
}

export default App

That’s the entire setup! You never touch these files again for analytics purposes.

---

What the setup handles automatically

Action	What happens
App loads (user logged out)	init() runs once, anonymous tracking begins
App loads (user already logged in)	userId restored from localStorage, user identified immediately
User logs in (your auth changes)	useEffect detects new user → identify(user) called automatically
User logs out (your auth clears)	user becomes null → reset() called automatically
User goes offline	Events saved to localStorage, retried on reconnect

---

Step 4 — Track Custom Events

For any specific action you want to measure (page views, clicks, purchases), import track() from your analytics.jsx file and call it where the action happens.

Track a page view

src/pages/Home.jsx

import { useEffect } from 'react'
import { track } from '../analytics.jsx'   // Import from your hub, not the package!

export function Home() {
  useEffect(() => {
    track('Home_page_view')
  }, [])

  return <h1>Welcome!</h1>
}

Button click

src/components/PricingCard.jsx

import { track } from '../analytics.jsx'

function PricingCard({ plan }) {
  const handleUpgrade = () => {
    track('upgrade_clicked', { plan: plan.name, price: plan.price })
    // your existing upgrade logic...
  }

  return <button onClick={handleUpgrade}>Upgrade to {plan.name}</button>
}

After an API call succeeds

src/pages/Checkout.jsx

import { track } from '../analytics.jsx'

async function handlePayment(paymentData) {
  const result = await processPayment(paymentData)

  if (result.success) {
    track('order_completed', {
      order_id: result.orderId,
      total: result.total,
    })
  } else {
    track('payment_failed', { reason: result.errorCode })
  }
}

Rule of thumb: Always import track from your local analytics.jsx file, not directly from analytiq. This ensures your tracking is always correctly initialized before it fires.

---

Step 5 — Verify it’s working

1. Run your app: npm run dev
2. Log into your app (so your useAuth returns a user)
3. Open browser DevTools (F12) → Network tab, filter by track
4. You should see a POST /api/events/track request for every event you fire

---

Common Mistakes

Mistake	Symptom	Fix
Using ANALYTIQ_KEY without VITE_ prefix	undefined key error in console	Rename to VITE_ANALYTIQ_KEY in .env
Importing track from analytiq instead of analytics.jsx	Events fire before SDK initializes	Always import from your local analytics.jsx hub
AnalyticsProvider placed outside AuthProvider	useAuth() crashes with context error	Ensure Auth wraps Analytics in App.jsx
Not calling identify() after login	Active Users shows 0 on dashboard	The analytics.jsx useEffect must receive a truthy user object