npm package: @savri/tracker
Description: Savri Analytics tracker for React, Next.js, and vanilla JavaScript
Author: Savri
Latest version: 1.0.0

# @savri/tracker

Privacy-friendly analytics for React, Next.js, and vanilla JavaScript.

## Installation

```bash
npm install @savri/tracker
```

## Quick Start

### React / Next.js

```tsx
// app/layout.tsx or _app.tsx
import { SavriProvider } from '@savri/tracker/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SavriProvider siteId="your-site-id">
          {children}
        </SavriProvider>
      </body>
    </html>
  )
}
```

```tsx
// In any component
import { useTracker } from '@savri/tracker/react'

function SignupButton() {
  const { trackEvent } = useTracker()

  return (
    <button onClick={() => trackEvent('Signup Click', { plan: 'pro' })}>
      Sign Up
    </button>
  )
}
```

### Vanilla JavaScript

```js
import { init, trackEvent } from '@savri/tracker'

// Initialize once
init({ siteId: 'your-site-id' })

// Track events anywhere
document.getElementById('signup-btn').addEventListener('click', () => {
  trackEvent('Signup Click', { plan: 'pro' })
})
```

## API Reference

### React Hooks

#### `<SavriProvider>`

Wrap your app with this provider to enable tracking.

```tsx
<SavriProvider
  siteId="your-site-id"          // Required
  apiUrl="https://your-api.com"  // Optional, defaults to besokskollen.se
  trackOutboundLinks             // Track external link clicks
  trackFileDownloads             // Track file downloads
  trackForms                     // Track form submissions
  trackScrollDepth               // Track scroll milestones
  debug                          // Log tracking calls to console
>
  <App />
</SavriProvider>
```

#### `useTracker()`

Access tracking functions from any component.

```tsx
const { trackEvent, trackPageview } = useTracker()

// Track custom event
trackEvent('Button Click', { buttonId: 'cta' })

// Track virtual pageview (modals, tabs, etc.)
trackPageview('/modal/signup')
```

#### `usePageview(url?)`

Track a pageview when a component mounts.

```tsx
function SignupModal() {
  usePageview('/modal/signup')
  return <div>...</div>
}
```

#### `useTrackEvent(eventName)`

Get a memoized callback for tracking a specific event.

```tsx
const trackClick = useTrackEvent('CTA Click')

<button onClick={() => trackClick({ variant: 'blue' })}>
  Click me
</button>
```

#### `<SavriScript>`

Alternative: render a script tag instead of using the Provider.

```tsx
// In _document.tsx or layout.tsx
<SavriScript siteId="your-site-id" trackOutboundLinks />
```

### Vanilla JavaScript

#### `init(config)`

Initialize the tracker. Call once on page load.

```js
import { init } from '@savri/tracker'

init({
  siteId: 'your-site-id',
  trackOutboundLinks: true,
  trackFileDownloads: true,
  trackForms: true,
  trackScrollDepth: true,
  debug: false,
})
```

#### `trackPageview(url?)`

Track a pageview. Called automatically on init and SPA navigation.

```js
import { trackPageview } from '@savri/tracker'

// Track current page
trackPageview()

// Track virtual page
trackPageview('/modal/signup')
```

#### `trackEvent(name, props?)`

Track a custom event.

```js
import { trackEvent } from '@savri/tracker'

trackEvent('Purchase', {
  productId: 'abc123',
  price: 99.99,
  currency: 'SEK'
})
```

## Enhanced Tracking

Enable these features in the config to automatically track:

| Feature | Description | Events Generated |
|---------|-------------|------------------|
| `trackOutboundLinks` | External link clicks | `Outbound Link: Click` |
| `trackFileDownloads` | File downloads (PDF, ZIP, etc.) | `File Download` |
| `trackForms` | Form submissions | `Form Submit` |
| `trackScrollDepth` | Scroll milestones (25%, 50%, 75%, 100%) | `Scroll Depth` |

## Next.js App Router

For Next.js 13+ with App Router, use the Provider in your root layout:

```tsx
// app/layout.tsx
import { SavriProvider } from '@savri/tracker/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SavriProvider siteId={process.env.NEXT_PUBLIC_SAVRI_SITE_ID!}>
          {children}
        </SavriProvider>
      </body>
    </html>
  )
}
```

## Next.js Pages Router

For Next.js with Pages Router, add the Provider to `_app.tsx`:

```tsx
// pages/_app.tsx
import { SavriProvider } from '@savri/tracker/react'

export default function App({ Component, pageProps }) {
  return (
    <SavriProvider siteId={process.env.NEXT_PUBLIC_SAVRI_SITE_ID!}>
      <Component {...pageProps} />
    </SavriProvider>
  )
}
```

## TypeScript

Full TypeScript support included. Types are exported from the package:

```ts
import type { SavriConfig, EventProps } from '@savri/tracker'
```

## Privacy

Savri is privacy-friendly by design:

- **No cookies** - No cookie banner needed
- **No IP storage** - IPs are hashed immediately
- **No personal data** - We don't collect PII
- **GDPR compliant** - Works in the EU without consent

## Links

- [Savri Dashboard](https://besokskollen.se/dashboard)
- [Documentation](https://besokskollen.se/docs)
- [Privacy Policy](https://besokskollen.se/integritet)