# Specvista Analytics

> Specvista Analytics is product analytics for websites, React Native apps and Node.js servers, with a consent banner built in. Websites add one script tag; apps and servers send named events over HTTP; reports cover pageviews, sessions, sources, devices, countries, custom events, funnels and identified people. Sign-up is self-serve and free.

## Instructions for agents

- Supported access: a person signs up at https://analytics.specvista.com/signup and creates a property (project). Its project key, which starts with sa_live_, authenticates event sending in the X-Api-Key header. Reading reports needs a bearer token from POST https://analyticsapi.specvista.com/api/v1/auth/login, valid for 90 days. The person signs in and gives you the token through the SA_TOKEN environment variable. Never ask for, type or store their password.
- API base: https://analyticsapi.specvista.com/api/v1. Contract: https://analyticsapi.specvista.com/api/v1/openapi.json.
- Websites: <script src="https://analyticsapi.specvista.com/api/v1/sdk.js" data-api-key="<project key>" async></script>. Custom events only send after the visitor accepts analytics in the banner.
- Packages: check before installing. Run npm view specvista-analytics-node version and npm view specvista-analytics-rn version. Both are prepared but not yet on npm; if npm returns E404, use the plain HTTP helpers in the guides. Never pin an old version from memory.
- Servers must send "source":"backend". Requests from script-like user agents (curl, headless browsers, python-requests and similar) are otherwise stored as bot traffic and left out of reports.
- Errors return JSON with a stable code and a doc_url. Match on code and follow doc_url.
- Safe ways to try: there is no sandbox or test mode yet. Read-only calls (sdk.js, openapi.json, reports) are safe. Every POST /ingest stores a real event, so send tests to a separate test property. Events with "environment":"development" are stored as internal and excluded from reports.
- Never: commit keys or tokens; put secrets, passwords, payment details or free text in event properties; create accounts or properties, rotate keys, delete properties, or call /forget without the person's go-ahead.
- There is no MCP server or CLI yet. Use the HTTP API.
- Every page below is Markdown. Add .md to any docs page address for its Markdown. The whole set is in one file at https://analytics.specvista.com/llms-full.txt.


---

<!-- Source: https://analytics.specvista.com/docs.md -->

# Specvista Analytics docs

Specvista Analytics counts what people do in your websites, React Native apps and Node services, and shows it in one dashboard. Websites send pageviews through one script tag. Apps and servers send named events, such as `signup.completed`, over HTTP. Reports cover pageviews, sessions, top pages, landing pages, referrers, channels, campaigns, devices, countries, custom events, funnels and identified people.

## Who it is for

Product teams and solo builders who want product analytics with a consent banner built in. Sign-up is self-serve and free at [analytics.specvista.com/signup](https://analytics.specvista.com/signup). There are no paid plans. Specvista also uses it to measure its own products.

## How access works

| Who | What they need | Where it comes from |
|---|---|---|
| A person | An account | [Sign up](https://analytics.specvista.com/signup) with first name, last name (optional), email and a password of 8 or more characters |
| A website, app or server sending events | A project key, which starts with `sa_live_` | The Properties page of the dashboard, or `GET /api/v1/projects` |
| A script or agent reading reports | A bearer token | `POST /api/v1/auth/login` with the account's email and password; valid for 90 days |

A project is called a property in the dashboard. Each property has one key and a type: web, mobile, backend or other.

## Guides

- [Get a project key](https://analytics.specvista.com/docs/get-a-project-key.md)
- [Add tracking to a website](https://analytics.specvista.com/docs/track-web.md)
- [Add tracking to a Node.js server](https://analytics.specvista.com/docs/track-node.md)
- [Add tracking to a React Native app](https://analytics.specvista.com/docs/track-react-native.md)
- [Read reports](https://analytics.specvista.com/docs/read-reports.md)
- [Build with AI agents](https://analytics.specvista.com/docs/agents.md)

## Reference

- [API reference](https://analytics.specvista.com/docs/api.md) and the [OpenAPI document](https://analyticsapi.specvista.com/api/v1/openapi.json)
- [SDK reference](https://analytics.specvista.com/docs/sdks.md)
- [Errors](https://analytics.specvista.com/docs/errors.md)

## Service addresses

| Purpose | Address |
|---|---|
| Dashboard and docs | `https://analytics.specvista.com` |
| API base | `https://analyticsapi.specvista.com/api/v1` |
| Browser script | `https://analyticsapi.specvista.com/api/v1/sdk.js` |
| OpenAPI | `https://analyticsapi.specvista.com/api/v1/openapi.json` |

---

<!-- Source: https://analytics.specvista.com/docs/agents.md -->

# Build with AI agents

Everything an AI agent, such as Claude, ChatGPT, Codex or Cursor, needs to add Specvista Analytics to a codebase or read its reports.

## Entry points

| Entry point | Address | Status |
|---|---|---|
| `llms.txt` | `https://analytics.specvista.com/llms.txt` | Live |
| `llms-full.txt`, every page in one file | `https://analytics.specvista.com/llms-full.txt` | Live |
| Markdown for any docs page | Add `.md` to the page address, for example `https://analytics.specvista.com/docs/track-web.md` | Live |
| OpenAPI | `https://analyticsapi.specvista.com/api/v1/openapi.json` | Live |
| HTTP API | `https://analyticsapi.specvista.com/api/v1` | Live |
| Browser script | `https://analyticsapi.specvista.com/api/v1/sdk.js` | Live |
| Node.js SDK | `specvista-analytics-node` | Not yet on npm |
| React Native SDK | `specvista-analytics-rn` | Not yet on npm |
| MCP server | None | Not available yet. Use the HTTP API |
| CLI | None | Not available yet. Use `curl` or PowerShell `Invoke-RestMethod` |
| Agent skill | None | Not available yet. Use the rules snippet below |

## How an agent gets access

- **To send events**, the agent needs a project key. The person copies it from the Properties page of the dashboard and stores it as `SA_API_KEY`, or the agent reads it with `GET /api/v1/projects` using their token.
- **To read reports**, the agent needs a bearer token in `SA_TOKEN`. The person runs the sign-in command in [Get a project key](https://analytics.specvista.com/docs/get-a-project-key.md) themselves. The token lasts 90 days and gives full access to that account, including keys, so keep it out of logs and commits.
- **Never** ask for, type or store the person's password, and never create an account or property without the person's go-ahead.

## Try things safely

There is no sandbox or test mode yet. Instead:

- Read-only checks need no account: `GET /api/v1/sdk.js`, `GET /api/v1/openapi.json` and `GET /api/v1/ingest/ignore-status`.
- Every call to `POST /ingest` stores a real event. Send test events to a separate property, for example one named "Test", rather than to a live one.
- Events sent with `"environment":"development"` are stored as internal and left out of every report, so they cannot skew numbers. They also do not appear in reports, so use a test property when you need to see the result.
- Reports are read-only and safe to call.
- Ask first before anything that cannot be undone: `POST /forget`, the `account.deleted` event, `DELETE /projects/{id}` and `POST /projects/{id}/rotate-key`.

## Rules for your repository

Paste this into `AGENTS.md`, `CLAUDE.md` or your editor's rules file:

```markdown
## Analytics: Specvista Analytics

- Docs: https://analytics.specvista.com/llms.txt (Markdown pages: add .md to any docs URL).
- API base: https://analyticsapi.specvista.com/api/v1. Contract: /openapi.json.
- Websites: one script tag, https://analyticsapi.specvista.com/api/v1/sdk.js with data-api-key.
  Custom events: window.saTrack(name, props); they send only after the visitor accepts analytics.
- Servers: POST /ingest with X-Api-Key from the SA_API_KEY environment variable and "source":"backend".
- Check npm view specvista-analytics-node version (or -rn) before installing; if 404, use HTTP.
- Event names: lower case object.action, for example checkout.completed. Never put secrets,
  passwords, payment details or free text in properties.
- Never commit keys or tokens. Never call /forget, rotate a key or delete a property without asking.
- Errors carry a code and a doc_url; follow the doc_url.
```

## Main tasks

- [Get a project key](https://analytics.specvista.com/docs/get-a-project-key.md)
- [Add tracking to a website](https://analytics.specvista.com/docs/track-web.md)
- [Add tracking to a Node.js server](https://analytics.specvista.com/docs/track-node.md)
- [Add tracking to a React Native app](https://analytics.specvista.com/docs/track-react-native.md)
- [Read reports](https://analytics.specvista.com/docs/read-reports.md)
- [Errors](https://analytics.specvista.com/docs/errors.md)

---

<!-- Source: https://analytics.specvista.com/docs/get-a-project-key.md -->

# Get a project key

Every event is sent with a project key. This guide creates an account and a property, then finds its key.

## Prerequisites

- An email address and permission to create an account. An agent must ask the person before creating an account or a property for them.
- For the API route: `curl`, or any HTTP client.

## In the dashboard

1. Open [analytics.specvista.com/signup](https://analytics.specvista.com/signup). Enter first name, last name, email and a password of at least 8 characters, then choose **Create account**. You land on the dashboard. Last name is optional.
2. Choose **Properties** in the sidebar, then **New property**.
3. Enter a **Name**. For a website, enter its **Domain**, for example `example.com`, without `https://`. Pick the **Type**: Website, Mobile, Backend or Other.
4. Choose **Create and get script**. The property appears in the list with its key, which starts with `sa_live_`, and a **Copy** button. **Show script** reveals the website snippet with the key filled in.

Expected result: the property is listed and its key is visible.

## With the API

The person runs the sign-in in their own terminal, so the password never reaches an agent's transcript or the shell history. Each command prompts for the email and password and stores the token in `SA_TOKEN` for that terminal session.

macOS and Linux, with Node.js 18 or later:

```bash
printf "Email: "; read -r SA_EMAIL; printf "Password: "; stty -echo; read -r SA_PASSWORD; stty echo; echo
export SA_TOKEN=$(SA_EMAIL="$SA_EMAIL" SA_PASSWORD="$SA_PASSWORD" node -e '
fetch("https://analyticsapi.specvista.com/api/v1/auth/login", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ email: process.env.SA_EMAIL, password: process.env.SA_PASSWORD }) })
  .then(async (res) => { const body = await res.json(); if (!res.ok) { console.error(body.code, body.message); process.exit(1); } console.log(body.user.token); })')
unset SA_PASSWORD
```

Windows PowerShell:

```powershell
$credential = Get-Credential -Message "Specvista Analytics"
$body = @{ email = $credential.UserName; password = $credential.GetNetworkCredential().Password } | ConvertTo-Json
$env:SA_TOKEN = (Invoke-RestMethod -Method Post -Uri https://analyticsapi.specvista.com/api/v1/auth/login -ContentType "application/json" -Body $body).user.token
```

Expected result: `SA_TOKEN` is set. On a wrong email or password, the macOS command prints `invalid_credentials` and PowerShell shows a 401 error; `SA_TOKEN` stays empty. Sign-in returns status 201, not 200.

Create a property. `type` is `web`, `mobile`, `backend` or `other`, and defaults to `web`:

```bash
curl -s https://analyticsapi.specvista.com/api/v1/projects \
  -H "Authorization: Bearer $SA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My shop","domain":"example.com","type":"web"}'
```

Expected result: status 201 and a project object with `id` and `apiKey`. List existing properties and their keys with `GET /api/v1/projects`.

## Which type to pick

| Type | Use it for | Notes |
|---|---|---|
| `web` | A website using the browser script | Set `domain` to allow tracking without a key in the page |
| `mobile` | A React Native or Expo app | |
| `backend` | A server sending events | Only backend keys can call `POST /forget` |
| `other` | Anything else | |

## Keep keys safe

- A web key is visible in the page source by design. Anyone with it can send events to that property, never read reports.
- Keep backend keys out of source control. Read them from an environment variable such as `SA_API_KEY`.
- A mobile key ships inside the app, so anyone who unpacks the app can read it. Inject it at build time, for example with `EXPO_PUBLIC_SA_API_KEY`, rather than committing it.
- **Rotate API key** on the Properties page, or `POST /api/v1/projects/{id}/rotate-key`, issues a new key and stops the old one at once. Ask the person first: every place still using the old key stops sending.

## Common errors

| Error code | Meaning | Fix |
|---|---|---|
| `email_taken` | The email already has an account | Sign in instead |
| `password_too_short` | Fewer than 8 characters | Use a longer password |
| `invalid_credentials` | Wrong email or password | Check both. There is no self-serve password reset yet |
| `project_name_required` | The name was missing or blank | Send a non-empty `name` |
| `missing_token`, `invalid_token` | No bearer token, or it expired after 90 days | Sign in again |

Every error is listed in [Errors](https://analytics.specvista.com/docs/errors.md).

## Confirm success

`GET /api/v1/projects` with the bearer token returns the property, or the property shows on the Properties page.

---

<!-- Source: https://analytics.specvista.com/docs/track-web.md -->

# Add tracking to a website

One script tag records pageviews, including route changes in single-page apps, and shows a consent banner. Works with any framework.

## Prerequisites

- A web property and its key. See [Get a project key](https://analytics.specvista.com/docs/get-a-project-key.md).
- A privacy page on the site. The banner links to `/privacy` unless you set `data-privacy-url`.

## 1. Add the script

Paste before `</body>`, replacing `<project key>`:

```html
<script src="https://analyticsapi.specvista.com/api/v1/sdk.js" data-api-key="<project key>" async></script>
```

Next.js App Router, in `app/layout.tsx`:

```tsx
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <footer>
          <a href="#" data-sa-consent-settings>Cookie and analytics settings</a>
        </footer>
        <Script src="https://analyticsapi.specvista.com/api/v1/sdk.js" data-api-key={process.env.NEXT_PUBLIC_SA_API_KEY} strategy="afterInteractive" />
      </body>
    </html>
  );
}
```

A web key is public by design, so a `NEXT_PUBLIC_` variable or a literal key are both fine.

Without a key: if the property's domain is set, leave out `data-api-key`. The script then identifies the site by its hostname, with `www.` ignored.

Expected result: the page loads `sdk.js` with status 200, and a request to `https://analyticsapi.specvista.com/api/v1/ingest` returns 202.

## 2. Understand consent

Until a visitor chooses, and after **Only essential**, the script sends one `pageview` per route change with only the path, the referrer host, the device type and `consent: "essential"`. These still count as pageviews in reports. Custom events and identify calls are dropped. After **Accept analytics and personalisation**, the script:

- stores a first-party visitor id in `localStorage["sa_aid"]` and the cookie `_sa_aid`, and a session id in `sessionStorage`;
- sends full events with the URL, referrer, browser, operating system, screen size, language, time zone and UTM parameters;
- adds a hashed browser fingerprint, built from canvas and font measurements, to help join visits;
- adds an `_sa_x` parameter to links that go to other domains registered on the same account, so a visitor moving between your sites is counted once.

Mention these in your privacy policy.

| Attribute | Default | Effect |
|---|---|---|
| `data-api-key` | none | Project key |
| `data-domain` | the page hostname | Domain to match when there is no key |
| `data-api-url` | `https://analyticsapi.specvista.com/api/v1` | API base |
| `data-privacy-url` | `/privacy` | Link in the banner |
| `data-consent-mode` | `ask` | `essential` never shows the banner, only sends essential pageviews and ignores `data-sa-consent-settings` clicks |

Let visitors change their choice: give any element `data-sa-consent-settings`, for example a footer link labelled "Cookie and analytics settings".

## 3. Send custom events and identify people

```js
window.saTrack?.("checkout.completed", { plan: "pro" });
window.saIdentify?.("user_123", { email: "person@example.com", name: "Ada" });
```

Both only send once the visitor has accepted. The functions exist only after `sdk.js` has run, and calls made earlier are not queued, so use `?.`. In React, call them from client components (`"use client"`) or event handlers. For TypeScript, declare them once, for example in `types/specvista.d.ts`:

```ts
declare global {
  interface Window {
    saTrack?: (event: string, properties?: Record<string, unknown>) => void;
    saIdentify?: (userId: string, traits?: Record<string, unknown>) => void;
    saConsent?: { open: () => void; choice: () => "full" | "essential" | null };
  }
}
export {};
```

Name events `object.action` in lower case. Never put passwords, payment details, messages or other free text in properties.

Other globals: `window.saConsent.open()` reopens the banner and `window.saConsent.choice()` returns `"full"`, `"essential"` or `null`. Each change fires a `sa:consent` event on `window` with `detail.choice`.

## 4. Confirm success

1. Open the site in an ordinary browser window, not a headless or automated one. Events are stored within seconds.
2. Open the property in the dashboard. While no event has arrived, the page says the property has not sent an event yet and checks again every 5 seconds.
3. Or, with a bearer token, call `GET /api/v1/analytics/{projectId}/overview` and check that `total` is above 0. See [Read reports](https://analytics.specvista.com/docs/read-reports.md).

## Common errors

| Symptom | Cause | Fix |
|---|---|---|
| `ingest` returns 401 with code `unregistered_sender` | Wrong key, or no key and the hostname is not a property's domain | Copy the key again from Properties, or set the property's domain |
| `sdk.js` returns 404 | The URL is missing `/api/v1` | Use `https://analyticsapi.specvista.com/api/v1/sdk.js` |
| Requests return 202 but reports stay empty | Your own browser is ignored. The dashboard header has a switch that reads **Track my visits** while your browser is tracked and **Ignoring my visits** while it is ignored; clicking it toggles an `sa_ignore` cookie. New browsers are tracked | Open `https://analyticsapi.specvista.com/api/v1/ingest/ignore-status` in that browser. If `tracking` is false, click **Ignoring my visits** in the dashboard header so it reads **Track my visits** |
| Events from automated tests never appear | Headless browsers, Playwright, Puppeteer, Selenium, curl and similar clients are stored as bot traffic and left out of reports | Test in an ordinary browser |
| Visits from Apple's offices are missing | Requests from Apple's network (17.0.0.0/8) are stored as internal, mainly to keep App Review out of reports | Expected; this applies to every property |
| `saTrack` calls do nothing | The visitor has not accepted analytics | Accept in the banner, or check `window.saConsent.choice()` |
| No script request at all | A content blocker or a Content Security Policy blocks it | Allow `analyticsapi.specvista.com` in `script-src` and `connect-src` |

---

<!-- Source: https://analytics.specvista.com/docs/track-node.md -->

# Add tracking to a Node.js server

Send events such as `signup.completed` or `payment.succeeded` from a server, worker or API built on Node.js, NestJS or Express.

## Prerequisites

- Node.js 18 or later.
- A backend property and its key. See [Get a project key](https://analytics.specvista.com/docs/get-a-project-key.md).
- The key in an environment variable named `SA_API_KEY`. Never commit it. For a quick test in a terminal, set it with `export SA_API_KEY=<project key>` on macOS and Linux, or `$env:SA_API_KEY = "<project key>"` in Windows PowerShell. In production, use your host's secret settings, or a `.env` file that is not committed, loaded with `node --env-file=.env server.js` (Node.js 20.6 or later) or the `dotenv` package.

## 1. Check whether the SDK is on npm

```bash
npm view specvista-analytics-node version
```

- If it prints a version, follow step 2a.
- If it fails with `E404`, the SDK is not published yet. Follow step 2b, which needs no package.

## 2a. With the SDK

```bash
npm install specvista-analytics-node
```

```ts
import { initAnalytics, track, identify } from "specvista-analytics-node";

initAnalytics({ apiKey: process.env.SA_API_KEY! });

track("signup.completed", { userId: user.id, plan: "pro" });
identify(user.id, { email: user.email, name: user.name });
```

`track` returns straight away and swallows network errors and timeouts. It drops event names that do not match `^[a-z][a-z0-9._:-]{1,79}$` (case-insensitive) and every call made before `initAnalytics`. NestJS can construct `new AnalyticsService(process.env.SA_API_KEY!)` as a provider instead. All options are in the [SDK reference](https://analytics.specvista.com/docs/sdks.md).

## 2b. With plain HTTP

Add this helper, which uses the built-in `fetch` and has the same call shape as the SDK's `track`. Save it as `analytics.js`:

```js
const SA_URL = "https://analyticsapi.specvista.com/api/v1";

function track(event, properties = {}) {
  const apiKey = process.env.SA_API_KEY;
  if (!apiKey) return;
  const { userId, sessionId, ...rest } = properties;
  fetch(`${SA_URL}/ingest`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-Api-Key": apiKey },
    body: JSON.stringify({ event, source: "backend", userId, sessionId, properties: rest }),
    signal: AbortSignal.timeout(5000),
  }).catch(() => {});
}

module.exports = { track };
```

That is CommonJS, the default for Express apps. In an ES module project (`"type": "module"` in `package.json`, or TypeScript with ES modules), write `export function track` and drop the `module.exports` line; in TypeScript, type the parameters as `event: string, properties: Record<string, unknown> = {}`. Call it like the SDK:

```js
const { track } = require("./analytics");

track("signup.completed", { userId: String(user.id), plan: "pro" });
```

Always send `source: "backend"`. Without it, requests from HTTP clients whose user agent looks like a script (curl, wget, python-requests, Go and others) are stored as bot traffic and left out of reports.

To attach an email or name to a user, `POST /ingest/identify` with `{"userId":"user_123","email":"person@example.com","name":"Ada"}`. To send up to 100 events in one request, `POST /ingest/batch` with a JSON array. Fields are listed in the [API reference](https://analytics.specvista.com/docs/api.md).

## 3. Test the key from a terminal

macOS and Linux:

```bash
curl -i https://analyticsapi.specvista.com/api/v1/ingest \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $SA_API_KEY" \
  -d '{"event":"setup.checked","source":"backend","properties":{"from":"terminal"}}'
```

Windows PowerShell:

```powershell
$response = Invoke-WebRequest -Method Post -Uri https://analyticsapi.specvista.com/api/v1/ingest -ContentType "application/json" -Headers @{ "X-Api-Key" = $env:SA_API_KEY } -Body '{"event":"setup.checked","source":"backend","properties":{"from":"terminal"}}'
$response.StatusCode
$response.Content
```

Expected result: status 202 and the body `{"ok":true}`. This stores one real event, so send it to the property you are setting up, not to someone else's.

## Deleted accounts

When a user deletes their account, send `account.deleted` with their `userId` from a backend key. Their identity is erased and their events are kept without the user id or personal properties. You can also call `POST /forget` with `{"userId":"user_123"}`. Both are permanent, so only send them for a real deletion.

## Common errors

| Symptom | Cause | Fix |
|---|---|---|
| 401 with code `unregistered_sender` | `SA_API_KEY` is empty, wrong or rotated | Copy the key again from Properties |
| 202 but the event is missing from reports | No `source: "backend"` and a script-like user agent, or `environment` set to something other than `production` | Send `source: "backend"`; leave out `environment` in production |
| `npm install specvista-analytics-node` fails with `E404` | Not published yet | Use step 2b |
| Events arrive twice after a retry | Ingest has no idempotency key yet | Do not retry a request that returned 202 |

## Confirm success

`GET /api/v1/analytics/{projectId}/live-events` with a bearer token lists up to 20 events from the last hour, newest first, including `setup.checked`. On a busy property it can drop out of that list within seconds; check `GET /api/v1/analytics/{projectId}/event-names?period=24h` instead. See [Read reports](https://analytics.specvista.com/docs/read-reports.md).

---

<!-- Source: https://analytics.specvista.com/docs/track-react-native.md -->

# Add tracking to a React Native app

Track app opens, screen views and custom events in a React Native or Expo app on iOS and Android.

## Prerequisites

- A mobile property and its key. See [Get a project key](https://analytics.specvista.com/docs/get-a-project-key.md). The key ships inside the app; inject it at build time, for example as `EXPO_PUBLIC_SA_API_KEY` in Expo, rather than committing it.
- For the SDK: `@react-native-async-storage/async-storage`, and optionally `expo-application` and `expo-device`, which add the vendor device id and the device model.

## 1. Check whether the SDK is on npm

```bash
npm view specvista-analytics-rn version
```

- If it prints a version, follow step 2a.
- If it fails with `E404`, the SDK is not published yet. Follow step 2b.

## 2a. With the SDK

```bash
npm install specvista-analytics-rn @react-native-async-storage/async-storage
```

The package ships TypeScript source, which Metro compiles like your own code. Call `initAnalytics` once, as early as possible:

```ts
import { initAnalytics, track, trackScreen, identify, reset } from "specvista-analytics-rn";

initAnalytics({ apiKey: process.env.EXPO_PUBLIC_SA_API_KEY!, appVersion: "1.4.0", appBuild: "42" });
```

Track screens from React Navigation. `onReady` records the first screen and `onStateChange` the rest. With the helpers from step 2b, import `trackScreen` from `./analytics` instead:

```tsx
import { NavigationContainer, useNavigationContainerRef } from "@react-navigation/native";
import { useRef } from "react";
import { trackScreen } from "specvista-analytics-rn";

export function AppNavigation({ children }: { children: React.ReactNode }) {
  const navigationRef = useNavigationContainerRef();
  const current = useRef<string | undefined>(undefined);
  const record = () => {
    const name = navigationRef.getCurrentRoute()?.name;
    if (name && name !== current.current) trackScreen(name);
    current.current = name;
  };
  return (
    <NavigationContainer ref={navigationRef} onReady={record} onStateChange={record}>
      {children}
    </NavigationContainer>
  );
}
```

Custom events, sign-in and sign-out:

```ts
track("checkout.completed", { plan: "pro" });
identify(user.id, { email: user.email });
reset();
```

What the SDK does for you:

- Sends `app_open` at start-up and every time the app returns to the foreground, with `cold` true when a new session starts. Sessions end after 30 minutes in the background.
- Adds the platform, OS version, app version and build, locale, time zone and a per-install id.
- Sends `environment: "development"` from development builds (`__DEV__`). Those events are stored as internal and left out of reports, so test in a release build.
- For apps directed at children, pass `audience: "child"`: user, install and device ids are never sent and `identify` does nothing.

## 2b. Without the SDK

Save these helpers as `analytics.ts` and import them from `./analytics`. They use `fetch` and have the same names and call shapes as the SDK's `track`, `trackScreen`, `identify`, `setUserId` and `reset`, so moving to the SDK later only changes the import:

```ts
import { AppState, Platform } from "react-native";

const SA_URL = "https://analyticsapi.specvista.com/api/v1";
const SA_KEY = process.env.EXPO_PUBLIC_SA_API_KEY!;
let userId: string | undefined;

export function track(event: string, properties: Record<string, unknown> = {}): void {
  const { userId: explicitUserId, ...rest } = properties;
  fetch(`${SA_URL}/ingest`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-Api-Key": SA_KEY },
    body: JSON.stringify({
      event,
      source: "mobile",
      userId: (explicitUserId as string | undefined) ?? userId,
      os: Platform.OS,
      osVersion: String(Platform.Version),
      environment: __DEV__ ? "development" : "production",
      properties: rest,
    }),
  }).catch(() => {});
}

export function trackScreen(screen: string, properties: Record<string, unknown> = {}): void {
  track("screen_view", { screen, ...properties });
}

export function setUserId(id: string): void {
  userId = id;
}

export function reset(): void {
  userId = undefined;
}

export function identify(id: string, traits: Record<string, unknown> = {}): void {
  userId = id;
  const { email, name, ...rest } = traits;
  fetch(`${SA_URL}/ingest/identify`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-Api-Key": SA_KEY },
    body: JSON.stringify({ userId: id, email, name, traits: rest }),
  }).catch(() => {});
}

let lastState = AppState.currentState;
track("app_open", { cold: true });
AppState.addEventListener("change", (state) => {
  if (state === "active" && lastState === "background") track("app_open", { cold: false });
  lastState = state;
});
```

`screen` ends up in `properties.screen`, as with the SDK. `app_open` is only sent again after the app was in the background, not after a brief interruption such as a permission prompt. This version has no sessions or install ids; add `sessionId`, `installId`, `appVersion` and the other fields from the [API reference](https://analytics.specvista.com/docs/api.md) if you need them.

## Keys in mobile apps

A key shipped in an app can be read by anyone who unpacks it. It can only send events, never read reports. If it leaks into abuse, rotate it and release an app update.

## Common errors

| Symptom | Cause | Fix |
|---|---|---|
| Nothing in reports from the simulator or a debug build | Development builds send `environment: "development"` | Test with a release build. For one check, pass `environment: "production"` to `initAnalytics` (SDK) or change the `environment` line in `analytics.ts` (step 2b), then change it back |
| Events from App Review devices are missing | Requests from Apple's network (17.0.0.0/8) are stored as internal | Expected; they are left out on purpose |
| 401 with code `unregistered_sender` | Wrong or rotated key | Copy the key again from Properties |
| Metro cannot resolve `expo-application` or `expo-device` | Neither is installed and your Metro version does not allow optional requires | Install both, or upgrade Metro |
| `npm install specvista-analytics-rn` fails with `E404` | Not published yet | Use step 2b |

## Confirm success

Open a release build, then call `GET /api/v1/analytics/{projectId}/live-events` with a bearer token and look for `app_open` from the last hour, or open the property in the dashboard. The default user agents of React Native apps are not treated as bots.

---

<!-- Source: https://analytics.specvista.com/docs/read-reports.md -->

# Read reports

Read a property's numbers from the dashboard, or from the API with a bearer token.

## Prerequisites

- An account with at least one property.
- For the API: a bearer token in `SA_TOKEN`, from the sign-in step in [Get a project key](https://analytics.specvista.com/docs/get-a-project-key.md). The person signs in, not the agent, and the token lasts 90 days. There are no read-only or per-property tokens yet, so treat it like the password.

## In the dashboard

Sign in at [analytics.specvista.com/login](https://analytics.specvista.com/login). **Properties** lists every property with live visitors and today's pageviews. Choose a property for charts, top pages, sources, devices, countries, events, funnels and people. **Tracking** shows which properties have gone quiet.

## With the API

Every report is a `GET` under `https://analyticsapi.specvista.com/api/v1` with `Authorization: Bearer $SA_TOKEN`. `period` is `24h`, `7d` or `30d`; any other value is treated as `30d`. Bot traffic, internal traffic (including requests from Apple's network, 17.0.0.0/8) and development builds are excluded everywhere.

1. Find the property id:

```bash
curl -s https://analyticsapi.specvista.com/api/v1/projects -H "Authorization: Bearer $SA_TOKEN"
```

Expected result: a JSON array of properties with `id`, `name`, `type` and `apiKey`.

2. Read the headline numbers:

```bash
curl -s "https://analyticsapi.specvista.com/api/v1/analytics/42/overview?period=7d" -H "Authorization: Bearer $SA_TOKEN"
```

Expected result: `total` (every event the property has ever received, excluding bot and internal traffic), `pageviews`, `uniqueSessions`, `liveVisitors`, `trend` (percentage change in pageviews against the previous 7 days) and `previous`.

Windows PowerShell:

```powershell
Invoke-RestMethod -Uri "https://analyticsapi.specvista.com/api/v1/analytics/42/overview?period=7d" -Headers @{ Authorization = "Bearer $env:SA_TOKEN" }
```

3. Any report in the table below works the same way. For example, the top pages and a signup funnel for the last 7 days:

```bash
curl -s "https://analyticsapi.specvista.com/api/v1/analytics/42/top-pages?period=7d" -H "Authorization: Bearer $SA_TOKEN"
curl -s "https://analyticsapi.specvista.com/api/v1/analytics/42/funnel?period=7d&from=signup.started&to=signup.completed" -H "Authorization: Bearer $SA_TOKEN"
```

```powershell
$headers = @{ Authorization = "Bearer $env:SA_TOKEN" }
Invoke-RestMethod -Uri "https://analyticsapi.specvista.com/api/v1/analytics/42/top-pages?period=7d" -Headers $headers
Invoke-RestMethod -Uri "https://analyticsapi.specvista.com/api/v1/analytics/42/funnel?period=7d&from=signup.started&to=signup.completed" -Headers $headers
```

## How funnels count

A funnel follows each person by `userId`, or by `sessionId` when there is no user id. `started` is the number of people who sent the `from` event in the period. `converted` is how many of them sent the `to` event at or after their first `from` event. `rate` is the percentage, to one decimal place. Because the browser script only sends `userId` after `saIdentify`, a funnel from an anonymous web event to a backend event only joins up when the web visitor was identified with the same user id the server sends.

## Reports

| Question | Endpoint |
|---|---|
| All properties at a glance | `/analytics/global?period=7d` |
| Headline numbers | `/analytics/{id}/overview` |
| Pageviews over time | `/analytics/{id}/pageviews?granularity=day` (or `week`, `month`) |
| Top pages | `/analytics/{id}/top-pages` |
| Where visits start, with bounce rate | `/analytics/{id}/landing-pages` |
| Custom events | `/analytics/{id}/top-events`, `/analytics/{id}/event-names` |
| Conversion between two events | `/analytics/{id}/funnel?from=signup.started&to=signup.completed` |
| Traffic sources | `/analytics/{id}/referrers`, `/analytics/{id}/channels`, `/analytics/{id}/utm-campaigns` |
| Audience | `/analytics/{id}/countries`, `/analytics/{id}/cities`, `/analytics/{id}/devices`, `/analytics/{id}/browsers`, `/analytics/{id}/os`, `/analytics/{id}/sources` |
| Engagement | `/analytics/{id}/bounce-rate`, `/analytics/{id}/new-vs-returning` |
| Identified people | `/analytics/{id}/people` |
| Latest events | `/analytics/{id}/live-events` |
| Raw events as CSV | `/analytics/{id}/export?period=30d` |
| Properties that stopped sending | `/analytics/tracking-health` |

Response shapes are in the [API reference](https://analytics.specvista.com/docs/api.md) and the [OpenAPI document](https://analyticsapi.specvista.com/api/v1/openapi.json).

## Common errors

| Error code | Meaning | Fix |
|---|---|---|
| `missing_token` | No `Authorization` header | Send `Authorization: Bearer $SA_TOKEN` |
| `invalid_token` | The token expired or was changed | Ask the person to sign in again |
| `project_not_found` | No property has that id | List properties with `GET /projects` |
| `project_forbidden` | The property belongs to another account | Use an id from your own `GET /projects` |
| `invalid_funnel_events`, `same_funnel_events` | `from` or `to` missing, or the same | Pick two different names from `/event-names` |

## Confirm success

The overview call returns status 200 with numbers. A `total` of 0 means no events have arrived yet; see the tracking guides.

---

<!-- Source: https://analytics.specvista.com/docs/api.md -->

# API reference

Base URL: `https://analyticsapi.specvista.com/api/v1`. Bodies are JSON. The machine-readable contract is the [OpenAPI document](https://analyticsapi.specvista.com/api/v1/openapi.json), which is checked against the API's routes in its test suite.

## Authentication

| Endpoints | Header |
|---|---|
| `/ingest`, `/ingest/identify`, `/ingest/batch`, `/sdk/linked-domains` | `X-Api-Key: <project key>`. Browsers may send `X-Domain: <hostname>` instead, for a web property with that domain |
| `/forget` | `X-Api-Key` with a backend property's key |
| `/auth/me`, `/auth/password`, `/auth/profile`, `/projects`, `/analytics/...` | `Authorization: Bearer <token>`, where the token is `user.token` from `/auth/login` or `/auth/register` |
| `/auth/login`, `/auth/register`, `/sdk.js`, `/openapi.json`, `/ingest/ignore-*` | None |

## Send events

### POST /ingest

Stores one event, usually within a second. Returns `202 {"ok":true}` straight away; processing happens afterwards, so an event that fails to store is dropped silently rather than rejected, and there is no way to see dropped events yet.

| Field | Type | Notes |
|---|---|---|
| `event` | string | For example `signup.completed`. Defaults to `pageview`. The API stores up to 100 characters and does not check the format; the Node.js SDK only sends names matching `^[a-z][a-z0-9._:-]{1,79}$` |
| `source` | `web`, `mobile` or `backend` | Defaults to `web`. Servers must send `backend` |
| `userId` | string | Your user id, up to 255 characters |
| `sessionId` | string | Up to 100 characters |
| `properties` | object | Your own structured fields. No secrets or free text |
| `environment` | `development`, `preview` or `production` | Anything except `production` is stored as internal and left out of reports |
| `consent` | `full` or `essential` | `essential` stores only the event, path, referrer, device type and country |
| `url`, `path`, `referrer` | string | Web context. UTM parameters are read from `url` |
| `os`, `osVersion`, `appVersion`, `appBuild`, `deviceModel` | string | App context |
| `deviceType`, `browser`, `language`, `locale`, `timezone`, `screenWidth`, `screenHeight` | | Device context |
| `utmSource`, `utmMedium`, `utmCampaign`, `utmContent`, `utmTerm` | string | Override values read from `url` |
| `anonymousId`, `installId`, `deviceId` | string | Visitor and install identifiers |

Country, region and city come from the request IP address. Events whose user agent looks like a bot or script (crawlers, headless browsers, Playwright, Puppeteer, Selenium, curl, wget, python-requests, Go's HTTP client, uptime monitors) are stored as bot traffic unless `source` is `backend`. The default user agents of mobile apps (`okhttp` on Android, `CFNetwork` on iOS) are not. Events from Apple's network (17.0.0.0/8, which App Review uses) are stored as internal. Bot and internal events are left out of every report.

There is no idempotency key yet: a retried request stores a second event.

### POST /ingest/batch

A JSON array of events, or `{"events":[...]}`. At most 100 are stored per request. Returns `202 {"ok":true,"queued":<number received>}`.

### POST /ingest/identify

`{"userId":"user_123","email":"person@example.com","name":"Ada","traits":{"plan":"pro"}}`. Attaches an identity to a user id so people show by name. Blank fields never overwrite stored ones. Add `"emailStorage":"hash_only"` to store only a salted hash of the email. Returns `202 {"ok":true}`, or `202 {"ok":false,"error":"userId required"}`.

### POST /forget

`{"userId":"user_123"}` with a backend key, and optionally `"projectId"` for another property owned by the same account. Deletes the stored identity and strips the user id and personal properties from that user's events. Returns 204. Permanent. Limited per key per minute. Sending the event `account.deleted` with a `userId` from a backend key does the same.

### GET /ingest/ignore-on, /ingest/ignore-off, /ingest/ignore-status

Set, clear or read the `sa_ignore` cookie in the calling browser. While it is set, ingest returns `{"ok":true,"skipped":true}` and stores nothing.

## Account

| Method and path | Body | Result |
|---|---|---|
| `POST /auth/register` | `email`, `password` (8 or more characters), `firstName`, `lastName` | 201 `{"user":{...,"token":"..."}}` |
| `POST /auth/login` | `email`, `password` | 201 `{"user":{"id","uuid","email","firstName","lastName","token"}}` |
| `GET /auth/me` | | The account |
| `PATCH /auth/password` | `currentPassword`, `newPassword` | `{"ok":true}` |
| `PATCH /auth/profile` | `firstName`, `lastName` | The account with a fresh token |

Tokens last 90 days and cannot be revoked early; changing the password does not end existing tokens.

## Properties

| Method and path | Body | Result |
|---|---|---|
| `GET /projects` | | Your properties, newest first, each with `id`, `name`, `slug`, `apiKey`, `domain`, `type`, `createdAt` |
| `POST /projects` | `name` (required), `domain`, `type` (`web`, `mobile`, `backend`, `other`) | 201 and the property |
| `GET /projects/{id}` | | The property |
| `PATCH /projects/{id}` | `name`, `domain` | The property |
| `DELETE /projects/{id}` | | `{"ok":true}` |
| `POST /projects/{id}/rotate-key` | | 201 and the property with a new `apiKey`. The old key stops at once |

## Reports

All `GET`, with a bearer token, `period` of `24h`, `7d` or `30d` (default `30d`). Bot and internal traffic is excluded.

| Path | Returns |
|---|---|
| `/analytics/global` | Per property: `live`, `pageviewsToday`, `pageviewsPeriod`; plus totals |
| `/analytics/{id}/overview` | `total`, `pageviews`, `uniqueSessions`, `liveVisitors`, `trend`, `previous` |
| `/analytics/{id}/pageviews` | `[{date, views}]`; `granularity` is `day`, `week` or `month` |
| `/analytics/{id}/top-pages` | Top 10 `[{path, views, sessions}]` |
| `/analytics/{id}/landing-pages` | `{sessions, pages:[{path, sessions, bounced, bounceRate}]}` |
| `/analytics/{id}/top-events` | Top 10 non-pageview `[{event, source, count}]` |
| `/analytics/{id}/event-names` | Up to 50 `[{event, count}]` |
| `/analytics/{id}/funnel?from=&to=` | `{fromEvent, toEvent, period, current, previous}`, each with `started`, `converted`, `rate` |
| `/analytics/{id}/referrers` | Top 10 `[{referrer, visits}]` |
| `/analytics/{id}/channels` | `[{channel, count}]`: Organic, Direct, Referral, Social, Email, Paid |
| `/analytics/{id}/utm-campaigns` | Top 20 `[{campaign, source, medium, visits}]` |
| `/analytics/{id}/sources`, `/devices`, `/browsers`, `/os` | `[{<field>, count}]` |
| `/analytics/{id}/countries` | Top 50 `[{countryCode, country, visits}]` |
| `/analytics/{id}/cities` | Top 20 `[{city, region, countryCode, country, visits}]` |
| `/analytics/{id}/bounce-rate` | `{bounceRate}` as a whole percentage |
| `/analytics/{id}/new-vs-returning` | `{new, returning}` among identified users |
| `/analytics/{id}/people` | Up to 500 user ids active in the period, with email and name where identified |
| `/analytics/{id}/live-events` | Up to 20 events from the last hour |
| `/analytics/{id}/export` | CSV of up to 50,000 events |
| `/analytics/tracking-health` | Whether each property is still receiving events |

## Other

- `GET /sdk.js` and `GET /sdk.min.js`: the browser script.
- `GET /sdk/linked-domains`: domains of the same account, used by the script to link visitors across your sites.
- `GET /openapi.json`: the OpenAPI 3.0 document.

## Errors

Every error code, and what to do about it, is in [Errors](https://analytics.specvista.com/docs/errors.md).

---

<!-- Source: https://analytics.specvista.com/docs/sdks.md -->

# SDK reference

| SDK | How to get it | Status |
|---|---|---|
| Browser script | `<script src="https://analyticsapi.specvista.com/api/v1/sdk.js">` | Live |
| Node.js and NestJS | `npm install specvista-analytics-node` | Prepared, not yet on npm. Check with `npm view specvista-analytics-node version` |
| React Native and Expo | `npm install specvista-analytics-rn` | Prepared, not yet on npm. Check with `npm view specvista-analytics-rn version` |
| Anything else | The HTTP API | Live. See [API reference](https://analytics.specvista.com/docs/api.md) |

Until a package is on npm, use the plain HTTP helpers in [Add tracking to a Node.js server](https://analytics.specvista.com/docs/track-node.md) and [Add tracking to a React Native app](https://analytics.specvista.com/docs/track-react-native.md).

## Browser script

Script attributes: `data-api-key`, `data-domain`, `data-api-url`, `data-privacy-url` and `data-consent-mode`. Details and the consent rules are in [Add tracking to a website](https://analytics.specvista.com/docs/track-web.md).

| Global | Does |
|---|---|
| `saTrack(event, properties?)` | Sends a custom event once the visitor has accepted analytics |
| `saIdentify(userId, traits?)` | Attaches an identity and uses `userId` on later events, once accepted |
| `saConsent.open()` | Reopens the consent banner |
| `saConsent.choice()` | `"full"`, `"essential"` or `null` |

The script sends a `pageview` on load and on every `pushState`, `replaceState` and `popstate` that changes the path.

## specvista-analytics-node

Node.js 18 or later.

| Export | Does |
|---|---|
| `initAnalytics({ apiKey, apiUrl?, source?, timeoutMs? })` | Configures the SDK. `apiUrl` defaults to `https://analyticsapi.specvista.com/api/v1`, `source` to `backend`, `timeoutMs` to 5000 |
| `track(event, properties?)` | Sends an event. `properties.userId` and `properties.sessionId` become top-level fields. Drops names that do not match `^[a-z][a-z0-9._:-]{1,79}$` (case-insensitive) |
| `identify(userId, { email?, name?, ...traits })` | Attaches an identity |
| `new AnalyticsService(apiKey, apiUrl?, timeoutMs?)` | A class wrapper with `track` and `identify`, for dependency injection |

Calls return straight away, do nothing before `initAnalytics`, and swallow network errors and timeouts.

## specvista-analytics-rn

Peer dependencies: `react-native` and `@react-native-async-storage/async-storage`. Optional: `expo-application` and `expo-device`.

| Export | Does |
|---|---|
| `initAnalytics({ apiKey, apiUrl?, userId?, appVersion?, appBuild?, audience?, environment? })` | Configures the SDK and sends `app_open`. `audience` is `general` or `child`. `environment` defaults to `development` in `__DEV__` builds and `production` otherwise |
| `track(event, properties?)` | Sends an event with session, platform, app and locale context |
| `trackScreen(name, properties?)` | Sends `screen_view` with `screen` set to the name |
| `identify(userId, { email?, name?, ...traits })` | Sets the user for later events and attaches an identity. Does nothing for `audience: "child"` |
| `setUserId(userId)` | Sets the user for later events without an identify call |
| `reset()` | Clears the user and starts a new session, for sign-out |
| `stopAnalytics()` | Stops sending and clears the stored session and install ids |

---

<!-- Source: https://analytics.specvista.com/docs/errors.md -->

# Errors

API errors return JSON with a stable `code`, a plain `message`, and a `doc_url` that links to the matching section below:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "code": "unregistered_sender",
  "message": "Unregistered sender. Send a valid project key in the X-Api-Key header, or set this site's domain on a web property.",
  "doc_url": "https://analytics.specvista.com/docs/errors#unregistered_sender"
}
```

Match on `code`, never on `message`, which may change. Some older responses, such as validation from the account page, have no `code`. Each `doc_url` opens this page; agents can read the same section as Markdown at `https://analytics.specvista.com/docs/errors.md`.

## Sending events

### unregistered_sender

401 from `/ingest`, `/ingest/identify`, `/ingest/batch` and `/sdk/linked-domains`. No property matches the `X-Api-Key` header, or, without a key, the `X-Domain` header or `domain` field. Copy the key again from the Properties page or `GET /projects`. The key may have been rotated. For keyless browser tracking, set the property's domain to the site's hostname without `www.`.

### invalid_api_key

401 from `/forget`. The `X-Api-Key` header is missing or matches no property. Send a backend property's key.

### backend_key_required

403 from `/forget`. Only keys of backend properties can forget users. Create a backend property and call `/forget` from your server.

### forget_forbidden

403 from `/forget`. The `projectId` in the body belongs to another account. Use a backend key from the account that owns that property.

### user_id_required

400 from `/forget`. Send `userId` as a non-empty string or number.

### invalid_project_id

400 from `/forget`. `projectId` must be an integer.

### rate_limited

429 from `/forget`. Too many requests for this key in the last minute. Wait a minute, then retry.

## Signing in

### missing_token

401. The request has no `Authorization: Bearer` header. Sign in with `POST /auth/login` and send `user.token`.

### invalid_token

401. The token is malformed or more than 90 days old. Sign in again.

### invalid_credentials

401 from `/auth/login`. The email or password is wrong. The same message is used for both. There is no self-serve password reset yet.

### credentials_required

400 from `/auth/login`. Send both `email` and `password`.

### email_required

400 from `/auth/register`. Send `email`.

### first_name_required

400 from `/auth/register`. Send `firstName`.

### password_too_short

400 from `/auth/register` and `/auth/password`. Passwords need at least 8 characters.

### email_taken

409 from `/auth/register`. An account already uses this email. Sign in instead.

### current_password_incorrect

400 from `/auth/password`. `currentPassword` does not match.

### admin_required

403. The endpoint is for the Specvista Analytics operator only and is not part of the public API.

## Properties and reports

### project_name_required

400 from `POST /projects`. Send a non-empty `name`.

### invalid_project_type

400 from `POST /projects`. `type` must be `web`, `mobile`, `backend` or `other`, or left out for `web`.

### project_not_found

404. No property has that id. List yours with `GET /projects`.

### project_forbidden

403. The property belongs to another account. Use an id from your own `GET /projects`.

### invalid_funnel_events

400 from `/analytics/{id}/funnel`. `from` and `to` must both be event names of up to 100 characters. Get names from `/analytics/{id}/event-names`.

### same_funnel_events

400 from `/analytics/{id}/funnel`. `from` and `to` must be different events.

## Responses that are not errors

- `202 {"ok":true,"skipped":true}`: this browser has the `sa_ignore` cookie, so nothing was stored. Clear it with `GET /ingest/ignore-off` from that browser.
- `202 {"ok":false,"error":"userId required"}` from `/ingest/identify`: send `userId`.
- `202` but the event is missing from reports: it was stored as bot or internal traffic. See the common errors in [Add tracking to a Node.js server](https://analytics.specvista.com/docs/track-node.md) and [Add tracking to a website](https://analytics.specvista.com/docs/track-web.md).