Architecture and overview

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, and on Day 1, Day 7, and Day 30 after their first join.
• Matches Tebex purchases back to the source that brought the buyer.
• Reports confirmed cheat bans, each tied to the player and the address they first joined through.
• Stores server heartbeats: online count, TPS, MSPT, and memory use.
• Records what happens inside a session: commands by label, deaths, kills, advancements, world and server moves, and kicks.

#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, in game events, 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, in game events, 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 fixed size cap. When it is full the oldest events are pruned, heartbeats before sessions and bans, so a long outage costs you old events rather than disk space.

These values are fixed in the connector and there is nothing to tune. Old config keys for them, such as spool-size-limit-mb, are ignored with one line in the console.

#What we do not collect

We never receive inventories or block coordinates. With heatmaps on, the finest position we receive is a chunk, counted per minute, and the only chunk tied to a player is the one they left a server in. A teleport is named by its world only.

If the owner turns on the world map, servers also send rendered pictures of the terrain around spawn and the busy areas, which can show builds. They show no player, are seen only by signed in members of the network, and can be deleted in Settings at any time.

What a player types stays on your server unless you switch it on. By default a chat message leaves as its length alone, a character count and a short, medium or long bucket, and a command as its label, such as spawn or tpa. Settings, Data and privacy can turn on the text itself, capped at 256 characters, and the arguments of login and private message commands are never sent either way.

The Velocity connector sends each player's IP address with the session, because the proxy is the only place the real address exists. On a Paper server that records its own sessions it is off by default: the key is track-ip-address and it ships set to false. When a session does carry an IP address, the API reads the country from it, then replaces it with a keyed HMAC-SHA256 hash under a key that belongs to your network alone, and the raw address is never written. A session that waits in the offline spool is written to disk without it.