Developer API

Send custom events, player properties and purchases from your own Bukkit plugin through the Analyse client.

Updated September 15, 20261 min read

On Paper, Folia and Spigot, the plugin registers its client with Bukkit's services manager. Your plugin can use it to send events without shipping its own key or HTTP code.

Get the client

Add Analyse as a soft dependency in your plugin.yml, then load the service. The classes live in net.analyse.sdk (AnalyseClient, Player, Event, Purchase).

Java
AnalyseClient analyse = getServer().getServicesManager().load(AnalyseClient.class);
if (analyse == null) {
    getLogger().info("Analyse is not installed or has no key; skipping analytics");
}

The Velocity and BungeeCord plugins do not register a service.

Custom events

Java
analyse.track(
    Event.named("quest_completed")
        .player(Player.of(player.getUniqueId()))
        .prop("quest", "dragon_slayer")
        .prop("duration_s", 312)
);

Player.of(UUID) works out Java or Bedrock from the UUID. Property values can be text, numbers or booleans. Event names starting with $ are reserved.

Player properties

Java
analyse.identify(Player.of(player.getUniqueId()))
    .set("rank", "vip")
    .setOnce("first_kit", "starter")
    .add("quests_completed", 1)
    .apply();
  • set overwrites the value.
  • setOnce only sets it if it has no value yet.
  • add increments a number.
  • unset removes a property.

Properties are stored on the player in Analyse. The same calls exist as /analyse set for use from the console.

Purchases

For purchases that do not come through a store integration:

Java
analyse.purchase(
    Player.of(player.getUniqueId()),
    9.99,
    "USD",
    Purchase.of("txn_123").item("vip", "VIP Rank")
);

Use your own transaction id in Purchase.of so a retry is not counted twice.

Delivery

  • Events are queued in memory and sent in batches, off the main thread.
  • Every event carries a unique id and the gateway removes duplicates, so retries are safe.
  • If the network is down, the client retries with backoff.

Built-in event names

These names are reserved and sent by the plugin itself: $join, $leave, $identify, $purchase, $credit_spend, $credit_earn, $level_up, $creator_code, $experiment_assign, $server_startup, $server_heartbeat, $server_shutdown.