Architecture and overview
ArchitectureHow the connector, the ingest API, and the dashboard fit together, and what leaves your servers.
MCAnalytics records which hostname a player first joined your network through, whether they came back, what they did, and what they spent, then reports all of it by acquisition source.
It is two parts: a connector plugin you install on servers you control, and a hosted dashboard we run. The connector reads the virtual host from the Minecraft handshake, tracks the session, and posts the result to the ingest API over HTTPS.
#What MCAnalytics does
- Attributes every new player to the hostname they first joined through.
- Measures whether a player came back inside a 7 day window.
- Matches Tebex purchases back to the source that brought the buyer.
- Reports confirmed cheat bans per source.
- Stores server heartbeats: online count, TPS, MSPT, and memory use.
#Network topology
On a network with a proxy, the Velocity connector sits at the edge and owns session tracking, because that is the only place the connect hostname exists. Backend Paper servers run the same connector in backend mode and send heartbeats and confirmed bans.
On a single server with no proxy, the Paper connector runs in standalone mode and does both jobs.
[ Player client ]
| handshake carries the virtual host, e.g. tiktok.myserver.net
v
[ Velocity proxy ] --> [ MCAnalytics Velocity connector ] sessions, hostnames, heartbeats
| | HTTPS, Bearer mca_live_...
| v
| [ MCAnalytics ingest API ]
v
[ Paper backend ] -----> [ MCAnalytics Paper connector ] heartbeats, confirmed bans, login hooks#Offline spool
If the ingest API is unreachable, the connector writes pending events to a local SQLite spool file next to the plugin and drains it when we answer again. Your server keeps running either way.
The spool has a size limit you set. When it is full the oldest events are pruned, so a long outage costs you old events rather than disk space.
| Setting | Default | What it does |
|---|---|---|
| spool-file | spool.db | SQLite file the connector spools to |
| spool-size-limit-mb | 50 | Size cap before the oldest events are pruned |
| spool-queue-capacity | 5000 | Events waiting in memory to be written |
| batch-size | 50 | Events per request when the spool drains |
| max-retries | 10 | Attempts before an event is dead lettered |
#What we do not collect
We do not receive chat messages, inventories, coordinates, or anything else from gameplay.
Player IP addresses are off by default. The Paper connector key is track-ip-address and it ships set to false. When a session does carry an IP address, the API replaces it with a keyed HMAC-SHA256 hash under a key that belongs to your network alone, and the raw address is never written.