Badges

Where skills draw a curve and coins drip over time, a badge freezes a moment. "7-day streak". "First 10 lessons". "Helped 5 classmates".

What badges can key off

• Milestone events — "complete your 100th lesson"
• Streaks — "7-day streak"
• Skill levels — "reach Pronunciation level 5"
• Collections — "earn all sports-themed items"
• Evolution stages — "reach stage 3"
• Coin thresholds — "earn 1,000 coins"
• Custom — any combination via the rule engine

Auto vs manual award

Badges can be auto-awarded (the rule engine evaluates the condition and awards immediately) or manual (the dashboard operator or an external workflow awards them after review).

Manual badges emit badge.ready webhooks — subscribe a moderation queue if you want humans in the loop.

Example

Week Warrior — auto-awarded on 7-day streak, plays a shine animation in the widget, fires badge.awarded. Also grants +50 coins as a side effect.

How to set it up

1. Name, icon, and description.
2. Pick a condition type (milestone, streak, skill, coin, custom).
3. Decide auto vs. manual award.
4. Optionally attach a coin or token reward.

Gotchas

• Custom conditions read the event payload — renaming properties silently breaks the rule. Version your event schemas.
• Manual badges fire badge.ready, not badge.awarded. Make sure your workflow calls POST /badges/:id/award when the human says yes.