Plugin installation

Minealyze reads your server through a small collector plugin: async, Folia‑ready, and never blocking. It reads events and pushes them into a bounded queue; it never mutates game state and never touches the main thread for network I/O. If Minealyze is unreachable, your server is never affected: the plugin just buffers and retries.

There are two ways to connect data. The second gets you value the fastest if you already run Plan.

Option A: install the collector plugin

The same button is inside Minealyze too: on the Servers page, and at the "Connect your data" step of the setup flow.

1. Add a server in the Minealyze dashboard (Settings → Servers → Add server). This generates a per‑server API key, shown once, so copy it now.
2. Download minealyze-collector.jar with the button above. That is the exact filename: do not rename it. Before dropping it on your server, compare its SHA-256 checksum with the one shown next to the button (sha256sum minealyze-collector.jar on Linux, Get-FileHash minealyze-collector.jar -Algorithm SHA256 on Windows); both values must match.
3. Drop the .jar into your server's /plugins folder (Paper, Purpur, or Folia; Spigot works but Paper is recommended), directly in /plugins, not in a subfolder.
4. Open plugins/Minealyze/config.yml (created on first start) and set api.key (your mna_… key) and api.server-id (the id shown on your server page). You can also provide the key through the MINEALYZE_API_KEY environment variable (takes precedence over the file).
5. Reload the plugin (/minealyze reload) or restart the server, then verify with:

/minealyze status

6. Watch your server page flip from "Waiting for connection…" to Connected (green dot, "seen a few seconds ago") on the first received batch.

config.yml reference

# plugins/Minealyze/config.yml
api:
  # Per-server API key (scope: ingestion + actions for THIS server only).
  # Can also be provided via the MINEALYZE_API_KEY environment variable
  # (takes precedence) to keep the secret out of plugin-folder backups.
  key: "mna_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  # Minealyze API base URL (HTTPS required in production).
  url: "https://api.minealyze.com"
  # Server id (provided by the Minealyze dashboard).
  server-id: ""

# Batch send interval (seconds), max batch size, bounded queue, gzip.
batch-interval: 30
max-batch-size: 500
queue-capacity: 10000
compression: true

# Collection toggles, one per category.
collectors:
  session: true
  milestones: true       # first_* onboarding milestones (new players)
  blocks: true           # block place/break, AGGREGATED per material (counters)
  chat-metadata: true    # length + mentions ONLY (never the content)
  deaths: true           # death/PvP (cause, killer player)
  advancements: true     # native advancements (recipes filtered)
  economy: true          # sampled Vault balance (soft-depend)
  ranks: true            # sampled LuckPerms rank (soft-depend)
  proximity: true        # co-play edges (sampled, no raw positions)
  votes: true
  heartbeat: true

What each block does

| Block | Purpose | Default | |---|---|---| | api.key | Authenticates ingestion for this server only, never cross‑tenant. Stored hashed on Minealyze's side; never logged. | none (required) | | collectors.* | Per‑category toggles. Everything can be turned off independently; the dashboard degrades gracefully when a category is missing (no invented metrics). | all on | | batch-interval / max-batch-size / queue-capacity | Control the async batch sender: flush frequency, max batch size, and the bounded local queue capacity (controlled drop when full). | 30s / 500 events / 10,000 | | actions.* | The channel used for nudges (never pay-to-win). OFF by default; strict cosmetic command allowlist, frequency caps, local audit log. | enabled: false |

Chat content is never transmitted in plaintext (metadata only: length, mentions) and UUIDs are pseudonymized on Minealyze's side before any storage.

Option B: import from Plan

If you already run Plan (Player Analytics), you can import its history directly instead of starting from zero. Upload your plugins/Plan/database.db in the onboarding flow (or send it to POST /imports/plan): players and sessions are imported, usernames are coded server‑side like any other data, re‑importing never duplicates anything, and live collection then merges with the imported history. Install the collector plugin (option A) right after: it takes over from there.

Verifying the connection

• Connected (green): a heartbeat was received recently. Historical data and Tebex ingestion keep working even if the plugin briefly disconnects.
• Disconnected (orange): no heartbeat past a threshold. Check the API key, that the server is running, and that outbound HTTPS isn't blocked by a firewall.
• Offline: the server itself is down (not just the plugin); Who's slipping away freezes at its last known value rather than showing a false "all good".

Security note on the API key

The server operator can always read config.yml: we don't try to hide the key from you, that's not a realistic threat model. What we do instead: the key is scoped to one server, stored hashed on Minealyze's side, never logged, and rejected over plain HTTP (TLS only). If the key ever leaks, contact support to revoke it and issue a new one. Prefer the MINEALYZE_API_KEY environment variable when your host supports it, so the key doesn't end up in shared config backups.

Next step

Continue to Your first week for the full account → server → data → Tebex path, or jump to The words Minealyze uses to understand what Who's slipping away and the morning recap actually show you.