EzBanners Roblox Integration

Display live Roblox game statistics in dynamic banner images for your game's social media, website, or developer forum. EzBanners supports Roblox-specific banner sizes and data fields.

Overview

The Roblox integration allows you to push game statistics to EzBanners via a secure REST API. Your game can send player counts, visits, favorites, ratings, and custom metrics. EzBanners then generates beautiful, customizable banner images that update in real-time.

Getting Started

1. Sign up for an account at ezbanners.org
2. Navigate to your dashboard and create a new Roblox Game
3. Copy your Roblox Game UUID and API token
4. Integrate the API endpoint into your game's ServerScriptService
5. Design your banner using the V2 Designer with Roblox data sources
6. Embed the generated banner URL on your website or social media

Authentication

All API requests require HMAC-SHA256 authentication headers:

• X-Roblox-Token: Your plaintext API token (issued by EzBanners)
• X-Timestamp: Current Unix timestamp (must be within ±5 minutes)
• X-Signature: HMAC-SHA256 signature of timestamp.rawBody using your token

Example signature calculation in Lua:

local HttpService = game:GetService("HttpService")
local timestamp = os.time()
local body = HttpService:JSONEncode(data)
local payload = tostring(timestamp) .. "." .. body
local signature = HttpService:GenerateHMACSHA256(payload, API_TOKEN)

API Endpoint

Send game statistics to:

POST https://ezbanners.org/api/roblox/{your-game-uuid}/data

Data Payload

Send a JSON payload with your game's statistics. The packaged Roblox scripts in roblox/game-scripts/EzBannersStatsSync.lua and roblox/game-scripts/StatsSyncServer.lua are intended to mirror this payload shape and the authentication headers shown above so the shipped Luau implementation stays aligned with these docs.

{
  "name": "Epic Adventure",
  "version": "2.1.0",
  "description": "An amazing Roblox experience",
  "stats": {
    "players": {
      "online": 150,
      "max": 500
    },
    "visits": 1000000,
    "favorites": 25000,
    "rating": 92.5
  },
  "meta": {
    "server_region": "us-east",
    "game_mode": "adventure"
  }
}

All fields are optional. Only send the data you want to display in your banner.

Roblox Banner Sizes

EzBanners supports Roblox-specific banner sizes optimized for the platform:

• 500x500 - Square format, ideal for Roblox thumbnails and profile displays
• 1920x1080 - Widescreen format, perfect for game detail pages and promotional material
• 468x60 - Standard web banner
• 728x90 - Leaderboard banner
• 300x250 - Medium rectangle
• 1200x300 - Large banner

Roblox badge shields

Roblox game badges use the same compact shield renderer shown in the badge gallery. The supported metric keys below come directly from RobloxGameShieldService::supportedMetrics(), so this list stays in sync with the service class.

• label replaces the left side text. Example: ?label=community.
• color overrides the generated badge color using a hex value such as 00a2ff.
• style supports flat, flat-square, plastic, and for-the-badge.

![Game](https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/game.png)

[IMG]https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/game.png[/IMG]

<img src="https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/game.png" alt="Game badge" />

![Playing](https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/playing.png)

[IMG]https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/playing.png[/IMG]

<img src="https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/playing.png" alt="Playing badge" />

![Visits](https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/visits.png)

[IMG]https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/visits.png[/IMG]

<img src="https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/visits.png" alt="Visits badge" />

![Favorites](https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/favorites.png)

[IMG]https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/favorites.png[/IMG]

<img src="https://ezbanners.org/shields/roblox-games/YOUR-GAME-UUID/favorites.png" alt="Favorites badge" />

Embedding Banners

Once configured, your banner is available at:

https://ezbanners.org/banners/roblox/{your-game-uuid}.png?size=500x500

Use this URL in HTML image tags, Markdown, or forum BBCode:

<img src="https://ezbanners.org/banners/roblox/{uuid}.png?size=1920x1080" alt="Game Stats" />

Complete Lua Example

Here's a complete example for sending game stats from a Roblox ServerScript. It matches the first-party files under roblox/game-scripts/ by using the same headers, payload keys, and override pattern for fields such as version, visits, and custom meta.

local Players = game:GetService("Players")
local ServerScriptService = game:GetService("ServerScriptService")

local EzBannersStatsSync = require(ServerScriptService:WaitForChild("EzBannersStatsSync"))

local statsSync = EzBannersStatsSync.new({
    baseUrl = "https://ezbanners.org",
    gameUuid = "YOUR-GAME-UUID",
    apiToken = "your-api-token-here",
    updateInterval = 60,
    retryCount = 3,
    retryBaseDelay = 2,
    retryBackoffMultiplier = 2,
    payloadBuilder = function()
        return {
            name = game.Name,
            version = "2.1.0",
            stats = {
                players = {
                    online = #Players:GetPlayers(),
                    max = Players.MaxPlayers,
                },
            },
        }
    end,
    payloadOverrides = {
        stats = {
            visits = 1000000,
        },
        meta = {
            release_channel = "production",
        },
    },
})

statsSync:start()

Best Practices

• Update Frequency: Send updates every 30-60 seconds. Avoid excessive requests that may trigger rate limiting.
• Error Handling: Always wrap HTTP requests in pcall() and implement retry logic with exponential backoff.
• Security: Never expose your API token in client scripts. Keep all API calls server-side.
• Data Validation: Validate your data before sending to avoid errors and wasted API calls.
• Testing: Use the ?invalidate_cache=1 parameter during development to see changes immediately.