---
name: kestrel-analytics
description: >-
Install privacy-friendly traffic analytics and a live visitor badge on a
website. Pairs to the user's Kestrel account, finds or creates the site,
installs the snippet, and verifies that a real pageview arrived. Use when
asked to add analytics, a hit counter, or a visitor badge to a site or
landing page.
---
# Adding Kestrel analytics to a site
Kestrel counts visitors without cookies, without storing addresses, and without
anything for an ad blocker to remove. Installing it is two tags: a script that
counts, and an image that shows the count.
This document is the whole procedure. Follow it in order. **Do not stop after
Step 3** — Step 4 is what tells you whether any of it worked.
Everything below is at `https://kestrel.host`.
---
## Working with the person
Three of the steps here are theirs rather than yours: approving the pairing,
saying which domain is the real one, and saying where the badge goes and what it
looks like. Ask, and wait for the answer. The middle one is already settled if
you were given a site name — the domain came with it, so do not ask again.
Whoever sent you here was probably handed a line ending *"ask me along the way
where the badge should sit and how it should look"* — so those questions are
expected of you, not an interruption.
They may never have heard of Kestrel, and unless they sent you here from a page
of their own you are about to ask them to make an account. One sentence covers
it: it counts visitors without cookies and without storing addresses, the badge
is an image they can put anywhere including a README, and they can take your key
back whenever they like from their own page.
Say what you are doing as you go, and say plainly when it works. Nothing below
needs their password, and nothing below needs anything from them but one click
and two small decisions.
---
## Before you start
**Look for a key you already have.** In order:
1. The `KESTREL_API_KEY` environment variable.
2. `~/.kestrel/key` — a file with the key on one line.
If you find one, skip to Step 2. Pairing again when a key already exists leaves
the user with a list of keys they have to sort out by hand.
**Ask the user for their domain** if you do not already know it — the real
domain the site is served from in production, not `localhost` and not a preview
URL. You need it in Step 2, and getting it wrong is the single commonest way
this ends up silently counting nothing.
**Unless you were given a site name.** A hyphenated name like
`bell-violet-sunlit-iron-valley` means the site already exists and its domain is
already set — Step 2 reads it off the site rather than asking you for it. Do not
ask, and do not substitute a domain of your own.
---
## Step 1 — Pair with the user's account
Only if you have no key.
```bash
curl -sX POST https://kestrel.host/api/pair \
-H 'Content-Type: application/json' \
-d '{"label": ""}'
```
```json
{
"ok": true,
"code": "WREN-4207",
"secret": "…",
"verify_url": "https://kestrel.host/pair",
"expires_in": 600,
"interval": 3
}
```
**Show the user the `code` and the `verify_url`, and stop to let them act.** Say
something like:
> Open https://kestrel.host/pair and enter **WREN-4207** to connect your Kestrel account.
> I'll wait.
If they have never used Kestrel, that page offers to make them an account and
brings them back to the code with it already filled in — so waiting is still the
right thing to do. If they already have one and are signed in — which they are
if they handed you this from a page of their own — approving is a single click
and should take seconds. Either way: do not try to make the account for them,
and never ask them for their password. The key arrives on its own.
Then poll, every `interval` seconds, until it answers:
```bash
curl -sX POST https://kestrel.host/api/pair/poll \
-H 'Content-Type: application/json' \
-d '{"secret": ""}'
```
- `{"status": "pending"}` — they have not approved yet. Wait `interval` seconds
and ask again. Give up after `expires_in` seconds and tell the user the code
expired.
- `{"status": "ok", "key": "ksk_…"}` — done.
If they come back and tell you the box is not taking new accounts, that is real
and not something to retry. Stop polling, tell them what they told you, and
leave it there rather than spending the whole `expires_in` window on it.
**Save the key immediately.** It is shown exactly once and cannot be recovered.
Write it to `~/.kestrel/key` with mode 600, or tell the user to export it as
`KESTREL_API_KEY`.
**Never write the key into the project.** Not into a `.env` that is committed,
not into source, not into a config file, not into a README. It is a credential
for the user's whole Kestrel account, not a per-project setting.
---
## Step 2 — Get the site
**If you were given a site name, it already exists. Read it; do not create it.**
```bash
curl -s https://kestrel.host/api/sites/ -H "Authorization: Bearer $KESTREL_API_KEY"
```
That returns everything the POST below does — the same `snippet` and `badge`
strings Step 3 installs — plus `domains`, the hosts this site counts, and
`problem`, which Step 4 is about. Take the domain from `domains` rather than
from anywhere else, and go to Step 3.
Getting this wrong is expensive and quiet. Somebody who signed up in a browser
already has a site with their own domain on it; the domain you would have posted
is the one you worked out from the project, and for a repo that knows itself only
as `myapp.vercel.app` those are not the same string. A different domain makes a
**second site**. They end up with two, the new one permanently empty, and nothing
on either page explains why.
**Otherwise — no site name, and you have their domain — make one:**
```bash
curl -sX POST https://kestrel.host/api/sites \
-H "Authorization: Bearer $KESTREL_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"domain": "example.com"}'
```
```json
{
"ok": true,
"created": true,
"slug": "bell-violet-sunlit-iron-valley",
"site_url": "https://kestrel.host/s/bell-violet-sunlit-iron-valley",
"badge_url": "https://kestrel.host/b/bell-violet-sunlit-iron-valley",
"json_url": "https://kestrel.host/b/bell-violet-sunlit-iron-valley?format=json",
"snippet": "",
"badge": "\n ![\"Traffic](\"…\")
\n"
}
```
**This is safe to call twice.** If the account already has a site for that
domain you get that site back with `"created": false`, and nothing is made. Do
not try to avoid calling it — call it, and read `created` if you want to know.
**One site per domain, not per page.** A site counts a whole website. If the
user has three pages on one domain, that is one site and the snippet goes on all
three.
---
## Step 3 — Install the two tags
Use the `snippet` and `badge` strings exactly as they came back.
**`snippet`** — the counting script. Put it on every page you want counted.
Anywhere before ` `; inside `