Plugin Data Push

This guide explains how a plugin can push live stats and metadata to the EzBanners service. The repository includes a Java helper (`EzBannersApi`) you can use inside your Bukkit/Spigot plugin to send payloads easily.

Overview

Endpoint:

POST https://ezbanners.org/api/plugins/{plugin_uuid}/data

Plugins authenticate using the per-plugin token shown in the dashboard. The bundled Java helper computes and sends the required HMAC signature and headers for you.

Payload structure

{
  "plugin": { "name": "MyPlugin", "version": "1.2.3" },
  "stats": { "servers": 1, "players": 42, "downloads": 215 },
  "meta": { "server_uuid": "...", "server_name": "My Server", "spigot_last_update": "2026-02-01 17:36:12" }
}

Key notes:

• plugin: basic plugin info (name + version).
• stats: numeric/stat fields for banners (server/player counts, custom numeric stats).
• meta: arbitrary metadata. Keys prefixed with spigot_ or github_ are mapped into their respective groups in the Designer.

Java helper (recommended)

The project ships a simple Java helper: EzBannersApi. It handles payload construction, signatures and repeating tasks.

// Send a single update
EzBannersApi api = new EzBannersApi(ezBannersPlugin);
ApiClient.ApiResponse resp = api.sendPluginStats("", this, 1, 12);
if (!resp.isSuccess()) { getLogger().warning("Push failed: " + resp.getMessage()); }

// Start periodic pushes every 60s
api.startAutoStatsPush("", this, 60);

Extra stats and meta

Call the extended API to include additional fields:

Map extraStats = new LinkedHashMap<>();
extraStats.put("downloads", 215);
Map meta = new LinkedHashMap<>();
meta.put("spigot_last_update", "2026-02-01 17:36:12");
api.sendPluginStats(pluginUuid, this, 1, 12, extraStats, meta);

Signature & headers

The helper computes the HMAC signature and sends these headers:

• X-Plugin-Token: plugin token
• X-Signature: HMAC_SHA256(token, timestamp + "." + body)
• X-Timestamp: seconds since epoch
• User-Agent: EzBanners/<version>

Troubleshooting

• Invalid token: ensure you used the plugin token from the dashboard.
• Signature mismatch: use seconds (not ms) and compute HMAC exactly as described.
• Designer doesn't show a field: only primitive stats/meta values are auto-exposed; flatten nested objects into primitive keys.

References

• Java helper: ezbanners/src/main/java/com/skyblockexp/ezbanners/api/EzBannersApi.java
• HTTP client & signing: ezbanners/src/main/java/com/skyblockexp/ezbanners/http/ApiClient.java
• HMAC helper: ezbanners/src/main/java/com/skyblockexp/ezbanners/util/HmacUtil.java

Related docs

• Java Plugin API — usage and examples for the bundled helper.
• Plugin guide — overview and plugin concepts.
• API reference — API endpoints and authentication details.
• Endpoints — list of public endpoints and parameters.