Built-in & Custom Events

The connector collects built-in events automatically. Custom events let you track gameplay or business logic the defaults do not cover, such as quests, economy actions, or minigame lifecycle.

Event design guidelines

• Use stable, low-cardinality names, for example minigame.match_end.
• Keep high-cardinality values such as player UUIDs in the payload, not in the event name.
• Use snake_case keys and flat values.
• Renaming an event splits its history, so treat names as part of your schema.

Payload contract

Custom event payloads support:

• Flat scalars: string, number, boolean, null.
• Flat arrays of scalars.

Nested objects and arrays of objects are not supported. If you need structure, flatten it into prefixed keys such as reward_item_id and reward_amount.

Sending an event

Use the Developer API from your own plugin. The client is available after the ShardAnalytics plugin is enabled, and custom events are automatically namespaced with custom:.

import com.shardanalytics.api.client.AnalyticsClient;
import com.shardanalytics.api.client.AnalyticsProvider;
import com.shardanalytics.api.events.EventBuilder;

public void onQuestComplete(Player player, Quest quest, long completionTimeMs) {
    AnalyticsClient client = AnalyticsProvider.get();
    if (client == null || !client.isReady()) {
        return;
    }

    client.track(EventBuilder.custom("quest.complete")
        .player(player.getUniqueId())
        .location(player.getWorld().getName(),
                  player.getLocation().getBlockX(),
                  player.getLocation().getBlockY(),
                  player.getLocation().getBlockZ())
        .data("quest_id", quest.getId())
        .data("quest_name", quest.getName())
        .data("completion_time_ms", completionTimeMs)
        .build());
}

Caution

playerId must be a UUID. Do not pass null or a string UUID; skip the call when there is no player, as in the example above.

For a raw map-based call, use trackCustom:

client.trackCustom("arena.end", player.getUniqueId(), Map.of(
    "arena_id", arena.getId(),
    "arena_name", arena.getName(),
    "winning_team", event.getWinningTeam().getName()
));

Where custom events appear

Once collected, custom events are available to:

• Dashboards as event-based widgets and tables.
• Funnels as steps, so you can measure conversion between two custom events.
• Custom dashboards for ad-hoc analysis.

Schema and catalog

ShardAnalytics indexes the payloads it receives and infers field types for querying. Because the queryable catalog is curated before fields are exposed to dashboards, a new custom event may not appear in every picker immediately after its first payload arrives.

Privacy

Do not send secrets, passwords, private messages, or full chat content in event properties. Prefer pseudonymous identifiers and keep payloads to the minimum needed for analysis.