EzBanners Java Plugin API

This page documents the Java API for integrating your Bukkit/Spigot plugin with EzBanners. Use this API to send plugin and server stats to the EzBanners platform for live banner rendering and analytics.

Overview

The EzBannersApi class provides methods to send plugin and server statistics to EzBanners. It handles authentication, payload formatting, and HTTP requests to the EzBanners backend.

Getting Started

1. Add the EzBanners plugin to your server and ensure it is enabled.
2. Obtain your plugin UUID and API token from the EzBanners dashboard.
3. In your plugin, add EzBanners as a dependency and use the API as shown below.

API Usage

import com.skyblockexp.ezbanners.api.EzBannersApi;

public class MyPlugin extends JavaPlugin {
    @Override
    public void onEnable() {
        EzBannersApi api = new EzBannersApi(this);
        api.startAutoStatsPush(
            "your-plugin-uuid",
            this,
            60 // interval in seconds
        );
    }
}

import com.skyblockexp.ezbanners.api.EzBannersApi;
import org.bukkit.plugin.java.JavaPlugin;

// Get EzBannersApi instance (assuming you have a reference to EzBannersPlugin)
EzBannersApi api = new EzBannersApi(ezBannersPlugin);

// Start automatic stats push (every 60 seconds)
api.startAutoStatsPush(
    "your-plugin-uuid",
    this, // your JavaPlugin instance
    60 // interval in seconds
);

// To stop automatic stats push:
// api.stopAutoStatsPush();

// --- Manual usage examples below ---

// Send basic plugin stats
api.sendPluginStats(
    "your-plugin-uuid",
    this, // your JavaPlugin instance
    serverCount,
    playerCount
);

// Send plugin stats with extra fields and meta overrides
Map extraStats = new HashMap<>();
extraStats.put("auctions", 42);
extraStats.put("sales", 1234);

Map meta = new HashMap<>();
meta.put("custom_label", "MyPlugin");

api.sendPluginStats(
    "your-plugin-uuid",
    this,
    serverCount,
    playerCount,
    extraStats,
    meta
);

Method Reference

• startAutoStatsPush(String pluginUuid, JavaPlugin sourcePlugin, int intervalSeconds)
  Starts an async repeating task to send server and player counts to EzBanners automatically (like bStats).
  Call stopAutoStatsPush() to stop the task.
• sendPluginStats(String pluginUuid, JavaPlugin sourcePlugin, int serverCount, int playerCount)
  Sends basic plugin stats (server and player count) to EzBanners.
• sendPluginStats(String pluginUuid, JavaPlugin sourcePlugin, int serverCount, int playerCount, Map<String, Object> extraStats, Map<String, Object> metaOverrides)
  Sends plugin stats with additional custom fields and meta data.
• stopAutoStatsPush()
  Stops the async stats push task if running.

Payload Structure

{
    "plugin": {
        "name": "YourPlugin",
        "version": "1.0.0"
    },
    "stats": {
        "servers": 5,
        "players": 123,
        // ...any extra stats
    },
    "meta": {
        "server_uuid": "...",
        "server_name": "...",
        // ...any meta overrides
    }
}

Error Handling

The API methods return an ApiClient.ApiResponse object with success, statusCode, and message fields. Check these to handle errors or log results.

Best Practices

• Send stats at a reasonable interval (e.g., every 30–60 seconds).
• Do not share your plugin UUID or API token publicly.
• Use extraStats and metaOverrides to provide additional context for your plugin.
• Check the ApiResponse for errors and log them for troubleshooting.