npm package: @pageviews/tracker
Description: Lightweight, cookie-free analytics tracker for PageViews.ai
Author: Pageviews
Latest version: 0.4.0

# @pageviews/tracker

The official JavaScript SDK for [Pageviews.ai](https://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](https://pageviews.ai/docs) 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

```bash
npm install @pageviews/tracker
```

## Quick Start

```js
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)

```tsx
// 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

```jsx
// 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

```js
// 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.

```ts
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.

```ts
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.

```ts
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](https://pageviews.ai/docs/npm-module-at-pageviewstracker)**