EzBanners API Docs Java Plugin API Docs

EzBanners Plugin: Advanced Configuration

This page provides detailed documentation for all configuration options available in the EzBanners plugin. For the latest version, see your config.yml file.

1. `api` Section

endpoint (string, optional):
The API endpoint for banner data uploads. Default: https://ezbanners.org/api/server/update. Only override for local testing or custom deployments.
token (string, required):
Your server's unique API token. Obtain this from the EzBanners dashboard. Used for authentication and request signing.

2. `server` Section

uuid (string, required):
The unique identifier for your Minecraft server. Used to associate banner data with your server. Provided in the dashboard.

3. `sync` Section

interval (integer, default: 30):
How often (in seconds) the plugin sends updates to the API. Minimum: 5 seconds.
max-backoff (integer, default: 300):
Maximum backoff time (in seconds) after repeated failures. Should be greater than or equal to interval.

4. `enabled.data.fields` Section

Controls which server data fields are sent to the API and available for banners. Example fields:

server_name
online_players
max_players
server_version
tps_1m, tps_5m, tps_15m
uptime
motd
whitelist
placeholders

To enable or disable fields, edit the list under enabled.data.fields in your config.

5. `placeholderapi.mappings` Section

Map custom placeholder names to PlaceholderAPI placeholders. Example:

placeholderapi:
  mappings:
    example_rank: "%vault_rank%"
    example_balance: "%vault_eco_balance_formatted%"
    custom_info: "%myplugin_custominfo%"

Use these mapped names in your banner templates. To add custom information, register your own PlaceholderAPI expansion or use an existing plugin that exposes your data as a placeholder. For example, if you want to show a custom statistic, create a PlaceholderAPI expansion and register a placeholder like %myplugin_custominfo%. Then add it to placeholderapi.mappings and reference custom_info in your banner template.

How to add custom information via PlaceholderAPI

Develop a PlaceholderAPI expansion (see official guide).
Register your custom placeholder, e.g. %myplugin_custominfo%.

Add a mapping in config.yml:

placeholderapi:
  mappings:
    custom_info: "%myplugin_custominfo%"

Use {{{ custom_info }}} in your banner template.

6. `debug` Section

enabled (boolean, default: false):
Enables verbose debug logging for troubleshooting. Set to true only when needed.

How to send data to your custom API and receive it in PHP

If you set api.endpoint to your own URL, EzBanners will POST server data as JSON. Example PHP code to receive and process the data:

/**
 * Example: Receive EzBanners data in PHP
 */
$input = file_get_contents('php://input');
$data = json_decode($input, true);
if (isset($data['data'])) {
    // Access fields, e.g. $data['data']['server_name']
    // Validate and process as needed
    file_put_contents('latest-server.json', json_encode($data['data'], JSON_PRETTY_PRINT));
}

For authentication, validate the X-Server-Token header and optionally the X-Signature (HMAC SHA256 of the body, using the token as key).

Plugin Data API (direct plugin banners)

Plugins can push structured JSON payloads directly to EzBanners without PlaceholderAPI. Use the plugin-scoped endpoint:

POST https://ezbanners.org/api/plugins/{plugin_uuid}/data
Headers:
  X-Plugin-Token: <your plugin API token>
  X-Timestamp: <unix timestamp>
  X-Signature: HMAC_SHA256(timestamp + '.' + rawBody, token)

Payload:
{
  \"plugin\": {
    \"name\": \"EzAuction\",
    \"version\": \"1.2.0\"
  },
  \"stats\": {
    \"activeAuctions\": 12,
    \"totalSales\": 3421
  },
  \"meta\": {
    \"status\": \"SALE LIVE\"
  }
}

EzBanners treats the dashboard name as authoritative, so the plugin name in payloads is ignored. Missing stats or meta keys simply render as empty placeholders.

Example `config.yml`

api:
  endpoint: "https://ezbanners.org/api/server/update"
  token: "YOUR_API_TOKEN"
server:
  uuid: "YOUR_SERVER_UUID"
sync:
  interval: 30
  max-backoff: 300
enabled:
  data:
    fields:
      - server_name
      - online_players
      - max_players
      - server_version
      - tps_1m
      - tps_5m
      - tps_15m
      - uptime
      - motd
      - whitelist
      - placeholders
placeholderapi:
  mappings:
    example_rank: "%vault_rank%"
    example_balance: "%vault_eco_balance_formatted%"
    custom_info: "%myplugin_custominfo%"
debug:
  enabled: false

Example plugin data config

plugin:
  id: 42
  name: "EzAuction"
api:
  endpoint: "https://ezbanners.org/api/plugins/42/data"
  token: "YOUR_PLUGIN_API_TOKEN"
sync:
  interval: 30
meta:
  status: "v1.21 Ready"

Plugin Shields/Badges

EzBanners now supports shield-style badges for plugin metrics. These are small, clean badges (similar to shields.io) that can be embedded in documentation, forums, or GitHub READMEs. If you want a higher-level overview with platform examples and conversion-focused guidance, visit the Minecraft Plugin Badges landing page.

Available Metrics

Metric	Description	Example URL
`version`	Plugin version	`/shields/plugins/{uuid}/version.png`
`downloads`	Total downloads from all sources	`/shields/plugins/{uuid}/downloads.png`
`rating`	Plugin rating (from Spigot/other sources)	`/shields/plugins/{uuid}/rating.png`
`status`	Active/inactive status (based on last seen)	`/shields/plugins/{uuid}/status.png`
`minecraft-versions`	Compatibility summary from `minecraft_versions`, using a compact range such as `1.20-1.21`	`/shields/plugins/{uuid}/minecraft-versions.png`
`server-software`	Compatibility summary from `server_software`, using compact labels such as `Paper/Folia` or `Paper/Folia+2`	`/shields/plugins/{uuid}/server-software.png`
`spigot`	Spigot resource ID	`/shields/plugins/{uuid}/spigot.png`
`github`	GitHub repository	`/shields/plugins/{uuid}/github.png`
`modrinth`	Modrinth project ID	`/shields/plugins/{uuid}/modrinth.png`
`hangar`	Hangar project slug	`/shields/plugins/{uuid}/hangar.png`
`spigot-downloads`	Spigot downloads from `meta.spigot.downloads` (orange badge, `spigot dl` label)	`/shields/plugins/{uuid}/spigot-downloads.png`
`modrinth-downloads`	Modrinth downloads from `meta.modrinth.downloads` (green badge, `modrinth dl` label)	`/shields/plugins/{uuid}/modrinth-downloads.png`
`modrinth-followers`	Modrinth followers from `meta.modrinth.followers` with a green `followers` label	`/shields/plugins/{uuid}/modrinth-followers.png`
`hangar-downloads`	Hangar downloads from `meta.hangar.downloads` (blue badge, `hangar dl` label)	`/shields/plugins/{uuid}/hangar-downloads.png`
`hangar-stars`	Hangar stars from `meta.hangar.stars` with a blue `stars` label	`/shields/plugins/{uuid}/hangar-stars.png`
`hangar-watchers`	Hangar watchers from `meta.hangar.watchers` with a blue `watchers` label	`/shields/plugins/{uuid}/hangar-watchers.png`
`spigot-version`	Spigot latest version from `meta.spigot.latest_version` with a native `spigot` label, falling back to `N/A`	`/shields/plugins/{uuid}/spigot-version.png`
`modrinth-version`	Modrinth latest version from `meta.modrinth.latest_version` with a native `modrinth` label, falling back to `N/A`	`/shields/plugins/{uuid}/modrinth-version.png`
`hangar-version`	Hangar latest version from `meta.hangar.latest_version` with a native `hangar` label, falling back to `N/A`	`/shields/plugins/{uuid}/hangar-version.png`
`github-release`	GitHub latest release from `meta.github.latest_release` with a native `release` label, falling back to `N/A`	`/shields/plugins/{uuid}/github-release.png`
`github-stars`	GitHub stars from `meta.github.stars` using the compact `formatNumber()` output, falling back to `N/A`	`/shields/plugins/{uuid}/github-stars.png`
`github-forks`	GitHub forks from `meta.github.forks` using the compact `formatNumber()` output, falling back to `N/A`	`/shields/plugins/{uuid}/github-forks.png`
`github-watchers`	GitHub watchers from `meta.github.watchers` using the compact `formatNumber()` output, falling back to `N/A`	`/shields/plugins/{uuid}/github-watchers.png`
`github-issues`	Open GitHub issues counted from the size of the `meta.github.open_issues` array, with healthier greens for lower counts and a warning yellow when the count climbs	`/shields/plugins/{uuid}/github-issues.png`
`license`	Normalized license badge sourced from `meta.hangar.license` first, then fallback metadata such as GitHub repository license fields, producing short badge-safe values like `MIT`, `GPL-3.0`, or `Custom`	`/shields/plugins/{uuid}/license.png`

Query Parameters

Parameter	Description	Example
`label`	Override the left label text	`?label=my%20plugin`
`color`	Override badge color (hex without #)	`?color=ff5733`
`style`	Badge style (flat, flat-square, plastic, for-the-badge)	`?style=flat`

Example Usage

# In Markdown (GitHub README, etc.)
![Version](https://ezbanners.org/shields/plugins/YOUR-UUID/version.png)
![Downloads](https://ezbanners.org/shields/plugins/YOUR-UUID/downloads.png?color=4c1)
![Rating](https://ezbanners.org/shields/plugins/YOUR-UUID/rating.png?label=user%20rating)
![Minecraft Support](https://ezbanners.org/shields/plugins/YOUR-UUID/minecraft-versions.png)
![Server Support](https://ezbanners.org/shields/plugins/YOUR-UUID/server-software.png)
![Spigot Downloads](https://ezbanners.org/shields/plugins/YOUR-UUID/spigot-downloads.png)
![Modrinth Downloads](https://ezbanners.org/shields/plugins/YOUR-UUID/modrinth-downloads.png)
![Modrinth Followers](https://ezbanners.org/shields/plugins/YOUR-UUID/modrinth-followers.png)
![Hangar Downloads](https://ezbanners.org/shields/plugins/YOUR-UUID/hangar-downloads.png)
![Hangar Stars](https://ezbanners.org/shields/plugins/YOUR-UUID/hangar-stars.png)
![Hangar Watchers](https://ezbanners.org/shields/plugins/YOUR-UUID/hangar-watchers.png)
![Spigot Version](https://ezbanners.org/shields/plugins/YOUR-UUID/spigot-version.png)
![Modrinth Version](https://ezbanners.org/shields/plugins/YOUR-UUID/modrinth-version.png)
![Hangar Version](https://ezbanners.org/shields/plugins/YOUR-UUID/hangar-version.png)
![GitHub Release](https://ezbanners.org/shields/plugins/YOUR-UUID/github-release.png)
![GitHub Stars](https://ezbanners.org/shields/plugins/YOUR-UUID/github-stars.png)
![GitHub Forks](https://ezbanners.org/shields/plugins/YOUR-UUID/github-forks.png)
![GitHub Watchers](https://ezbanners.org/shields/plugins/YOUR-UUID/github-watchers.png)
![GitHub Open Issues](https://ezbanners.org/shields/plugins/YOUR-UUID/github-issues.png)
![License](https://ezbanners.org/shields/plugins/YOUR-UUID/license.png)

# In BBCode (SpigotMC, etc.)
[IMG]https://ezbanners.org/shields/plugins/YOUR-UUID/version.png[/IMG]

# Topic page compatibility row
[IMG]https://ezbanners.org/shields/plugins/YOUR-UUID/minecraft-versions.png[/IMG] [IMG]https://ezbanners.org/shields/plugins/YOUR-UUID/server-software.png[/IMG]

Embedding on Topic Pages

Plugin authors can drop the compatibility shields into forum topic headers, changelog posts, or download pages to show supported Minecraft releases and server software at a glance.

# SpigotMC / forum topic BBCode
[center][IMG]https://ezbanners.org/shields/plugins/YOUR-UUID/minecraft-versions.png[/IMG]
[IMG]https://ezbanners.org/shields/plugins/YOUR-UUID/server-software.png[/IMG][/center]

# HTML block for a project website or docs topic page
<div class="plugin-compat">
  <img src="https://ezbanners.org/shields/plugins/YOUR-UUID/minecraft-versions.png" alt="Supported Minecraft versions">
  <img src="https://ezbanners.org/shields/plugins/YOUR-UUID/server-software.png" alt="Supported server software">
</div>

Copyable Embed Snippets

Forum Embed (BBCode)

Topic page compatibility strip

Modrinth followers

Hangar stars

Hangar watchers

GitHub open issues

License

Website Embed (HTML)

Topic page compatibility row