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

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

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.