Next.js — Pages Router

Add Analytiq to your Next.js app (Pages Router) in two files. Uses the Analytiq component for initialization.

This guide is for Next.js projects with a /pages directory. If you have an /app directory, use the App Router guide

---

Step 1 — Install the SDK

npm install analytiq

---

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

Create this file anywhere in your project. This is the only place Analytiq is configured.

TypeScript (analytics.tsx)

components/analytics.tsx

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

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

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

  return (
    <>
      <Analytiq apiKey={process.env.NEXT_PUBLIC_ANALYTIQ_KEY!} />
      {children}
    </>
  )
}

export { track }

JavaScript (analytics.js)

components/analytics.js

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

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

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

  return (
    <>
      <Analytiq apiKey={process.env.NEXT_PUBLIC_ANALYTIQ_KEY} />
      {children}
    </>
  )
}

export { track }

Add your API key to .env.local:

NEXT_PUBLIC_ANALYTIQ_KEY=pk_live_your_actual_key_here

The prefix must be NEXT_PUBLIC_. Without it, the key will be undefined on the client side.

---

Step 3 — Wrap your app in pages/_app

_app is a special Next.js file that wraps every page. Add your AnalyticsProvider there.

TypeScript (pages/_app.tsx)

pages/_app.tsx

import type { AppProps } from 'next/app'
import { AuthProvider } from '../context/AuthContext'
import { AnalyticsProvider } from '../components/analytics'

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <AuthProvider>
      <AnalyticsProvider>
        <Component {...pageProps} />
      </AnalyticsProvider>
    </AuthProvider>
  )
}

JavaScript (pages/_app.js)

pages/_app.js

import { AuthProvider } from '../context/AuthContext'
import { AnalyticsProvider } from '../components/analytics'

export default function MyApp({ Component, pageProps }) {
  return (
    <AuthProvider>
      <AnalyticsProvider>
        <Component {...pageProps} />
      </AnalyticsProvider>
    </AuthProvider>
  )
}

Setup is complete! You never need to touch _app 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	user becomes null → reset() called automatically

---

Step 4 — Track Custom Events

For any specific action, import track() from your analytics.jsx file and call it where the action happens.

Track a page view

pages/dashboard.jsx

import { useEffect } from 'react'
import { track } from '../components/analytics'   // Import from your hub!

export default function DashboardPage() {
  useEffect(() => {
    track('Dashboard_page_view')
  }, [])

  return <h1>Dashboard</h1>
}

Button click

pages/pricing.jsx

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

export default function PricingPage() {
  return (
    <button onClick={() => track('upgrade_clicked', { plan: 'Pro' })}>
      Upgrade to Pro
    </button>
  )
}

After a login / API call

pages/login.jsx

import { useRouter } from 'next/router'
import { track } from '../components/analytics'

export default function LoginPage() {
  const router = useRouter()

  async function handleLogin(email, password) {
    const res = await api.post('/auth/login', { email, password })

    track('login_completed', { method: 'email' })
    router.push('/dashboard')
  }
}

---

Step 5 — Verify it’s working

1. Run: npm run dev
2. Log into your app
3. Open http://localhost:3000, press F12 → Network tab
4. You should see POST /api/events/track requests for every track() call you make

---

Common Mistakes

Mistake	Symptom	Fix
Using ANALYTIQ_KEY without NEXT_PUBLIC_	undefined key warning	Rename to NEXT_PUBLIC_ANALYTIQ_KEY
AnalyticsProvider outside AuthProvider	useAuth() context error	Auth must always wrap Analytics
Importing track from analytiq directly	Events may fire before SDK initializes	Always import from your local analytics.jsx hub