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 🔗

1. Develop a PlaceholderAPI expansion (see official guide).
2. Register your custom placeholder, e.g. %myplugin_custominfo%.
3. Add a mapping in config.yml:

   placeholderapi:
     mappings:
       custom_info: "%myplugin_custominfo%"
   

4. 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.

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
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

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)

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

Notes & Best Practices

• Never share your API token publicly.
• Leave api.endpoint blank unless you are instructed to use a custom endpoint.
• Restart your server after making changes to config.yml.
• For advanced PlaceholderAPI usage, see the official PlaceholderAPI documentation.

Future Premium Plans

• Premium plugin templates with advanced gradients, icons, and animated-ready layouts.
• Higher render rate limits and longer cache TTLs for network-scale deployments.
• Team roles and shared plugin workspaces for agencies and networks.
• Priority template reviews and custom template design sessions.