# Install statistics

ScreenTinker can optionally report how many screens an install runs. It is **off until you turn it
on**, and this page documents the whole of it.

---

## What is sent

Three fields. This is the complete payload:

```json
{
  "instance_id": "9f2c1b6e-4a17-4c8e-9d3b-27a5e0f81c44",
  "version": "1.9.34",
  "screen_count": 42
}
```

| Field | What it is |
|---|---|
| `instance_id` | A random UUID generated by your server on first use and kept in its own database. It carries no information about you — its only job is to let two reports from the same server be recognised as the same server, so a count is a count rather than a sum of duplicates. |
| `version` | The ScreenTinker version this server is running. |
| `screen_count` | How many displays have been paired with this server. |

## What is not sent

No hostnames, IP addresses or domains. No organization, workspace or user names. No email
addresses and no user count. No device names, locations or serial numbers. No content, filenames,
playlists or schedules. No logs and no configuration.

The request is sent over HTTPS, and the receiving service does not record the source address.

## Verifying that

Rather than take the above on trust:

- **In the product** — Settings → Install statistics shows the exact payload your server would
  send, generated live from your own data, plus what it last actually sent and when.
- **In the source** — the payload is built in one function, `payload()` in
  [`server/lib/telemetry.js`](../server/lib/telemetry.js). Every field that leaves your server
  is in that object literal. `server/test/telemetry.test.js` fails if a field is added.
- **On the wire** — the destination is a single `POST`, overridable with `TELEMETRY_ENDPOINT`, so
  you can point it at your own collector and read exactly what arrives.

## Turning it on or off

You are asked once, on the dashboard, if you are a platform administrator. Both answers are
remembered, so declining is permanent and you will not be asked again after an update.

To change your mind at any time: **Settings → Install statistics**.

Reports are sent at most once a day. Nothing is queued or retried — if your server is offline or
the request fails, that day is simply skipped.

## Why we ask

ScreenTinker is self-hostable, so most installs are invisible to us by design, and that is how it
should stay. The cost is that we genuinely cannot answer "how many screens run this?" — a question
that matters for arguing the project is worth continuing to build, and for deciding which players
deserve the next round of work.

Sharing is a small, specific way to help with that. Declining is a completely reasonable answer and
changes nothing about how the product works.

> **A note on honesty.** Because sharing is opt-in, any total we publish is a **floor** — "at least
> N screens" — never an estimate of the whole install base. Instances that opt in are not a random
> sample of those that don't, so the number is not something to extrapolate from, and we won't.

## Running your own collector

Set `TELEMETRY_COLLECTOR=1` and this server accepts reports at `POST /api/telemetry/report`,
storing them in a `telemetry_reports` table keyed by `instance_id`. The endpoint is inert unless
that variable is set, so a normal install never exposes it.

Reports are upserted rather than appended — one row per install holding its latest report, not a
growing event log.