# Savri / Besökskollen, Complete Documentation

> Simple, privacy-friendly web analytics. No cookies, no personal data, GDPR-compliant.

- Website: https://savri.io (international) / https://besokskollen.se (Swedish)
- Dashboard: https://savri.io/login
- Documentation: https://savri.io/docs
- Demo: https://savri.io/demo
- NPM Tracker: https://www.npmjs.com/package/@savri/tracker
- NPM MCP Server: https://www.npmjs.com/package/@savri/mcp
- Privacy policy: https://savri.io/privacy
- Terms of service: https://savri.io/terms

---

## Key Features

- **Real-time statistics**: Visitors, pageviews, traffic sources, countries, devices, browsers
- **Custom events**: Track any interaction with `savri.event('name', { properties })`
- **Event properties**: Add metadata to events for deeper analysis
- **Goals & conversions**: Pageview-based and event-based goals with trend tracking
- **Funnels**: Multi-step conversion funnel analysis with drop-off rates
- **Site search analytics**: Top searches, zero-result searches and zero rate per site via the site_search events
- **Google Search Console**: Integrated GSC data showing keywords, positions, CTR
- **Revenue tracking**: Connect affiliate and ad revenue to traffic data
- **Site groups**: Organize sites into groups with aggregated stats
- **Reports**: Monthly email reports with key metrics
- **Export**: CSV export of all data
- **API**: Public REST API for programmatic access
- **MCP Server**: AI assistants (Claude, Cursor) can read analytics directly
- **Tracker SDK**: npm package with React hooks, Next.js support, TypeScript

## Technical Details

- Tracking script: < 1KB gzipped
- No cookies, no cookie banner required
- SPA support: Automatic navigation tracking for React, Next.js, Vue
- Bot filtering: Built-in filtering of known bots and crawlers
- Data retention: 24 months of aggregated statistics, raw data deleted after 90 days
- 30-day free trial, no credit card required

---

## Pricing

### Plans & Features

| Plan | Sites | Features |
|------|-------|----------|
| **Starter** | 2 sites | Basic analytics, traffic sources, countries, devices |
| **Basic** | 5 sites | + Custom events, event properties, Google Search Console |
| **Growth** | 10 sites | + API access, CSV export, funnels, API keys |
| **Business** | 15 sites | + Revenue tracking, team members (5), priority support |
| **Enterprise** | Custom | + Unlimited team, SLA, custom integrations |

### USD Pricing (monthly)

| Pageviews/mo | Starter | Basic | Growth | Business |
|-------------|---------|-------|--------|----------|
| 10,000 | $9 | $12 | $19 | $49 |
| 100,000 | $15 | $19 | $29 | $79 |
| 200,000 | $23 | $29 | $45 | $99 |
| 500,000 | $35 | $45 | $69 | $129 |
| 1,000,000 | $49 | $65 | $99 | $179 |
| 2,000,000 | $69 | $89 | $139 | $249 |
| 5,000,000 | $99 | $129 | $199 | $349 |
| 10,000,000+ | Custom | Custom | Custom | Custom |

### SEK Pricing (monthly)

| Pageviews/mo | Starter | Basic | Growth | Business |
|-------------|---------|-------|--------|----------|
| 10,000 | 79 kr | 99 kr | 159 kr | 499 kr |
| 100,000 | 149 kr | 189 kr | 299 kr | 799 kr |
| 200,000 | 229 kr | 289 kr | 449 kr | 999 kr |
| 500,000 | 349 kr | 449 kr | 699 kr | 1 299 kr |
| 1,000,000 | 499 kr | 649 kr | 999 kr | 1 799 kr |
| 2,000,000 | 699 kr | 899 kr | 1 399 kr | 2 499 kr |
| 5,000,000 | 999 kr | 1 299 kr | 1 999 kr | 3 499 kr |

Yearly billing: 10x monthly price (2 months free).
30-day free trial on all plans. No credit card required.

---

## Comparison with Plausible Analytics

| Feature | Savri | Plausible |
|---------|-------|-----------|
| Privacy-first, no cookies | Yes | Yes |
| GDPR compliant | Yes | Yes |
| Free trial | 30 days | 30 days |
| MCP server for AI | Yes | No |
| Revenue tracking | Yes | Yes (v2) |
| Affiliate tracking | Yes | No |
| Site groups | Yes | No |
| Funnels | Yes | Yes |
| Google Search Console | Yes | Yes |
| Custom events | Yes | Yes |
| API | Yes | Yes |
| Self-hosted option | No | Yes |
| Starting price | $9/mo | $9/mo |

---

## Getting Started

### Quick Start (5 minutes)

1. **Create an account**: Sign up free at https://savri.io/signup
2. **Add your site**: Enter your domain in the dashboard
3. **Copy the tracking script**: You'll get a unique script like:

```html
<script defer data-site-id="YOUR-SITE-ID" data-api="https://savri.io" src="https://savri.io/script.js"></script>
```

4. **Paste in your site's `<head>`**: Add it to all pages you want to track
5. **Done!** Visit your site and check the dashboard, data appears within seconds

The script is under 1KB and doesn't affect load time. No cookies, no cookie banner needed.

### Script Attributes

| Attribute | Description | Required |
|-----------|-------------|----------|
| `data-site-id` | Your unique site ID from the dashboard | Yes |
| `data-api` | API endpoint (https://savri.io or https://besokskollen.se) | Yes |
| `defer` | Load asynchronously without blocking | Recommended |

---

## Script Extensions

Extend tracking with data attributes on the script tag:

| Extension | Attribute | What it tracks |
|-----------|-----------|---------------|
| Outbound links | `data-outbound-links` | Clicks on external links |
| File downloads | `data-file-downloads` | Downloads of PDF, ZIP, etc. |
| Form submissions | `data-forms` | Form submit events |
| Scroll depth | `data-scroll-depth` | Scroll milestones (25%, 50%, 75%, 100%) |

Example with all extensions:
```html
<script defer
  data-site-id="YOUR-SITE-ID"
  data-api="https://savri.io"
  data-outbound-links
  data-file-downloads
  data-forms
  data-scroll-depth
  src="https://savri.io/script.js">
</script>
```

---

## Custom Events

Track any user interaction with the JavaScript API.

### Basic usage
```javascript
savri.event('signup');
```

### With properties
```javascript
savri.event('purchase', { product_id: '123', value: 299 });
```

### With revenue
```javascript
savri.event('purchase', { value: 49.90, currency: 'USD' });
```

Properties must be registered in the dashboard before they appear in reports.
Custom events require the Basic plan or higher.

## Event Properties

Add metadata to events for deeper analysis. Properties are key-value pairs attached to events.

### Registering properties
Properties must be registered in Settings > Properties before use.
Names must be lowercase, start with a letter, contain only letters, numbers, underscores and hyphens.

### Using properties
```javascript
savri.event('purchase', {
  product_id: 'SKU-123',
  category: 'electronics',
  value: 299
});
```

---

## Goals & Conversions

Goals track when important actions happen on your site.

### Pageview goals
Track when a user visits a specific URL:
- Match type: Exact, Contains, or Starts with
- Example: Track visits to `/thank-you` as a conversion

### Event goals
Track when a custom event fires:
- Match on event name
- Example: Track `signup` or `purchase` events

### Creating goals
1. Go to Goals in the dashboard
2. Click "Create goal"
3. Choose Pageview or Event type
4. Set the match pattern
5. Goals show completion count and trend vs previous period

Goals are available on all plans.

---

## Funnels

Analyze multi-step conversion flows to find where visitors drop off.

### How funnels work
1. Define 2+ steps (pageviews or events)
2. See how many sessions complete each step
3. Identify drop-off rates between steps
4. Optimize the weakest step

### Example funnel: E-commerce checkout
1. Product page viewed (pageview: `/products/*`)
2. Add to cart (event: `add_to_cart`)
3. Checkout started (pageview: `/checkout`)
4. Purchase completed (event: `purchase`)

### Match types
- **Exact**: URL must match exactly
- **Contains**: URL must contain the string
- **Starts with**: URL must start with the string

Funnels require the Growth plan or higher.

---

## Site Search Analytics

Measure your site's internal search: what visitors look for, and what they cannot find.

### Events
- `site_search`: sent on every completed search, with properties `query` (normalized phrase), `results_count` and `source` (autocomplete or results page)
- `site_search_zero`: sent in addition when a search returns 0 results
- `site_search_click` (optional): sent on search result clicks, enables search CTR

### What you get
- **Top searches**: the most popular search phrases with share of sessions
- **Zero-results list**: phrases visitors look for but do not find, an action list for catalog and synonyms
- **Zero rate**: the share of searches with no results
- **Search CTR**: the share of searches that lead to a result click (requires site_search_click)

Register the properties under Settings, Properties, then send the events. Full guide: /docs/site-search

Site search analytics requires the Basic plan or higher.

---

## Google Search Console Integration

See search keywords, positions, CTR and impressions directly in Savri.

### How to connect
1. Go to your site in the dashboard
2. Click "Connect GSC"
3. Log in with your Google account and grant access
4. Data syncs automatically (weekly, with 2-3 day delay from Google)

### What you get
- **Search queries**: Keywords that drive traffic
- **Pages**: Which pages rank in Google
- **Countries**: Geographic search distribution
- **Devices**: Desktop vs mobile search performance
- **Metrics**: Clicks, impressions, CTR, average position
- **Trends**: Compare with previous period

### Data views
Switch between Queries, Pages, Countries, and Devices tabs.
Export any view as CSV. Data is cached and synced weekly.

GSC integration requires the Basic plan or higher.

---

## Revenue Tracking

Connect affiliate and ad revenue to your traffic data.

### Supported sources
- **Affiliate networks**: Amazon, Adtraction, Awin, etc.
- **Ad networks**: Google AdSense, Mediavine, etc.
- **Manual entry**: Add revenue data manually

### How it works
1. Go to Revenue in the dashboard
2. Add revenue entries per site, source, and period
3. See total revenue, revenue per visitor, and revenue per pageview
4. Compare revenue across sites and time periods

Revenue tracking requires the Business plan or higher.

## Affiliate Tracking

Track affiliate link clicks and attribute revenue to traffic sources.

### Setup
1. Add `data-outbound-links` to your tracking script
2. Affiliate link clicks are tracked automatically
3. Match revenue data to click data in the Revenue dashboard

### Supported link patterns
Automatically detects common affiliate link patterns from major networks.

---

## Site Groups

Organize your sites into logical groups for aggregated statistics.

### Use cases
- Group sites by client (for agencies)
- Group sites by category (e.g., "E-commerce", "Blogs")
- Group sites by region

### Features
- Aggregated visitor and pageview counts per group
- Color coding and emoji for visual organization
- Click into a group to see individual site stats
- Drag sites between groups

---

## Reports

Automatic monthly email reports with key metrics.

### What's included
- Total visitors and pageviews
- Trend vs previous month
- Top pages and traffic sources
- One report per site

### Setup
Enable monthly reports in Settings. Reports are sent on the 1st of each month.

---

## Export Data

Download your analytics data as CSV files.

### What can be exported
- Daily visitor/pageview data
- Top pages
- Traffic sources
- Countries
- Search Console data (queries, pages, countries, devices)

Export requires the Growth plan or higher.

---

## Public REST API

Programmatic access to all your analytics data.

### Authentication
All requests require an API key in the `X-API-Key` header:
```bash
curl -H "X-API-Key: YOUR_API_KEY" https://savri.io/api/v1/sites
```

### Endpoints

#### Sites
- `GET /api/v1/sites`, List all sites
- `GET /api/v1/sites/:id`, Get site details

#### Stats
- `GET /api/v1/stats/overview?siteId=X&period=7d`, Overview stats
- `GET /api/v1/stats/pages?siteId=X&period=7d`, Top pages
- `GET /api/v1/stats/referrers?siteId=X&period=7d`, Traffic sources
- `GET /api/v1/stats/countries?siteId=X&period=7d`, Countries

#### Goals
- `GET /api/v1/goals?siteId=X`, List goals
- `POST /api/v1/goals`, Create goal

#### Funnels
- `GET /api/v1/funnels?siteId=X`, List funnels
- `GET /api/v1/funnels/:id/stats?period=30d`, Funnel statistics

#### Properties
- `GET /api/v1/properties?siteId=X`, List event properties
- `GET /api/v1/properties/breakdown?site_id=X&property=query&event=site_search_zero`, Top values for a property, optionally filtered by event

### Periods
- `today`, `7d`, `30d`, `90d`

### Rate limiting
API requests are rate-limited per API key.

API access requires the Growth plan or higher.

## API Keys

Create and manage API keys in Settings > API Keys.

- Each key has a name for identification
- Keys can be revoked at any time
- One key per purpose recommended (e.g., separate keys for different integrations)

API keys require the Growth plan or higher.

---

## Tracker SDK (@savri/tracker)

Official npm package for React, Next.js, and vanilla JavaScript.

### Installation
```bash
npm install @savri/tracker
```

### React / Next.js

#### SavriProvider
```tsx
import { SavriProvider } from '@savri/tracker/react';

export default function Layout({ children }) {
  return (
    <SavriProvider siteId="YOUR-SITE-ID" apiUrl="https://savri.io">
      {children}
    </SavriProvider>
  );
}
```

#### useTracker()
```tsx
import { useTracker } from '@savri/tracker/react';

function MyComponent() {
  const { trackEvent } = useTracker();
  return <button onClick={() => trackEvent('click', { button: 'cta' })}>Click me</button>;
}
```

#### usePageview(url?)
Track a pageview when a component mounts:
```tsx
import { usePageview } from '@savri/tracker/react';

function ProductPage() {
  usePageview('/products/my-product');
  return <div>...</div>;
}
```

#### useTrackEvent(eventName)
Get a memoized callback for a specific event:
```tsx
import { useTrackEvent } from '@savri/tracker/react';

function SignupButton() {
  const trackSignup = useTrackEvent('signup');
  return <button onClick={trackSignup}>Sign up</button>;
}
```

### Vanilla JavaScript
```javascript
import { init, trackEvent, trackPageview } from '@savri/tracker';

init({ siteId: 'YOUR-SITE-ID', apiUrl: 'https://savri.io' });

trackPageview();
trackEvent('purchase', { product_id: '123', value: 299 });
```

### Enhanced tracking options
```javascript
init({
  siteId: 'YOUR-SITE-ID',
  apiUrl: 'https://savri.io',
  trackOutboundLinks: true,
  trackFileDownloads: true,
  trackForms: true,
  trackScrollDepth: true,
});
```

---

## AI Integration (MCP Server)

Give AI assistants direct access to your analytics via the Model Context Protocol.

### What is MCP?
MCP (Model Context Protocol) lets AI tools like Claude and Cursor read your analytics data directly, without manual copy-paste.

### Installation
```bash
npm install @savri/mcp
```

### Setup for Claude Desktop
Add to your Claude Desktop config (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "savri": {
      "command": "npx",
      "args": ["@savri/mcp"],
      "env": {
        "SAVRI_API_KEY": "your-api-key"
      }
    }
  }
}
```

### What AI can do
- "How many visitors did my site get this week?"
- "Which pages are most popular?"
- "Show me traffic sources for the last 30 days"
- "Create a goal for the signup page"
- "What's my conversion rate for the checkout funnel?"

### MCP vs REST API
- **MCP**: Runs locally, best for Claude/Cursor, natural language queries
- **Remote MCP connector** (https://savri.io/api/mcp, OAuth): Claude.ai, ChatGPT (Developer mode) and Perplexity. Sign in once, no API key to paste
- **REST API**: Standard HTTP, best for custom integrations and Custom GPTs

---

## Developer Tools Overview

Four ways to integrate with Savri:

| Tool | Purpose | Use when |
|------|---------|----------|
| **@savri/tracker** (npm) | Collect data | Building a website to be tracked |
| **@savri/mcp** (npm) | Read data via AI | Using Claude Code or Cursor |
| **Remote MCP connector** | Read/write via AI, OAuth sign-in | Using Claude.ai, ChatGPT or Perplexity |
| **REST API** | Read/write programmatically | Building custom tools or integrations |

### Do I need both tracker and MCP?
They serve different purposes. Tracker collects data INTO Savri. MCP reads data OUT from Savri.

### Script tag vs npm package?
Script tag is easiest for most sites. npm package (@savri/tracker) is best for React/Next.js with TypeScript support.

---

## Integration Guides

### HTML / Vanilla JavaScript
Paste the script in your `<head>` tag:
```html
<script defer data-site-id="YOUR-SITE-ID" data-api="https://savri.io" src="https://savri.io/script.js"></script>
```

### WordPress
Three options:
1. **Theme header**: Appearance > Theme Editor > header.php, paste before `</head>`
2. **Plugin**: Install "Insert Headers and Footers", paste in Header section
3. **Customizer**: Appearance > Customize > Additional CSS/Scripts

### Next.js
Add to `app/layout.tsx`:
```tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          defer
          data-site-id="YOUR-SITE-ID"
          data-api="https://savri.io"
          src="https://savri.io/script.js"
          strategy="afterInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

Or use the npm package: `npm install @savri/tracker`

### React (SPA)
Add to `index.html` or use the npm package for React hooks support.
Navigation tracking is automatic for SPAs.

### Shopify
1. Go to Online Store > Themes > Edit code
2. Open `theme.liquid`
3. Paste the script before `</head>`

### Vue.js / Nuxt
Add to `index.html` or `nuxt.config.ts` head section.

### Squarespace
Settings > Advanced > Code Injection > Header

### Webflow
Project Settings > Custom Code > Head Code

### Wix
Dashboard > Settings > Custom Code > Head

### Hugo / Jekyll / Gatsby / Astro
Add to your base template/layout in the `<head>` section.

---

## Bot Filtering

Savri automatically filters out bot traffic to give you accurate visitor counts.

### What's filtered
- Known bots (Googlebot, Bingbot, etc.)
- Headless browsers and automation tools
- Requests without proper browser headers
- Known spam referrers
- Data center IP ranges

### How it works
Filtering happens server-side at the data collection point. No bot traffic is stored, so it doesn't count toward your pageview quota.

---

## Metrics Explained

### Visitors (Unique visitors)
Unique sessions in the selected period. Identified by a privacy-friendly hash, no cookies or personal data.

### Pageviews
Total number of page loads. One visitor can generate multiple pageviews.

### Bounce rate
Percentage of sessions with only one pageview. Lower is generally better.

### Session duration
Average time visitors spend on your site per session.

### Traffic sources
Where visitors come from: Direct, Organic Search, Social, Referral, etc.

### Channels
- **Direct**: Typed URL or bookmark
- **Organic Search**: Google, Bing, etc.
- **Paid Search**: Google Ads, Bing Ads
- **Social**: Facebook, Twitter, LinkedIn, etc.
- **Referral**: Links from other websites
- **Email**: Links from email campaigns

---

## Content Security Policy (CSP)

If your site uses CSP headers, add these directives:

```
script-src: https://savri.io https://besokskollen.se
connect-src: https://savri.io https://besokskollen.se
```

Or if using Besökskollen:
```
script-src: https://besokskollen.se
connect-src: https://besokskollen.se
```

---

## Billing & Subscription

### Trial
- 30-day free trial on all plans
- No credit card required
- Full access to all features during trial
- Reminder emails at 7 days, 1 day, and expiry

### Payment
- Stripe-powered payments
- Monthly or yearly billing (yearly = 2 months free)
- Invoices available in the customer portal
- SEK for Swedish customers, USD for international

### Changing plans
- Upgrade or downgrade at any time
- Pro-rated billing on plan changes
- Go to Settings > Subscription

### Cancellation
- Cancel any time, no commitment
- Access continues until end of billing period
- All data is retained for 30 days after cancellation