@pageviews/tracker

The official JavaScript SDK for Pageviews.ai — a lightweight, cookie-free analytics platform built for privacy.

Use this package to add analytics to React, Vue, Next.js, or any other JavaScript framework with full programmatic control over pageview and event tracking.

For simple script tag installation (no build step), see the Script Tag guide instead.

Features

• Cookie-free and GDPR-compliant — no consent banner required
• Automatic pageview tracking for SPAs (React Router, Vue Router, Next.js App Router)
• Custom event tracking with properties and revenue data
• Engagement tracking — active time and scroll depth per page
• Auto-tracking for outbound links, file downloads, and form submissions
• Realtime User Explorer via identify()
• Full TypeScript support

Installation

npm install @pageviews/tracker

Quick Start

import { init, track, identify } from '@pageviews/tracker'

// Initialize once at your app's entry point
await init({ siteId: 'your-site-id' })

// Track custom events
track('signup', { props: { plan: 'pro' } })

// Identify a logged-in user for the Realtime User Explorer
identify({ userId: 'user-123' })

Your site ID is available in the Pageviews dashboard under Settings → Tracking.

Framework Examples

Next.js (App Router)

// app/providers.tsx
'use client'

import { useEffect } from 'react'
import { init, destroy } from '@pageviews/tracker'

export function Providers({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    init({ siteId: 'your-site-id' })
    return () => destroy()
  }, [])

  return <>{children}</>
}

React

// Entry point or layout component
import { useEffect } from 'react'
import { init, destroy } from '@pageviews/tracker'

export function AnalyticsProvider({ children, siteId }) {
  useEffect(() => {
    init({ siteId })
    return () => destroy()
  }, [siteId])

  return children
}

Vue

// main.js
import { init } from '@pageviews/tracker'

init({ siteId: 'your-site-id' })

API

init(options): Promise<void>

Initializes the tracker. Call once at your app's entry point.

await init({
  siteId: 'your-site-id',   // required — from your Pageviews dashboard
  endpoint?: string,         // optional — custom ingest URL (self-hosted / proxy)
  configEndpoint?: string,   // optional — custom config URL
})

On init, site configuration (routing mode, auto-tracking rules, scroll goals) is fetched from the Pageviews API and cached in localStorage for 1 hour.

track(eventName, options?): void

Sends a custom event.

track('purchase', {
  props: { plan: 'pro', annual: true },
  revenue: { amount: 49, currency: 'USD' },
  callback: (result) => console.log(result),
})

identify(data): void

Associates a user identifier with the current session. Appears in the Realtime User Explorer in the dashboard. Not persisted to the database — stored in memory only for the duration of the session.

identify({ userId: 'user-123' })

destroy(): void

Stops all tracking and resets state. Useful for SPA cleanup or testing. init() can be called again after destroy().

Privacy

• No cookies or persistent browser identifiers set
• Query parameters containing potential PII are stripped from URLs before sending — only UTM parameters and ref are kept
• Referrer query strings are stripped entirely — only the domain and path are sent
• IP addresses are hashed server-side with a daily-rotating salt and never stored in raw form
• No cross-site tracking

Full Documentation

For configuration options, advanced usage, and the script tag installation method, see the full docs:

pageviews.ai/docs/npm-module-at-pageviewstracker