Swarm Documentation API Reference

Adding Leaderboards to your App

Estimated Integration Time: 10 minutes

Leaderboards are a great way to get users to compete with their friends and the rest of your community, and they have been shown to increase number of user sessions while giving users a reason to keep getting better.

The first step is to define a measure of success for your users. In this guide, you will learn how to add Leaderboards by following an example for a leaderboard that tracks "Most Balloons Popped."

Leaderboards come in three different formats, Integer, Float, and Time. Integer and Float leaderboards are built for tracking integer and floating-point values respectively. Time based leaderboards use float values that represent "number of seconds". Examples are given below.

  • Integer: 5, Number of Balloons Popped.
  • Float: 6.3, Average Balloons Popped per Round
  • Time: 8.8, Fastest Lap Finished (measured in seconds)

Leaderboards can be sorted as Ascending (Low to High) or Descending (High to Low). Examples are given below.

  • Ascending: Golf Scores, Racing Times
  • Descending: Points, Survival Time

Prerequisite: Swarm Setup

Step 1: Define Leaderboards in the Admin Panel
  1. Go to your Swarm Admin Panel (click here).
  2. Click on your app's name in the app list.
  3. Create the leaderboard and click on Submit.
  4. Write down the Leaderboard Id number, as you'll need it very soon!

Step 2: Submit Score to Leaderboard
Call the following method to submit a score to the leaderboard where LEADERBOARD_ID is the Leaderboard ID number shown in the admin panel, and numBalloonsPopped is the score being submitted.
SwarmLeaderboard.submitScore(LEADERBOARD_ID, numBalloonsPopped);
[+] Click here to see more control and customization options.

Step 3: Show Leaderboard(s)
Option 1: Show a single leaderboard (where LEADERBOARD_ID is the Leaderboard ID number shown in the admin panel).
Option 2: Show a list of all your leaderboards.
Option 3: Show a single leaderboard immediately after submitting a score (within about 250ms or less):
SwarmLeaderboard.submitScoreAndShowLeaderboard(LEADERBOARD_ID, numBalloonsPopped)


Now you know how to add leaderboards to your apps. It's pretty easy, isn't it?. If you'd like to take it one step further, you can customize the look and feel of your leaderboards with Swarm's complete APIs.

Have you added Achievements or a Virtual Store yet? They both offer more excellent ways to improve your app!