# IPBlade for agents

This file does three jobs: it tells you what IPBlade is, it takes you through deploying an instance of your own, and it shows how to install visitor tracking in the application you are working on. After that comes the API playbook that registers a site, confirms the install and reads the numbers back.

Send `Accept: text/markdown` with any request to a page of the marketing site and the server answers with this document rather than the HTML page.

## What IPBlade is

IPBlade is a web analytics suite you can host yourself: a Node.js monolith with a MySQL database behind it, no framework, no build step for the server.

- One instance serves many sites. Each site is a row you register, and every page load is attributed to a site by the host in the `Referer` header of the tracking request.
- It records hits, visitors, pageviews, bounce rate and a round-trip `ping` per day, and enriches each hit with city and autonomous-system data from MaxMind GeoLite2, the client's browser, screen and language claims, and a network category that marks VPNs, datacenters, Tor exits, academic networks and crawlers apart from ordinary visitors.
- The dashboard is server-rendered HTML with a WebSocket feed for the live view. Sections are live, history, stats and a per-domain detail panel that carries the month chart and the whois facts.
- The REST API lives under `/api/v1` and authenticates with a 64-character `X-Token`. The playbook at the end of this file uses it.
- Installation on a site you want to measure is one `<script>` tag. There is nothing to build, bundle or configure per site.

## Deploying IPBlade yourself

The steps below produce a running instance on a fresh 64-bit Linux host. They assume root: the tree has no ACL awareness and everything runs as root.

### Step D0 — Obtain the source tree

There is no public clone URL. The tree is distributed by its operator, over a private git remote or as an archive. Ask the operator for it, or use the copy you were given. Do not invent a remote, guess a GitHub repository or clone something with a similar name; a wrong tree wastes the whole deployment and the mistake is invisible until the app fails to boot.

### Step D1 — Host requirements

- 64-bit Linux, Ubuntu in the reference deployment.
- Node 22.
- MySQL 8, reachable over TCP.
- `root` on the host, since the install script sets the tree to `777`.
- Two external binaries the app shells out to: `whois` and `dig`.
- Build tooling for the `canvas` native module, which is compiled during `npm ci`.

```bash
apt-get update
apt-get install -y pkg-config libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev
apt-get install -y whois dnsutils
```

If `whois` is missing the process dies the first time a domain is added: the spawn raises an asynchronous `error` event that the surrounding `try/catch` cannot catch. If `dig` is missing, DNS checks fail and every domain registration reports that the host does not resolve.

### Step D2 — Install the dependencies

From the project root:

```bash
npm ci --omit=dev
```

Use `npm ci`, not `npm install`: the lockfile is the only record of the versions this tree was built against.

### Step D3 — Prepare the tree

```bash
./tasks/install.sh
```

That creates `./cache` and `./tmp`, clears the git file-mode flag and recursively sets the tree to `777` with `tasks/` executable. Run it once, from the project root, before the first boot.

Then supply the files the tree does not carry:

- **`conf/config.json`** — the runtime configuration. At minimum it needs `domain` (the public base URL with a trailing slash), `webroot` (`./public`), and `ports.interface` and `ports.websocket`. The reference deployment uses **4848** for HTTP and **4849** for the websocket. It also carries the encryption key, the Stripe keys and the pricing configuration; replace the payment and encryption keys with your own before the instance is reachable from anywhere.
- **`conf/cron.json`** — read unguarded at boot, so a missing file means the app never starts. It is a JSON array of scheduled tasks, each `{"task": …, "interval": …, "lastrun": …}`. An empty array, `[]`, is valid and schedules nothing.
- **`db/GeoLite2-City.mmdb`** and **`db/GeoLite2-ASN.mmdb`** — both are opened unconditionally at boot and the process exits if either is absent. If the tree you were given does not include them, download them from MaxMind under their licence and place them at exactly those paths.

### Step D4 — Create the database

Import the schema dump from the project root:

```bash
mysql -u root -p -e "CREATE DATABASE ipblade CHARACTER SET utf8mb4;"
mysql -u root -p ipblade < ipblade.sql
```

Create the account the app will use with `mysql_native_password`:

```sql
CREATE USER 'ipblade'@'127.0.0.1' IDENTIFIED WITH mysql_native_password BY 'choose-a-password';
GRANT ALL PRIVILEGES ON ipblade.* TO 'ipblade'@'127.0.0.1';
FLUSH PRIVILEGES;
```

The authentication plugin is not optional. `lib/dba.js:171` loads the `mysql` driver, whose v2 line cannot negotiate `caching_sha2_password`, so a MySQL 8 account created with the default plugin fails to authenticate.

The connection parameters are inline in `server.js`, in the `process.db` call near the top of the file: host, port, user, password and database. Edit them to match your server. The reference deployment reaches MySQL on `127.0.0.1:3050`; yours will normally be `3306`.

### Step D5 — Provision the telemetry tables

Telemetry lives in monthly tables named `gr_telemetry_<MM>_<YYYY>`, and nothing in the application creates them. Every read and write builds that name from the current date, so a missing table takes `/dashboard` down with `ER_NO_SUCH_TABLE` and the page never renders.

The dump ships several, for example `gr_telemetry_06_2025`. Clone one for the current month and create the next before the month turns:

```sql
CREATE TABLE gr_telemetry_12_2025 LIKE gr_telemetry_06_2025;
```

### Step D6 — Boot it

```bash
node server.js
```

A healthy boot logs the configured domain and a listening port of 4848. In production, run it under pm2 so it survives a disconnect and a reboot:

```bash
pm2 start server.js --name ipblade
pm2 startup systemd
pm2 save
systemctl enable pm2-root
```

`pm2 save` freezes the process list to `/root/.pm2/dump.pm2`; the `pm2-root` unit resurrects it on boot. Note that the process reads the HTML templates in `res/` into memory at boot, so a template edit needs `pm2 restart ipblade` to take effect.

Leave `devmode` at the top of `server.js` set to `true`. With it set to `false`, the CSS minifier throws an uncaught `TypeError` inside `clean-css` on ordinary stylesheets and takes the process down; the reverse proxy surfaces that as a burst of 502 followed by 503.

### Step D7 — Put Apache in front

Run TLS and the websocket through Apache rather than exposing the Node process. Enable the modules:

```bash
a2enmod proxy proxy_http proxy_wstunnel headers rewrite ssl
```

A vhost that proxies the app and splits the websocket onto its own port:

```apache
<VirtualHost *:443>
    ServerName analytics.example.com

    ProxyPreserveHost On
    RequestHeader set X-Forwarded-For "%{REMOTE_ADDR}s"

    ProxyPass        /!/ ws://127.0.0.1:4849/
    ProxyPassReverse /!/ ws://127.0.0.1:4849/

    ProxyPass        / http://127.0.0.1:4848/
    ProxyPassReverse / http://127.0.0.1:4848/
</VirtualHost>
```

Three details carry the deployment:

- **`ProxyPreserveHost On`** keeps the public hostname visible to the application, which uses it when it builds redirects and absolute links.
- **`X-Forwarded-For`** must be set from the client address. Without it, `req.ip` collapses to the proxy for every visitor, and every record, rate-limit bucket and GeoIP lookup describes the reverse proxy instead of the visitor.
- **`/!/` goes to the websocket port, never to 4848.** The WebSocket server listens on `config.ports.websocket` — 4849 — and the HTTP port cannot upgrade the connection. The `ws://` rule has to come before the general `/` rule, or `/` swallows it first.

### Step D8 — Smoke test

The application refuses bare HTTP clients: a request without `user-agent`, `accept` and `accept-encoding` gets an empty `400`. Probe it the way a browser would.

```bash
curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36" \
  -H "Accept: text/html" \
  -H "Accept-Encoding: identity" \
  http://127.0.0.1:4848/
```

Expect `200` and the marketing page. Then load the dashboard, add a domain and confirm the detail panel renders.

### Deployment checklist

1. Source tree obtained from the operator, no invented remote.
2. Node 22, MySQL 8, `whois`, `dig` and the `canvas` build dependencies installed.
3. `npm ci --omit=dev` completed and `./tasks/install.sh` run once from the project root.
4. `conf/config.json`, `conf/cron.json`, `db/GeoLite2-City.mmdb` and `db/GeoLite2-ASN.mmdb` all present.
5. Database imported, account created with `mysql_native_password`, connection parameters in `server.js` updated.
6. A `gr_telemetry_MM_YYYY` table exists for the current month, and for the next one before it starts.
7. `pm2` running the process as `ipblade`, saved, resurrected by `pm2-root`.
8. Apache proxying `/` to 4848 and `/!/` to 4849, with `ProxyPreserveHost` and `X-Forwarded-For`.
9. A probe with browser headers returns 200.

## Installing the loader in your own app

This is the part that makes a site produce data. It is one tag in the documents the site serves.

### The tag

```html
<script type="text/javascript">
    (function (t, r, a, c, k) {
        c = a.createElement(r);
        c.src = t;
        c.async = 1;
        k = a.getElementsByTagName(r)[0];
        k.parentNode.insertBefore(c, k);
    })('https://ipblade.net/$?r='+~~Date.now(), 'script', document);
</script>
```

For an instance you host yourself, replace `https://ipblade.net` with its public base URL. Everything else stays exactly as written: do not bundle it, defer it, minify it or rewrite the expression. `$?r=` is a per-load cache-buster.

### Where it goes

Immediately before the closing `</body>` tag of the final HTML the client receives, once per served document or layout.

- Shared layouts — `layout.html`, `base.html`, `default.html`, `_document.tsx`, `app/layout.tsx`, `application.html.erb`, `main.php` — are usually the single best insertion point when many pages extend them.
- For a client-side rendered application, put it in the HTML shell the server sends first: `public/index.html`, `index.html`, `pages/_document.tsx`, `app/layout.tsx`. A tag injected after hydration is not in the first response and records nothing.
- For a generated site, insert into the generator or the shared template, never into the built output.
- Leave mail templates, SDK and widget bundles, code samples and anything under `node_modules/` alone. The playbook below carries the full exclusion list.

### How the site is identified

The tag carries no site identifier. The server resolves the site from the **`Referer`** header of the tracking request and matches it against the hosts you registered, so the host that serves the page is the host that must be registered. `example.com` and `www.example.com` are two different records: if one redirects to the other, register the target; if both are served, register both. A host that is served but not registered records nothing, silently.

### When there is no `Referer`

A page served with `Referrer-Policy: no-referrer`, a sandboxed iframe or a client that strips the header gives the server nothing to match on. For those, append the hostname to the loader as base64 in the `d` parameter, the form `res/tracker/inject.js:3` uses:

```html
<script type="text/javascript">
    (function (t, r, a, c, k) {
        c = a.createElement(r);
        c.src = t + '&d=' + btoa(a.location.hostname);
        c.async = 1;
        k = a.getElementsByTagName(r)[0];
        k.parentNode.insertBefore(c, k);
    })('https://ipblade.net/$?r='+~~Date.now(), 'script', document);
</script>
```

`btoa('example.com')` gives `ZXhhbXBsZS5jb20=`, so the request resolves to `https://ipblade.net/$?r=…&d=ZXhhbXBsZS5jb20=`. The server decodes the parameter and uses it in place of the `Referer`. Use this form only where the plain tag cannot work; the `Referer` route stays correct when the site is served on more than one host.

### Confirm before you test

Request a public page yourself and confirm the loader survived to the response body:

```bash
curl -sS https://example.com/ | grep -c -F 'ipblade.net/$?r='
```

A non-zero count is what you want. If the site sends `Content-Security-Policy`, `script-src` must allow the tracker origin, `https://ipblade.net` for the hosted service, or the browser blocks the load and the verification below fails on the CSP check.

## Registering, verifying and reading the numbers

Base URL: `https://ipblade.net`

## Rules that apply to every request

Send these headers or the server closes the connection with an empty `400` before your key is even read. The three browser headers apply to every request to this host, including the one that fetched this file; `X-Token` applies to every API endpoint except account creation, which carries the enrollment code instead, and `Content-Type` to the POST calls:

```
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36
Accept: application/json
Accept-Encoding: identity
X-Token: <64 character api key>
Content-Type: application/json          # POST only
```

- A `User-Agent` containing `HeadlessChrome` is refused. Use the string above.
- **Rate limit: 10 requests per 60 seconds per IP.** Exceeding it returns HTTP 429 with `{"result":false,"code":1,"msg":"rate limit exceeded"}` — note `msg`, not `message`. Verify calls count against the same bucket, so do not poll in a tight loop.
- Keys are 64 lowercase hex characters and are scoped to that account's sites. One comes back from account creation in Step 0.5; the account owner can issue more in the dashboard under Settings → API Access.

## Response envelope

Every endpoint answers with the same shape. Check `result`, then read `code` when it is `false`:

```json
{"result": true, "code": 0, "message": "ok"}
```

Success payloads add their own fields. Failures use HTTP 403, 404, 429 or 503, with one exception: a verification that reached the page but failed returns HTTP 200 with `result: false` and `code: 17`, because the request itself succeeded.

---

## Step 0 — Establish the public URL

You cannot register a site before you know where it is actually served. Resolve this from the repository first, and only ask the user when the repository does not answer it.

Look in this order, and stop at the first source that gives a production hostname:

1. **Project metadata** — `package.json` (`homepage`, `repository`), `Cargo.toml` (`homepage`), `pyproject.toml`, `composer.json`, `*.gemspec`, `README`.
2. **Canonical and social tags in served documents** — `<link rel="canonical" href="…">`, `og:url`, `twitter:domain`.
3. **Machine-readable site files** — `robots.txt` (`Sitemap:` line), `sitemap.xml` (`<loc>` entries), `CNAME` for GitHub Pages.
4. **Framework and hosting config** — `next.config.js` (`assetPrefix`, `env.NEXT_PUBLIC_SITE_URL`), `vercel.json`, `netlify.toml`, `fly.toml`, `app.yaml`, `Dockerfile`/`docker-compose.yml` labels, `Caddyfile`, `nginx.conf` (`server_name`), `Procfile`.
5. **Environment templates** — `.env.example`, `.env.sample`, `config/*.example.*` keys named `SITE_URL`, `BASE_URL`, `PUBLIC_URL`, `APP_URL`, `CANONICAL_HOST`.
6. **Deploy workflow files** — `.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile` deploy targets, and any `aws`/`gcloud`/`heroku` step naming a bucket, distribution or app.

Rules for this step:

- **Never invent or guess a domain.** A wrong guess often passes the registry and DNS checks and silently produces a site record that tracks nothing.
- If the only candidates are local development hosts (`localhost`, `127.0.0.1`, `*.local`, `0.0.0.0`) or a placeholder such as `example.com`, treat the URL as unknown.
- If two candidates disagree, prefer the one used by the canonical link or the deploy config over a README badge.
- **When you cannot establish it with confidence, ask the user for the production URL** before doing anything else. State what you looked at and what you found; that is faster than registering the wrong host and cleaning it up.
- Record the exact host you settled on, for example `www.example.com` or `example.com`. The next step needs the precise host, not a prettified version.

## Step 0.5 — Create the account

Every call from Step 1 onward needs a key, and there is no self-service signup. Ask the operator who gave you this task for an **enrollment code**: it is a secret set on the instance, and while it is unset the endpoint refuses every request, correct code or not.

```bash
curl -sS -X POST https://ipblade.net/api/v1/accounts \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: identity" \
  -H "Content-Type: application/json" \
  -d '{"mail":"you@example.com","password":"at-least-8-characters","code":"<enrollment code>"}'
```

```json
{"result": true, "code": 0, "message": "ok", "token": "64d22467e72d2aa2899eb30f768070c2776d12ff8fde7e15d8edb7198fb96296", "uid": 10}
```

The `token` is the `X-Token` value for every later call in this playbook. It appears in this response only, so store it.

- `mail` must be a valid address that is not already registered.
- `password` is 8 to 128 characters. It is the account's password, not the key's, and it is the way into the dashboard later.
- `code` is compared in constant time against the instance's secret. Do not guess values or retry with variations.
- A new account is on the free plan, which holds one site. Ask the operator if you need more rather than creating a second account.

| code | HTTP | meaning |
| --- | --- | --- |
| 0 | 200 | account created, `token` and `uid` returned |
| 1 | 429 | rate limit exceeded |
| 3 | 403 | enrollment code missing, wrong, or enrollment disabled on the instance |
| 6 | 403 | mail or password is invalid |
| 10 | 403 | user lookup failed |
| 11 | 403 | email already registered |
| 13 | 403 | account or key could not be saved |

## Step 1 — Register the site

```bash
curl -sS -X POST https://ipblade.net/api/v1/sites \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: identity" \
  -H "Content-Type: application/json" \
  -H "X-Token: $IPBLADE_TOKEN" \
  -d '{"domain":"example.com","name":"Example"}'
```

```json
{"result": true, "code": 0, "message": "ok", "sid": "Ab3Xy9Q", "domain": "example.com"}
```

`domain` is the host from step 0, without a scheme or path. `name` is optional and defaults to the domain. The server runs whois against the registrable root and a DNS lookup against the host itself, so the host must be registered and must resolve publicly. Keep the returned `sid`; every later step is keyed by it.

**Register the exact host that serves the pages.** IPBlade identifies the site from the `Referer` host and matches it against registered hosts, so `example.com` and `www.example.com` are two different records:

- If the site redirects `www` to the apex, register the apex.
- If it redirects the apex to `www`, register `www.example.com`.
- If it serves pages on both hosts without redirecting, register both. A host that is served but not registered records nothing, silently.
- Every registered host is a separate site record and counts against the account's plan limit, so on a free plan only one host fits. Code `16` below is what a second registration returns.
- A staging or preview host is a separate record too; register it only if it should collect data.

Codes for this call, all HTTP 403:

| code | meaning |
| --- | --- |
| 1 | `X-Token` missing or not 64 characters |
| 2 | `X-Token` unknown, or the key has no owner |
| 3 | Path does not resolve to an endpoint |
| 6 | Site name is neither a human name nor a valid domain |
| 7 | Domain is not a valid domain name |
| 8 | Social network or site-builder host, not supported |
| 9 | Unable to add the site, unspecified |
| 10 | Domain lookup failed |
| 11 | Domain is already registered on IPBlade |
| 12 | Saving the record failed |
| 13 | Unknown internal error |
| 14 | Domain is not in the registry, check the spelling |
| 15 | Domain does not resolve to a public address |
| 16 | Account reached its plan's site limit |

## Step 2 — Find every publicly served page and install the snippet

```bash
curl -sS https://ipblade.net/api/v1/sites \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: identity" \
  -H "X-Token: $IPBLADE_TOKEN"
```

```json
{"result": true, "code": 0, "sites": [
  {"sid": "Ab3Xy9Q", "domain": "example.com", "name": "Example", "verified": false,
   "snippet": "<script type=\"text/javascript\">\n    (function (t, r, a, c, k) {\n        c = a.createElement(r);\n        c.src = t;\n        c.async = 1;\n        k = a.getElementsByTagName(r)[0];\n        k.parentNode.insertBefore(c, k);\n    })('https://ipblade.net/$?r='+~~Date.now(), 'script', document);\n</script>"}
]}
```

The snippet is identical for every site — the host is resolved server-side from the `Referer`, so there is nothing per-site to substitute. Do not rewrite, bundle, defer or minify it; `$?r=` is a per-load cache-buster.

### Which files count

**Default: every page the site serves publicly.** Assume all of them, then apply the exclusions below. A page that renders without the snippet is a page that records nothing.

Find the documents that are served, including templates that produce them:

- Plain documents: `**/*.html`, `**/*.htm`, `**/*.php`, `**/*.aspx`, `**/*.ejs`, `**/*.hbs`, `**/*.pug`, `**/*.twig`, `**/*.njk`, `**/*.liquid`, `**/*.erb`, `**/*.vue`, `**/*.svelte`, `**/*.astro`.
- Template engine directories: `templates/`, `views/`, `app/views/`, `resources/views/`, `layouts/`, `partials/`, `includes/`, `theme/`, `themes/<name>/`, `_layouts/`, `_includes/`.
- Shared layouts that close the document, which are usually the single best insertion point: `layout.html`, `base.html`, `default.html`, `main.php`, `footer.php`, `_document.tsx`, `app/layout.tsx`, `src/app/layout.tsx`, `pages/_document.js`.
- Client-side rendered applications: the HTML shell, not the components. `public/index.html`, `src/index.html`, `index.html` at the project root, `app/layout.tsx` for Next.js App Router, `pages/_document.tsx` for Next.js Pages Router, `nuxt.config` `app.head`, `svelte.config` templates. The tag must be present in the first response, not injected after hydration.
- Static site generators: `hugo` `layouts/_default/baseof.html`, `eleventy` `_includes/base.njk`, `jekyll` `_layouts/default.html`, `gatsby` `src/html.js`, `mkdocs`/`docusaurus` custom theme footer.
- Server frameworks: `Flask`/`Django` `base.html`, `Rails` `app/views/layouts/application.html.erb`, `Laravel` `resources/views/layouts/app.blade.php`, `Express` view layouts, `Phoenix` `root.html.leex`.

If several pages extend one layout, install once in that layout and check that each page still renders it. If pages are generated from data, insert into the generator, not the output.

### Where the tag goes

Immediately before the closing `</body>` tag, in the final HTML the client receives. One insertion per served document or layout. Do not put it in `<head>`, and do not rely on a component that renders conditionally.

### Do not install into

- **Mail templates** — `emails/`, `mailers/`, `mail/`, `views/emails/`, `templates/email/`, `*.mjml`, `*_mail.*`, `*mailer*`, `*notification*template*`. Mail clients drop scripts and the requests would pollute the data if they did not.
- **SDK, widget and platform bundles** — files a platform serves to other people's pages, embed scripts, iframe runtimes, `public/*.min.js` libraries, `dist/` build artefacts of a library, anything under `node_modules/`.
- **Code samples, documentation snippets and fixtures** — `examples/`, `demo/`, `samples/`, `docs/`, `*.md`, test fixtures and snapshot files, IDE snippets.
- Generated or vendored output that is rebuilt from source: change the source template instead, or your edit disappears on the next build.

If a file is ambiguous — a template used for both web pages and e-mail — check what renders it before inserting.

### Confirm before you call verify

Request the public page yourself and confirm `ipblade.net/$?r=` appears in the response body:

```bash
curl -sS https://example.com/ | grep -c -F 'ipblade.net/$?r='
```

A non-zero result is what you want. If the site sends `Content-Security-Policy`, `script-src` must allow `https://ipblade.net`, or the browser blocks the load and verification fails on the CSP check.

## Step 3 — Verify

```bash
curl -sS -X POST https://ipblade.net/api/v1/sites/Ab3Xy9Q/verify \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: identity" \
  -H "Content-Type: application/json" \
  -H "X-Token: $IPBLADE_TOKEN" \
  -d '{}'
```

```json
{"result": true, "code": 0, "message": "ok",
 "site": {"sid": "Ab3Xy9Q", "domain": "example.com"},
 "verification": {"attempts": 1, "status": 200, "csp": true, "code": true, "netscape": false, "method": "http"}}
```

**Verification passes only once the live page serves the snippet.** The server fetches the site, takes the plain HTTP status and CSP header, then reads the HTML — from a headless renderer when one is configured, otherwise from that same plain fetch — and looks for the tracker marker. All three must hold: `status` is 200, `csp` is true, `code` is true. A snippet sitting in a local checkout, an unmerged branch, or a file the site does not serve changes nothing.

Repeat this call once per `sid`, which is one call per registered host. A pass stamps the site as verified; a genuine miss clears the flag and stores the failure detail.

| code | HTTP | meaning |
| --- | --- | --- |
| 0 | 200 | verified, `verification.code` is true |
| 4 | 404 | `sid` not found on this account |
| 6 | 403 | `sid` parameter is empty or malformed |
| 17 | 200 | the page was read and the marker was absent, or CSP blocks it; `verification` says which |
| 18 | 503 | no body could be read at all, by renderer or by plain fetch; the site's stored state was left untouched, retry later |

`verification.method` says what produced the HTML:

- `http` — a plain fetch read the page. This is the normal case for server-rendered documents, and it covers everything Step 2 tells you to install into.
- `render` — a headless renderer read the page after it ran.
- `none` — neither produced a body, which is the only way to get `code: 18`.

`verification.netscape` reports only whether the renderer ran. `code: false` with `method: http` is a real miss: the markup is not in the HTML that was served. A snippet injected after hydration, or into a shell whose first response carries no tag, can only be seen with `method: render`, so install into the first response instead of after it.

If a deploy takes time, retry a few times with a delay, respecting the 10 requests per minute.

## Step 4 — Read today's numbers

```bash
curl -sS https://ipblade.net/api/v1/sites/Ab3Xy9Q/stats \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: identity" \
  -H "X-Token: $IPBLADE_TOKEN"
```

```json
{"result": true, "code": 0,
 "site": {"sid": "Ab3Xy9Q", "domain": "example.com"},
 "day": "2026-11-20",
 "stats": {"hits": 1, "visitors": 1, "pageviews": 1, "bounce": 100, "ping": 313}}
```

- `hits` counts recorded page loads today, `visitors` distinct visitors, `pageviews` the same total the dashboard labels pageviews.
- `bounce` is a percentage, one decimal.
- `ping` is the average round trip to the server in milliseconds, rounded.

A registered site that has never been visited returns the same shape with zeros, which is a valid answer and not an error. The current month's telemetry table is provisioned on demand; if none exists to copy from, the answer is 503 with `code: 19`.

| code | HTTP | meaning |
| --- | --- | --- |
| 0 | 200 | numbers for `day` |
| 4 | 404 | `sid` not found on this account |
| 6 | 403 | `sid` parameter is empty or malformed |
| 19 | 503 | no telemetry table available to provision from |

---

## Checklist

1. Public URL established from the repository, or asked from the user. Exact host recorded.
2. Every host that serves pages registered, one `sid` each.
3. Every publicly served document or layout has the snippet before `</body>`; mail templates, SDK bundles, samples and docs untouched.
4. The served page contains `ipblade.net/$?r=` and CSP allows it.
5. `verify` returns `result: true` for each host.
6. `stats` returns the day's numbers, zeros included.

Requests for this file need the same three browser headers as the API; a bare client gets HTTP 400.
