Introduction to Leaderboards for iOS

Supported Platforms:

iPhone: yes (with online and offline support) Android: only a subset of the features described on this page and online only


OpenFeint leaderboards are a powerful yet simple way of encouraging social competition in your game. Leaderboards in OpenFeint have the following behaviors: High Scores can either be ranked globally or filtered by a players friends. High Scores can be sorted in ascending or descending order. Each player can have one ranked score per leaderboard. A game can have an unlimited number of leaderboards. Leaderboards can be named whatever youd like. Leaderboards are not shared across games. You can restrict leaderboards by your games bundle version. Score submitted when offline will be sent to the server the next time they are playing online. If displayText is passed when submitting that is shown in the high score list instead of the score.

Aggregate leaderboard

OpenFeint supports aggregate leaderboards that allow you to summarize any number of other leaderboards. These are useful when you want to have a set of leaderboards all contribute to another leaderboard. Aggregated leaderboards are created on the developer dashboard.

Note: You cannot recursively aggregate leaderboards.

Quick Start

Add a leaderboard to your application from the Developer Dashboard. Note the Unique Identifier of your new leaderboard. In your application, submit the players score like this:

  OFHighScoreService setHighScore:
    scoreGoesHere forLeaderboard:@"leaderboard_id_string"
    onSuccess:[OFInvocation invocationForTarget:self selector:@selector(onSuccess:)]
    onFailure:[OFInvocation invocationForTarget:self selector:@selector(onFailure:)]

Downloading leaderboard data for custom display

OFScoreEnumerator provides a high level means to download leaderboard data for custom display inside your game. The sample app included with the OF SDK includes code demonstrating OFScoreEnumerator that you can copy into your own app. OFHighScoreService provides a lower level alternative means to fetch leaderboard data. OFScoreEnumerator is built on top of OFHighScoreService. The scores are paginated, which means that you can only request a certain number of records at a time.

Time Scoped Leaderboards

Custom-displayed leaderboard data can be filtered by age measured in days since the present. Leaderboards displayed within the OF user dashboard use this ability to implement a row of tabs for All, This Week, and Today. To use this feature in your own custom display of leaderboard data, you must use the low level API declared in OFLeaderboardService.h. Note that the getPage method accesses a paginated series of scores. Two variations of the getPage method include a timeScope parameter. When timeScope=1, only scores posted in the last day are retrieved. When timeScope=7 only scores posted in the last week will be retrieved. The special case of timeScope=0 allows all scores to be retrieved. You may search within the OF SDK source code for references to timeScope to see how the OF user dashboard uses this feature.

High Level Header Files


Low Level Header Files