Skip to main content

Leaderboard Competitions

The Challenge​

You're running a gaming or betting platform where users place bets, play games, and compete. But looking at your metrics, something's wrong:

  • 😴 Most users play once and disappear
  • 🎯 No competitive element to keep users engaged
  • 📉 Retention rates are lower than expected
  • 💔 Users don't return for weekly or monthly events

The question: How do you turn casual players into competitive regulars who return every week?

The Solution: Competitive Leaderboards​

The secret? Competition drives engagement. When users see their ranking and can climb the leaderboard, magic happens:

  • 🏆 Engagement increases - users return to improve their rank
  • 🔄 Session frequency multiplies as users check standings
  • 💰 Revenue grows - competitive users bet/play more
  • 👥 Community forms around weekly/monthly competitions
  • 🎁 Prize-driven behavior encourages consistent participation

In this guide, you'll build a complete leaderboard system featuring:

  • Weekly and monthly competitions
  • Real-time standings and rankings
  • Action-based point accumulation
  • Winner rewards and recognition

What You'll Build​

By the end of this guide, you'll have:

  1. Competition leaderboards that rank users by performance
  2. Automated point tracking based on user actions (bets, games, purchases)
  3. Real-time standings showing current rankings
  4. Time-bound competitions (weekly/monthly leagues)
Real-World Impact

Platforms with leaderboards see significantly higher engagement. Users return regularly to check their rank and compete for top positions, dramatically increasing retention and activity.

Before You Start​

Make sure you have:

  • ✅ RapidMule account and API key (Get one here)
  • ✅ Users registered in RapidMule (via Player API)
  • ✅ Action tracking set up (bets, purchases, games, etc.)

Setup: Configure Your First Leaderboard​

Before tracking competition points, you need to create a leaderboard in your RapidMule dashboard. Let's create a "Weekly Football Champions" leaderboard for football betting competitions.

Dashboard Configuration

Here's how to set up your first leaderboard step-by-step in the RapidMule dashboard:

Navigate to Leaderboards in your dashboard and create a new leaderboard:

Leaderboard Properties
Name: "Weekly Football Champions"
Type: Leaderboard
Description: "Top football bettors of the week compete for prizes"
Start Date: 2025-01-01
End Date: 2025-12-31
Limited: true
Randomized Prize: false

This leaderboard will track users who place bets during the week.

How Leaderboards Work

Unlike badges, leaderboards rank users against each other. Points are accumulated only from actions that satisfy the leaderboard's Condition (for this guide: place_bet actions where category is football). Qualifying actions add to the user's leaderboard score; non-qualifying actions are ignored. The user with the highest score gets Rank 1, second-highest gets Rank 2, and so on. It's a zero-sum competition - only one user can be #1!

Step 1: Track First Bet Action​

Sarah places her first bet of $50 on a football match. This bet will add points to the "Weekly Football Champions" leaderboard. Let's track it:

Understanding Bet Actions​

Bet actions include:

  • Bet amount - How much the user wagered
  • Event type - Sport, game, or category
  • Odds - Betting odds (optional)
  • Status - Pending, won, lost
POSThttps://api.rapidmule.com/v1/action/process

Track a bet action to add points to leaderboard

Leaderboard Points Logic

By default, the bet amount directly translates to points (e.g., $50 bet = 50 points). You can customize this in your dashboard with multipliers or different calculation logic (e.g., won bets count 2x).

What Just Happened?

  1. ✅ Sarah placed a $50 football bet
  2. ✅ RapidMule's engine added 50 points toward the football leaderboard
  3. ✅ To see rank/standings, query the Leaderboards endpoint (Step 3)

Next Challenge: What happens when Sarah places more bets? Let's see her climb the leaderboard...

Step 2: Climb the Leaderboard​

Sarah is hooked! She places 3 more football bets totaling $200 throughout the week. Each bet adds more points to her leaderboard score. Let's track her progress:

POSThttps://api.rapidmule.com/v1/action/process

Track another bet to improve leaderboard rank

Progress Check:

Sarah's journey on the leaderboard:

  • 🎯 First bet ($50) → Rank 12 (50 points)
  • 🚀 More bets ($200) → Rank 3 (250 points)
  • 🏆 Current status: Top 3 competitor!

Notice how each qualified bet updates her leaderboard totals. RapidMule recalculates rankings in near real-time; use the Leaderboards API to read the current standings.

Next Challenge: How do you view the full leaderboard standings? Let's check who's winning...

Step 3: View Leaderboard Standings​

Now let's see the complete leaderboard with all competitors. This is what powers your "Top Players" page in your app.

GEThttps://api.rapidmule.com/v1/admin/leaderboards/weekly-football-champions-lb

Retrieve leaderboard standings with all ranked users

No body required for GET requests

Frontend Display:

🏆 WEEKLY CHAMPIONS LEADERBOARD 🏆

#1  Mike Champion     ⭐ 450 pts
#2  Emma Ace          💎 380 pts
#3  Sarah             🔥 250 pts  ← You are here!
#4  John Bettor       📈 180 pts
#5  Lisa Pro          🎯 120 pts

Only 130 points to reach #2!
Keep betting to climb! 💪

Next Challenge: How do you create multiple leaderboards (daily, weekly, monthly)? Let's set up a competition calendar...

Step 4: Multiple Leaderboards​

Most platforms run multiple competitions simultaneously. Let's create a monthly leaderboard alongside the weekly one:

Dashboard Setup:

Monthly Competition
Name: "Monthly Masters"
Type: Leaderboard
Description: "Compete all month for the grand prize"
Start Date: 2025-01-01
End Date: 2025-01-31
Limited: true

How It Works:

When Sarah places a bet, it can count toward multiple leaderboards at once:

{
  "leaderboards": [
    {
      "uid": "daily-dominators-lb",
      "label": "Daily Dominators",
      "totalPoints": 100.0,
      "rank": 2
    },
    {
      "uid": "weekly-champions-lb",
      "label": "Weekly Champions",
      "totalPoints": 250.0,
      "rank": 3
    },
    {
      "uid": "monthly-masters-lb",
      "label": "Monthly Masters",
      "totalPoints": 850.0,
      "rank": 7
    }
  ]
}

Sarah competes in 3 leaderboards simultaneously! This creates multiple engagement hooks:

  • 🏃 Daily urgency - "I can win today!"
  • 📅 Weekly consistency - "I need to maintain my rank"
  • 🏆 Monthly ambition - "Top 3 gets the grand prize"

Verification: Check All Leaderboards​

Let's retrieve all active leaderboards to see what competitions are running:

GEThttps://api.rapidmule.com/v1/admin/leaderboards

Retrieve all leaderboards and their standings

No body required for GET requests

What You've Built​

Congratulations! You now have a complete competitive leaderboard system. Let's recap what you achieved:

🎯 Competition Flow You Created​

  • 🎲 User places bet → Points added to leaderboard(s)
  • 📈 More bets → Higher rank
  • 🏆 Check standings → See current position
  • 🔄 Repeat → Climb to #1

💡 Key Concepts You Learned​

  1. Leaderboard Type: Different from badges - ranks users competitively
  2. Real-Time Rankings: Positions update automatically as users compete
  3. Multiple Competitions: Run daily, weekly, monthly leaderboards simultaneously
  4. Summed Amount Challenge: Accumulate points based on action values (bet amounts)
  5. Standings API: Retrieve rankings to display in your frontend

📊 Business Impact​

With this system, you can now:

  • ✅ Create competitive urgency that drives daily engagement
  • ✅ Build retention loops through weekly/monthly competitions
  • ✅ Increase user activity with rank-chasing behavior
  • ✅ Boost revenue as users bet/play more to climb rankings
  • ✅ Foster community competition and social dynamics

What's Next?​

Explore complementary gamification patterns:

🎯 Other Engagement Strategies​

  1. E-commerce Purchase Tracking - Combine leaderboards with purchase-based badges
  2. Social Engagement Rewards - Rank contributors by content quality
  3. Habit Formation with Sliding Windows - Track competitive habit streaks

📚 Technical Resources​

Competition Ideas to Explore​

  • Category Leaderboards: Separate rankings for different game types/sports
  • Team Competitions: Guild vs Guild leaderboards
  • Streak Bonuses: Bonus points for consecutive daily participation
  • Tier-Based Leagues: Bronze, Silver, Gold leagues based on user level
  • Winner Rewards: Automatic prize distribution to top 3 finishers

Need Help?​

Success!

You've successfully implemented competitive leaderboards! Your users can now compete for rankings, driving engagement and retention through healthy competition. 🏆