Docs/Analytics/Event Tracking

Event Tracking

Send custom events from your plugins to StaffHQ and view them in the dashboard.

Event tracking lets you record things that happen on your server that StaffHQ does not capture automatically. Every event has a name, an optional set of properties, and is tied to a player UUID. Events appear in the Events page in your dashboard.

When to use it

Use event tracking any time something meaningful happens that you want to measure or analyze later. Three concrete examples from a typical Minecraft server:

tutorial_completedPlayer finishes the new-player tutorial. Track this to measure tutorial completion rate and correlate it with long-term retention.

kit_purchasedPlayer buys a kit from the store. Add a property like {"kit": "starter"} to break down revenue by product.

faction_joinedPlayer joins a faction. Useful for understanding social graph formation and how it affects engagement.

Java plugin integration (recommended)

If your server runs the StaffHQ plugin, you can call the SDK directly from your own plugin code. This is the simplest path. No HTTP client, no auth header management.

Add the compile dependency

groovy

// build.gradle
dependencies {
    compileOnly files("libs/staffhq-plugin-bukkit.jar")
}

Declare the soft dependency

yaml

# plugin.yml
depend: [StaffHQ]

ℹ

Note

Use depend rather than softdepend if your plugin requires StaffHQ to be present. If StaffHQ is optional, use softdepend and guard the call with a null check on the API instance.

Track an event

java

import net.staffhq.bukkit.StaffHQBukkit;

// Inside any Bukkit event listener or command handler:
StaffHQBukkit.trackEvent(
    player,
    "kit_purchased",
    Map.of("kit", "starter", "price_credits", 500)
);

The call is non-blocking. StaffHQ batches the event with the next sync cycle and sends it to the dashboard.

HTTP webhook

If you cannot take a compile dependency on the StaffHQ jar, or if you are sending events from outside the Minecraft server entirely, use the REST endpoint directly.

Request

http

POST https://dash.staffhq.net/api/v1/plugin/events
Authorization: Bearer YOUR_PLUGIN_API_KEY
Content-Type: application/json

{
  "player_uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "name": "kit_purchased",
  "properties": {
    "kit": "starter",
    "price_credits": 500
  },
  "occurred_at": "2026-05-11T14:32:00Z"
}

curl example

bash

curl -sS -X POST https://dash.staffhq.net/api/v1/plugin/events \
  -H "Authorization: Bearer YOUR_PLUGIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "player_uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "kit_purchased",
    "properties": {"kit": "starter"},
    "occurred_at": "2026-05-11T14:32:00Z"
  }'

occurred_at is optional. If omitted, the server uses the time the request was received.

Event name rules

Event names must match the pattern ^[a-z0-9_]{1,64}$. Use lowercase letters, digits, and underscores only. Maximum 64 characters.

⚠

Warning

The following name prefixes are reserved for internal StaffHQ events and cannot be used for custom events: session_, punish_, chat_, rank_, block_. Events sent with reserved prefixes will be rejected with a 422 response.

Properties

Properties are an optional JSON object. Any depth is accepted and the object is stored as-is. There is no fixed schema. Send whatever context is useful for your analysis. Property values can be strings, numbers, booleans, or nested objects.

Where to find events

Events appear in real time on the Events page in your dashboard. You can filter by event name, player, or time range. Events are also available as the first step in a Funnel.

← PreviousAnalytics Next →Funnels