Leaderboards

What are Leaderboards?

Leaderboards allow users to compete and see how they stack up against each other. Once a leaderboard has been associated with a ProgramProgram - A time-ordered sequence of widgets. A program can have extra information attached, like scheduling data and video preview URL for aiding in producing the program in the Producer Site. A widget can only be published to a single program, and only subscribers to a given program will see its widgets., users who earn rewards in that program will have them counted toward their ranks on that leaderboard.

A program can have many leaderboards associated, and a leaderboard can be linked with many programs. This allows you to better capture your own experience's structure better, such as allowing all-time, seasonal, or single event leaderboards, and even mixing and matching them.

Configuring Leaderboards

To get started you need to first configure a Reward Item.

When you've configured a Reward Item you can:

  1. Head to your Application on the Producer Site
  2. Select "Leaderboards" in the Sidebar
  3. Select the "New Leaderboard" button
  4. Set the Leaderboard name, Reward Item, and the associated Program(s).
  5. Select "Create" to finish

Now, the Leaderboard will be tracking user's progress!

Getting leaderboards associated with a program

You have the option to retrieve all leaderboards associated to a program by using the code samples below. This function will return an array of leaderboards.

class HelloWorld {
  let sdk: EngagementSDK
  
  sdk.getLeaderboards(programID: "<program id>") { result in
     switch result {
       case let .success(leaderboards):
        //do something with leaderboards
       case let .failure(error):
        print(error)
     }
  }
}
LiveLike.getLeaderboards({programId: "<program id>"})
    .then(leaderboards => console.log(leaderboards));
sdk.getLeaderBoardsForProgram(
                    programId, object : LiveLikeCallback<List<LeaderBoard>>() {
                        override fun onResponse(result: List<LeaderBoard>?, error: String?) {
                            result?.let {}
                            error?.let {
                                showToast(error)
                            }
                        }
                    }
                )
final List<LeaderBoard> list = await sdk.getLeaderBoards(<program-id>);

Getting leaderboard details

If you know a leaderboard id, you are able to get its details by using the code samples below. This can be useful if you would like to know the name of the leaderboard or the type of reward a user can earn.

class HelloWorld {
  let sdk: EngagementSDK
  
  sdk.getLeaderboard(leaderboardID: "<leaderboard id>") { result in
     switch result {
       case let .success(leaderboard):
        //do something with a leaderboard
       case let .failure(error):
        print(error)
     }
  }
}
LiveLike.getLeaderboard({leaderboardId: "<leaderboard id>"})
    .then(leaderboard => console.log(leaderboard));
sdk.getLeaderBoardDetails(leaderBoardId,
                        object : LiveLikeCallback<LeaderBoard>() {
                            override fun onResponse(result: LeaderBoard?, error: String?) {
                                result?.let {}
                            error?.let {
                                showToast(error)
                            }
                            }

                        })
final LeaderBoard detail=await sdk.getLeaderBoardDetails(<leaderBoardId>);

Getting leaderboard entries

A user that competes is considered a leaderboard entry. Use the code samples below to retrieve leaderboard entries for a specific leaderboard. Due to the nature of leaderboard entries growing to a very high number, this call is paginated with each page returning 20 leaderboard entries.

class HelloWorld {
  let sdk: EngagementSDK
  
  sdk.getLeaderboardEntries(leaderboardID: "<leaderboard id>", page: .first) { result in
     switch result {
       case let .success(leaderboardEntries):
        //do something with leaderboardEntries
       if leaderboardEntries.hasNext == false {
         // you have reached the last leaderboard entry page
       }
       case let .failure(error):
        print(error)
     }
  }
  
  // ** Available in iOS SDK 2.48+ **
  // Get leaderboard entries filtered by profile IDs
  let requestOptions = GetLeaderboardEntriesRequestOptions(
    leaderboardID: "<leaderboard ID>",
    profileIDs: ["<profile ID 1>", "<profile ID 2"]
  )
  sdk.getLeaderboardEntries(
      page: .first,
      options: requestOptions
  ) { result in
        
    switch result {
    case let .success(leaderboardEntries):
        // handle success 
    case let .failure(error):
        // handle failu
    }
  }
}
LiveLike.getLeaderboardEntries({
  leaderboardId: "<leaderboard id>",
  profileIds: ["<profileId1>","<profileId2>"]
})
.then(leaderboardEntries => console.log(leaderboardEntries));
sdk.getEntriesForLeaderBoard(
                leaderBoardId!!,
                LiveLikePagination.FIRST,
                object :
                    LiveLikeCallback<List<LeaderBoardEntry>>() {
                    override fun onResponse(
                        result: List<LeaderBoardEntry>?,
                        error: String?
                    ) {
                        result?.let {}
                        error?.let {
                            showToast(error)
                        }
                    }
                })
final List<LeaderBoardEntry> result = await sdk.getEntriesForLeaderBoard(
        <leaderboard-id>, <LiveLikePagination>);

Getting leaderboard entry for a given profile

Details about a leaderboard entry can be retrieved by providing a profile id and a leaderboard id. This can be useful if there is a leaderboard entry you are interested in keeping track of.

class HelloWorld {
  let sdk: EngagementSDK
 
  sdk.getLeaderboardEntry(profileID: "<profile id>", leaderboardID: "<leaderboard id>") { result in
     switch result {
       case let .success(entry):
        //do something with a leaderboard entry
       case let .failure(error):
        print(error)
     }
  }
}
LiveLike.getLeaderboardProfileRank({leaderboardId:"<leaderboard id>", profileId:"<profile id>"})
    .then(profileRank => console.log(profileRank));
sdk.getLeaderBoardEntryForProfile(
                        leaderBoardId,
                        profileId,
                        object : LiveLikeCallback<LeaderBoardEntry>() {
                            override fun onResponse(result: LeaderBoardEntry?, error: String?) {
                               
                                result?.let {
                                    
                                }
                                error?.let {
                                    showToast(error)
                                }
                            }
                        })
final LeaderBoardEntry result = await sdk.getLeaderBoardEntryForProfile(
        <leaderboard-id>, <profile-id>);

Getting a leaderboard entry for the current user profile

Retrieving details about the current user's profile can be done using the code samples below. This can be used to look up the current user's ranking in a specific leaderboard.

class HelloWorld {
  let sdk: EngagementSDK

  sdk.getLeaderboardEntryForCurrentProfile(leaderboardID: "<leaderboard id>") { result in
     switch result {
       case let .success(entry):
        //do something with a leaderboard entry
       case let .failure(error):
        print(error)
     }
  }
}
LiveLike.init({ clientId }).then(profile => {
    LiveLike.getLeaderboardProfileRank({leaderboardId: "<leaderboard id>", profileId: profile.id})
    .then(profileRank => console.log(profileRank))
});

// or
LiveLike.getLeaderboardProfileRank({leaderboardId: "<leaderboard id>", profileId: LiveLike.userProfile.id})
    .then(profileRank => console.log(profileRank))
sdk.getLeaderBoardEntryForCurrentUserProfile(
                       leaderBoardId,
                        object : LiveLikeCallback<LeaderBoardEntry>() {
                            override fun onResponse(result: LeaderBoardEntry?, error: String?) {
                              
                                result?.let {
                                   
                                }
                                error?.let {
                                    showToast(error)
                                }
                            }
                        })
final LeaderBoardEntry result = await sdk.getLeaderBoardEntryForCurrentUserProfile(<leaderboard-id>);

Subscribe to the Current User's Leaderboard Position

You can subscribe to the current user's Leaderboard position to receive updates when their position changes.

📘

Minimum SDK Version

iOS: 2.9
Android:
Web: 2.0.0

Get LeaderboardClients from Content Session

class MyViewController: UIViewController {
  let session: ContentSession
  var leaderboards: [LeaderboardClients]?
  
  override func viewDidLoad() {
    super.viewDidLoad()
    
    session.getLeaderboardClients { result in
      switch result {
      case .success(let leaderboards):
        self.leaderboards = leaderboards
        leaderboards.forEach { leaderboard in
          leaderboard.delegate = self
        }
      case .failure(let error):
        // handle error
      }
    }
  }
}

extension MyViewController: LeaderboardDelegate {
  func leaderboard(_ leaderboardClient: LeaderboardClient, currentPositionDidChange position: LeaderboardPosition) {
    // Do something (ie. update ui)
  }
}
const widgetContainer = document.querySelector('livelike-widgets');
widgetContainer.addEventListener('rankchange', e => console.log(e.detail));
session?.getLeaderboardClients(leaderboardIDs, object : LiveLikeCallback<LeaderboardClient>(){
                                    override fun onResponse(result: LeaderboardClient?, error: String?) {
                                       // result received, do something
                                    }
                                })

Get LeaderboardClient with Leaderboard ID

class MyViewController: UIViewController {
  let sdk: EngagementSDK
  var leaderboards: [LeaderboardClients]?  
  
  override func viewDidLoad() {
    super.viewDidLoad()
    
    sdk.getLeaderboardClients(leaderboardIDs: ["my-leaderboard"]) { result in
      switch result {
      case .success(let leaderboards):
        self.leaderboards = leaderboards
        leaderboards.forEach { leaderboard in
          leaderboard.delegate = self
        }
      case .failure(let error):
        // handle error
      }
    }
  }
}

extension MyViewController: LeaderboardDelegate {
  func leaderboard(_ leaderboardClient: LeaderboardClient, currentPositionDidChange position: LeaderboardPosition) {
    // Do something (ie. update ui)
  }
}

Getting total count of leaderboard entries

Integrators can fetch the total count of leaderboard entries to contextualize the user’s own rank.

let sdk: EngagementSDK

sdk.getLeaderboardEntries(leaderboardID: "<leaderboard id>", page: .first) { result in
     switch result {
     case let .success(leaderboardEntries):
         self.sdk.getLeaderboardEntryForCurrentProfile(leaderboardID: "<leaderboard id>") { result in
             switch result {
             case let .success(entry):
                 print("You placed \(entry.rank) out of \(leaderboardEntries.total)")
             case let .failure(error):
                 print(error)
             }
         }
     case let .failure(error):
         print(error)
     }
}
LiveLike.getLeaderboardEntries({leaderboardId: "<leaderboard id>"})
  .then(leaderboard => {
    LiveLike.getLeaderboardProfileRank(
      {
        leaderboardId: "<leaderboard id>", 
        profileId: LiveLike.userProfile.id
      })
      .then(entry => console.log(`You are placed ${entry.rank} out of ${leaderboard.count}`))
      .catch(err => console.log(err))
  });
  .catch(err => console.log(err));
lateinit var sdk: EngagementSDK
      
sdk.leaderboard().getEntriesForLeaderBoard(
    leaderBoardId,
    LiveLikePagination.FIRST,
    object :
        LiveLikeCallback<LeaderBoardEntryPaginationResult>() {
        override fun onResponse(
            result: LeaderBoardEntryPaginationResult?,
            error: String?
        ) {
            result?.let {
                (application as LiveLikeApplication).sdk.leaderboard().getLeaderBoardEntryForCurrentUserProfile(
                    leaderBoardId!!,
                    object : LiveLikeCallback<LeaderBoardEntry>() {
                        override fun onResponse(entry: LeaderBoardEntry?, error: String?) {
                            entry?.let {
                              Log.d("Entry rank","${ entry.rank} / ${result.count}")    
                                }
                            error?.let {
                                showToast(it)
                            }
                        }
                    }
                )
            }
            error?.let {
                showToast(error)
            }
        }
    }
)

What’s Next