Badge Progression Tracking

The BadgeTracker wraps Roblox’s BadgeService to prevent common award errors, track completion rates, and measure how long it takes players to earn specific badges.

Events Dispatched

Event Name	Category	Description
BadgeAwardSuccess	badge	Emitted when a badge is successfully awarded to a user.
BadgeAwardFailed	badge	Emitted when the award attempt fails (e.g. rate limit or API failure).
BadgeAlreadyOwned	badge	Emitted when the user already possesses the badge, skipping the award call.

Safe Awarding Method

Use Analytics:AwardBadge instead of raw BadgeService:AwardBadge:

local BADGE_ID = 212456789

local ok, wasAwarded, err = Analytics:AwardBadge(player, BADGE_ID)

if wasAwarded then
    print("Player earned a new badge!")
elseif not ok then
    warn("Badge award failed with error:", err)
end

Why use Analytics:AwardBadge?

1. Pre-checks Ownership: Calls BadgeService:UserHasBadgeAsync first, saving rate limits and avoiding redundant calls.
2. Measures Time-to-Earn: Automatically logs timeToEarnSeconds (time elapsed since player joined the server).
3. Safe pcall Wrapper: Prevents unhandled Roblox API exceptions from crashing your scripts.

Manual Recording

If your game already has its own badge award framework, you can hook telemetry into it without changing your logic:

Analytics:RecordBadgeAward(player.UserId, BADGE_ID, true, nil)

Querying Badge Statistics

-- Total times a specific badge has been awarded on this server
local count = Analytics:GetBadgeAwardCount(BADGE_ID)

-- Total badges of all types awarded on this server
local total = Analytics:GetTotalBadgesAwarded()