---
title: "Visitor analytics"
description: "Cookieless visitor counts for your blog: the script tag and its attributes, when it stays silent, the domains that count, verifying an install, and the analytics API."
canonical: "https://writavo.com/docs/analytics"
---

# Visitor analytics

Visitors, pages, sources, countries and devices for your blog, with no cookies. Hosted blogs are counted already; a site you render yourself needs one script tag.

## Hosted blogs need nothing

Blogs Writavo serves (your writavo.com address, a custom domain or a reverse proxy) already carry the tag. Open Visitors in the dashboard. The rest of this page is for a site you render yourself.

## Add the script to your own site

Paste this into the <head> of every page that shows your articles, in the HTML your server sends:

html:

```
<script defer src="https://blog.writavo.com/api/a/s" data-site="wa_0123456789abcdef01234567"></script>
```

- Keep `src` as it is. Never use a `localhost` address: readers cannot reach it.
- Your site id is public, not a key. Copy the ready snippet from Visitors > Setup, or `snippet` from `GET /v1/analytics/setup`.
- The page's domain must be one the Site counts (see [Domains that count](#domains)).

## Next.js and React

Put the tag once, in the root layout's head. It counts client-side navigation by itself.

app/layout.tsx (Next.js App Router):

```
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <script
          defer
          src="https://blog.writavo.com/api/a/s"
          data-site="wa_0123456789abcdef01234567"
          data-include="^/blog(/|$)"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

- **Pages Router:** inside `<Head>` in `pages/_document.tsx`. **Vite or Create React App:** in `index.html`.
- **`next/script`** also counts, but the install check (which reads server HTML) reports the tag missing. Confirm with `install.last_event_at` instead.
- **Never** load it as `type="module"` or bundle it: it finds its own tag through `document.currentScript`.

## Content-Security-Policy

If your site sends a Content-Security-Policy, add the collector to script-src and connect-src (if you set data-api, allow that origin in connect-src instead):

header:

```
Content-Security-Policy: script-src 'self' https://blog.writavo.com; connect-src 'self' https://blog.writavo.com
```

## Verify the install

The collector answers 202 to everything, so a 202 proves nothing. Instead:

1. **Run the install check.** Visitors > Setup > Check installation, or `POST /v1/analytics/install-check` with the page's `url`.
2. **Visit the page in an ordinary browser.** Not an automated one, and not one where you set `writavo_ignore`: those are never counted.
3. **Read what arrived.** `GET /v1/analytics/setup` shows `install.last_event_at` and `events_24h` within seconds. Visitor totals update every 15 minutes.
4. **Nothing arrived?** A host in `install.rejected_hosts` needs adding to `extra_domains`. No hosts and no events: check the tag is in the server HTML, your Content-Security-Policy, ad blockers, and that you are not on `localhost`.

## Leave your own visits out

Run this in the browser console on your site:

browser console:

```
localStorage.writavo_ignore = "true"
```

It applies per browser and per domain. To be counted again, run localStorage.removeItem("writavo_ignore").

## Domains that count

Only the Site's own domains count, so nobody can push fake traffic into your numbers:

- the primary domain and its subdomains (`primary_domain`)
- custom domains that have not failed verification, exact match (`custom_hostname`)
- a connected reverse proxy's domain, plus its `www.` form (`proxy`)
- up to 20 extra domains you add, with subdomains (`extra_domain`), under Visitors > Setup or with `PATCH /v1/analytics/settings`

Beacons from other hosts are dropped and listed under Visitors > Setup and in install.rejected_hosts. Add any you expected as an extra domain.

> Nothing is counted while analytics is off or the organisation is not active. Switching off keeps the numbers already collected.

## Attributes

| Attribute | Required | What it does |
|---|---|---|
| `data-site` | yes | Your site id, `wa_` plus 24 hexadecimal characters. Without it nothing runs. |
| `data-include` | no | A regular expression on the path only. Only matching pages count. Case sensitive and not anchored (start with `^`). An invalid one is ignored. |
| `data-api` | no | Where beacons go. Default: the script's origin plus `/api/a/e`. |
| `defer` | recommended | Does not hold up the page. |

data-include examples:

```
<!-- only /blog and everything under it -->
<script defer src="https://blog.writavo.com/api/a/s" data-site="wa_0123456789abcdef01234567"
  data-include="^/blog(/|$)"></script>

<!-- the blog under an optional two-letter locale: /blog/..., /en/blog/..., /de/blog/... -->
<script defer src="https://blog.writavo.com/api/a/s" data-site="wa_0123456789abcdef01234567"
  data-include="^/([a-z]{2}/)?blog(/|$)"></script>
```

> Leave data-api unset if you can. Through your own server, readers can merge into one visitor, locations become your server's, and all traffic shares one limit of 300 events a minute. If you must, forward the body unchanged as text/plain to https://blog.writavo.com/api/a/e with the reader's User-Agent.

## What the script does

- A pageview on load and on each client-side navigation (`pushState`, back and forward). Not on `replaceState`, a `#fragment` change or the same address.
- When the reader leaves a page, the time the tab was visible (if one second or more).
- A same-site referral (with or without `www.`) is not a source.
- Sends with `navigator.sendBeacon` as `text/plain`: no CORS preflight, no cookies. Loading it twice is harmless.
- The collector always answers `202`, so nobody can probe which site ids exist.

## When the script stays silent

The script sends nothing when:

- the host is `localhost`, `127.*`, `0.0.0.0` or `[::1]`, or the page is a `file:` address (other private hosts send, and are turned away);
- the browser is automated (`navigator.webdriver`, Cypress, PhantomJS or Nightmare);
- `localStorage.writavo_ignore` is exactly `"true"`;
- the tag has no `data-site`, or is loaded as `type="module"`.

## What it counts, and what it keeps

On for every Site and free on every plan. It counts pageviews, unique visitors, bounces and time on page, by page, entry page, source, referrer, UTM tags, location, device, browser and operating system.

- **No cookies, storage ids or fingerprints,** so no consent banner of its own. A visitor is a hash of a daily random salt, the Site, the IP address and the user agent. The salt is deleted the next day, so a person counts as new each day.
- **Never stored:** the IP address, full user agent, query string, full referrer URL, or anything that identifies a person.
- **Stored per event:** the hash, page host and path, referrer host, UTM tags, country, region, city, browser, operating system, device class and visible time.
- **Kept:** raw events for 90 days, daily totals for the life of the Site.
- **Dropped:** known bots, prefetch and prerender requests, and over 300 events a minute from one address.

## The analytics API

Four operations on https://api.writavo.com/v1, with a secret key. Free on every plan.

| Request | Scope | What it does |
|---|---|---|
| `GET /analytics/setup` | `insights:read` | Site id, snippet, counted domains, recent arrivals |
| `PATCH /analytics/settings` | `site:write` | Turn collecting on or off; set extra domains |
| `GET /analytics/visitors` | `insights:read` | The visitor report |
| `POST /analytics/install-check` | `insights:read` | Check a page for the tag |

## GET /analytics/setup

curl:

```bash
curl -s https://api.writavo.com/v1/analytics/setup \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY"
```

200 response:

```json
{
  "ok": true,
  "data": {
    "site_id": "wa_0123456789abcdef01234567",
    "enabled": true,
    "collector_origin": "https://blog.writavo.com",
    "script_url": "https://blog.writavo.com/api/a/s",
    "snippet": "<script defer src=\"https://blog.writavo.com/api/a/s\" data-site=\"wa_0123456789abcdef01234567\"></script>",
    "extra_domains": [],
    "allowed_domains": [
      { "domain": "example.com", "source": "primary_domain", "subdomains": true },
      { "domain": "blog.example.com", "source": "custom_hostname", "subdomains": false }
    ],
    "install": {
      "last_event_at": "2026-10-04T09:12:44Z",
      "last_event_host": "example.com",
      "last_event_path": "/blog/hello-world",
      "events_24h": 12,
      "rejected_hosts": [
        { "hostname": "staging.example.net", "hits": 3, "last_seen_at": "2026-10-04T08:55:02Z" }
      ]
    },
    "docs_url": "https://writavo.com/docs/analytics"
  }
}
```

- The `last_event_*` fields are `null` until the first event (they look back 90 days).
- `rejected_hosts`: today and yesterday (UTC), newest first, at most 20.

## PATCH /analytics/settings

curl:

```bash
curl -s -X PATCH https://api.writavo.com/v1/analytics/settings \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "extra_domains": ["example.org", "app.example.net"] }'
```

- Send `enabled`, `extra_domains` (up to 20), or both. Anything else is `422 VALIDATION_FAILED`.
- `extra_domains` replaces the whole list. A pasted URL is reduced to its lower-case domain.
- Returns the same body as `GET /analytics/setup`.

## GET /analytics/visitors

curl:

```bash
curl -s "https://api.writavo.com/v1/analytics/visitors?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY"
```

200 response (shortened):

```json
{
  "ok": true,
  "data": {
    "from": "2026-09-01",
    "to": "2026-09-30",
    "totals": {
      "visitors": 4120, "pageviews": 6935, "bounces": 2810,
      "engaged_ms": 391204000, "engaged_samples": 5230, "avg_engaged_seconds": 75
    },
    "previous": {
      "visitors": 3644, "pageviews": 6012, "bounces": 2501,
      "engaged_ms": 340110000, "engaged_samples": 4602, "avg_engaged_seconds": 74
    },
    "daily": [
      { "day": "2026-09-01", "visitors": 131, "pageviews": 220, "bounces": 90,
        "engaged_ms": 12001000, "engaged_samples": 160 }
    ],
    "breakdowns": {
      "page": [
        { "value": "/blog/hello-world", "visitors": 812, "pageviews": 1010, "bounces": 640,
          "engaged_ms": 80100000, "engaged_samples": 900 }
      ],
      "source": [
        { "value": "Google", "visitors": 2210, "pageviews": 3400, "bounces": 1500,
          "engaged_ms": 190000000, "engaged_samples": 2600 }
      ],
      "entry_page": [], "referrer": [], "utm_source": [], "utm_medium": [], "utm_campaign": [],
      "country": [], "region": [], "city": [], "device": [], "browser": [], "os": []
    }
  }
}
```

- `from` and `to`: inclusive UTC dates, default the last 30 days, at most 400 days apart.
- `previous` is the same length just before `from`. `daily` has every day, zeros included.
- 13 breakdowns, up to 50 rows each, most visitors first. `entry_page` counts visits by landing page; `page` counts views.
- A bounce is a visitor with one pageview that day. `avg_engaged_seconds` is `engaged_ms / engaged_samples`.
- Rolled up every 15 minutes; yesterday is final just after midnight UTC.

## POST /analytics/install-check

curl:

```bash
curl -s -X POST https://api.writavo.com/v1/analytics/install-check \
  -H "Authorization: Bearer $WRITAVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/blog/hello-world" }'
```

200 response:

```json
{
  "ok": true,
  "data": {
    "url": "https://example.com/blog/hello-world",
    "final_url": "https://example.com/blog/hello-world",
    "status": "ok",
    "checks": [
      { "key": "page_reachable", "ok": true, "message": "The page answered HTTP 200 with HTML." },
      { "key": "tag_present", "ok": true, "message": "Found the analytics script tag in the page's HTML." },
      { "key": "site_id_matches", "ok": true, "message": "data-site is this Site's id (wa_0123456789abcdef01234567)." },
      { "key": "collector_public", "ok": true, "message": "The script loads from the public collector (https://blog.writavo.com)." },
      { "key": "include_matches", "ok": true, "message": "data-include matches this page's path (/blog/hello-world), so the page is counted." },
      { "key": "collecting_enabled", "ok": true, "message": "Collecting is on for this Site." },
      { "key": "recent_events", "ok": true, "message": "12 events arrived in the last 24 hours. The last arrived at 2026-10-04T09:12:44Z from example.com/blog/hello-world." }
    ],
    "script": {
      "found": true,
      "src": "https://blog.writavo.com/api/a/s",
      "site_id": "wa_0123456789abcdef01234567",
      "data_include": "^/blog(/|$)",
      "data_api": null
    },
    "install": {
      "last_event_at": "2026-10-04T09:12:44Z",
      "last_event_host": "example.com",
      "last_event_path": "/blog/hello-world",
      "events_24h": 12,
      "rejected_hosts": []
    }
  }
}
```

- `url` must be on a domain the Site counts, or it is `422 VALIDATION_FAILED`. Default: the first verified custom domain, else the primary domain.
- Reads the server HTML (10 second timeout) without running scripts.
- `status` is `failed` if `page_reachable`, `tag_present`, `site_id_matches` or `collecting_enabled` failed, `warning` if only the others failed, otherwise `ok`.
- Branch on each check's `key` and `ok`. Show `message` to a person; do not parse it.
- `recent_events` needs one real visit; the check itself is never counted.

## From an AI assistant (MCP)

Find these with search_writavo_actions (for example "analytics setup"). Run reads with read_writavo_action and changes with run_writavo_action. The connection needs Reports and logs to read, and Site settings to change the domains.

## Agent checklist

Asked to "add Writavo analytics to my site", do this in order:

1. **Read the setup.** `GET /v1/analytics/setup`. If `enabled` is false, ask the person before turning it on.
2. **Skip installing on hosted pages.** The writavo.com address and `custom_hostname` or `proxy` domains already have the tag: go to step 5.
3. **Make sure the domain counts.** If `allowed_domains` does not cover it, send `PATCH /v1/analytics/settings` with the current `extra_domains` plus the new one (the list is replaced).
4. **Paste `snippet` unchanged, once, in the server-rendered root `<head>`.** Add `data-include` only for a blog inside a bigger app. Never use a local `src`. Update the Content-Security-Policy if there is one.
5. **Run the install check** until `status` is `ok`, or `warning` with only `recent_events` failing.
6. **Get one real visit** from the person's ordinary browser, then confirm `install.last_event_at`. If it is still null, check `install.rejected_hosts`.
7. **Report back** the counted domain, the last event time, and that totals appear within 15 minutes.
