Integrate Leaderboards

Score components

Property

Description

Type

Status

Access

result

The primary result achieved by a player of your game.

double

Required

SC_Score_GetResult()

minorResult

A secondary result that you might want to consider for purposes of score comparison.

double

Optional

SC_Score_GetMinorResult()

level

The game stage at which the score was achieved.

unsigned int

Optional

SC_Score_GetLevel()

mode

The gameplay setting at which the score was achieved. Leaderboards are generated per mode.

unsigned int

Default Mode 0 present. Configuring additional modes Optional

SC_Score_GetMode()

You can set and retrieve the values for each of the score components by using the appropriate access methods available through SC_Score.

Models and Controllers

Scores are modeled around SC_Score and are managed by the following controllers:

Controller

Tasks

SC_ScoreController

Submits a score to Scoreloop

SC_ScoresController

Retrieves a list of scores from Scoreloop servers

Basic integration

Use cases to integrate leaderboards:
  1. Submit scores

  2. Retrieve scores

  3. Format scores

Use Case 1: Submit scores

To submit a score to the Scoreloop server:

  1. Create a SC_Score object by calling SC_Client_CreateScore().

  2. Set the result for the score by calling SC_Score_SetResult().

  3. Optionally, set the mode, minorResult and level of the score, if your game supports these, by calling SC_Score_SetMode(), SC_Score_SetMinorResult() and SC_Score_SetLevel(), respectively.

  4. Use the client instance to call SC_Client_CreateScoreController().

  5. Call SC_ScoreController_SubmitScore() to submit a score.

  6. Await a successful server response using callbacks.

SC_Error_t errCode;
SC_Client_h client;
unsigned int aMode, aLevel;
double aResult;
SC_ScoreController_h score_controller;
SC_Score_h score;

//Step 1
errCode = SC_Client_CreateScore(client, &score);

//Step 2
//aResult is the main numerical result achieved by a user in the game.
SC_Score_SetResult(score, aResult);

//Step 3
//aMinorResult is the score result of the game
SC_Score_SetMinorResult(score, aMinorResult);
//aMode is the mode of the game
SC_Score_SetMode (score, aMode);
//aLevel is the level in the game
SC_Score_SetLevel (score, aLevel);

//Step 4
// client - assumes the handle to the client exists
// aCallback is the callback to be registered
errCode = SC_Client_CreateScoreController (client, &score_controller, aCallback, aCookie);

//Step 5
SC_ScoreController_SubmitScore(score_controller, score);

//Step 6
//To be written by the developer
void controllerCallback(void* userData, SC_Error_t completionStatus) {
// Write code
}

Use Case 2: Retrieve scores

Retrieve ranking and scores from the Scoreloop server

  1. Use the SC_Client object to call SC_Client_CreateScoresController() and SC_Client_CreateRankingController().

  2. Set the searchlist for the controller by calling SC_ScoresController_SetSearchList(). Following pre-defined search lists are available: SC_SCORES_SEARCH_LIST_ALL, SC_SCORES_SEARCH_LIST_24H or SC_SCORES_SEARCH_LIST_USER_COUNTRY.

  3. Set the mode for the controller by calling SC_ScoresController_SetMode().

  4. Call SC_RankingController_LoadRankingForUserInMode() to request the user's ranking.

  5. Call SC_ScoresController_LoadScoresAroundUser() to request the scores around the user.

  6. Wait for a successful server response via callbacks.

  7. Once the request is complete, access the ranking and scores by calling SC_RankingController_GetRanking() and SC_ScoresController_GetScores() respectively.

unsigned int aRange;
SC_Score_h aScore;
SC_Client_h client;
SC_Error_t errCode;
SC_User_h aUser;
unsigned int aMode;
unsigned int aRank;
SC_ScoreList_h score_list;
SC_ScoresController_h scores_controller;
SC_RankingController_h ranking_controller;

//Step 1
// client - assumes the handle to the client exists
// aCallback is the callback to be registered
// Returns SC_OK is success.
errCode = SC_Client_CreateScoresController(client, &scores_controller, aCallback, aCookie);
errCode = SC_Client_CreateRankingController(client, &ranking_controller, aCallback, aCookie);

//Step 2
//setting the search list option
// aSearchList = SC_SCORES_SEARCH_LIST_ALL, SC_SCORES_SEARCH_LIST_24H or SC_SCORES_SEARCH_LIST_USER_COUNTRY
SC_ScoresController_SetSearchList (scores_controller, aSearchList);

//Step 3
//aMode is the game mode
SC_ScoresController_SetMode(scores_controller, aMode);

//Step 4 & 5
//Request user ranking
// pass @c NULL as the user object to load ranking of the session user
errCode = SC_RankingController_LoadRankingForUserInMode(ranking_controller, aUser, aMode);
//Request the scores around user
errCode = SC_ScoresController_LoadScoresAroundUser(scores_controller, aUser, aRange);

//Step 6 & 7
//Wait for callback - developer's method
static void aRankCallback(void *userData, SC_Error_t completionStatus){
aRank = SC_RankingController_GetRanking(ranking_controller);
}
static void aScoreCallback(void *userData, SC_Error_t completionStatus){
aScore = SC_ScoresController_GetScores(scores_controller);
}

Retrieve only scores from the Scoreloop server

  1. Use the SC_Client object to call SC_Client_CreateScoresController().

  2. Set the searchlist for the controller by calling SC_ScoresController_SetSearchList(). Following search lists are available:
    • SC_SCORES_SEARCH_LIST_ALL

    • SC_SCORES_SEARCH_LIST_24H

    • SC_SCORES_SEARCH_LIST_USER_COUNTRY.

  3. Set the mode for the controller by calling SC_ScoresController_SetMode().

  4. Wait for a successful server response via callbacks.

  5. Once the request is complete, access the scores that are returned by calling SC_ScoresController_GetScores().

SC_Error_t errCode;
unsigned int aRange;
SC_Score_h aScore;
SC_User_h aUser;
SC_Client_h client;
unsigned int aMode;
SC_ScoresController_h scores_controller;
SC_ScoreList_h score_list;
SC_ScoresSearchList_t aSearchList;

//Step 1
// client - assumes the handle to the client exists
// aCallback is the callback to be registered
errCode = SC_Client_CreateScoresController(client, &scores_controller, aCallback, aCookie);

//Step 2
//setting the search list option
// aSearchList = SC_SCORES_SEARCH_LIST_ALL, SC_SCORES_SEARCH_LIST_24H or SC_SCORES_SEARCH_LIST_USER_COUNTRY
SC_ScoresController_SetSearchList (scores_controller, aSearchList);

//Step 3
//aMode is the game mode
SC_ScoresController_SetMode(scores_controller, aMode);

//Step 4
//Request the scores by using one of the following methods
aRange.offset = 0;
aRange.length = 20;
errCode = SC_ScoresController_LoadScores(scores_controller, aRange);
errCode = SC_ScoresController_LoadScoresAroundScore(scores_controller, aScore, aRange);
errCode = SC_ScoresController_LoadScoresAroundUser(scores_controller, aUser, aRange);

//Steps 5 & 6
//Developer's method
void controllerCallback(void* userData, SC_Error_t completionStatus) {
score_list = SC_ScoresController_GetScores(scores_controller);
}

Retrieve only ranking from the Scoreloop server

  1. Use the SC_Client object to call SC_Client_CreateRankingController.

  2. Call SC_RankingController_LoadRankingForUserInMode() to request the user's ranking.

  3. Wait for a successful server response via callbacks.

  4. Once the request is complete, access the ranking by calling SC_RankingController_GetRanking().

SC_Error_t errCode;
unsigned int aRank;
SC_User_h aUser;
SC_Client_h client;
unsigned int aMode;

//Step 1
// client - assumes the handle to the client exists
// aCallback is the callback to be registered
errCode = SC_Client_CreateRankingController(client, &ranking_controller, aCallback, aCookie);

//Step 2
//Request user ranking
// pass @c NULL as the user object to load ranking of the session user
errCode = SC_RankingController_LoadRankingForUserInMode(ranking_controller, aUser, aMode);

//Steps 3 & 4
//Wait for callback - developer's method
static void aRankcallback(void *userData, SC_Error_t completionStatus){
aRank = SC_RankingController_GetRanking(ranking_controller);
}

Use Case 3: Format scores

SC_ScoreFormatter allows you to configure and display the score as required.

  1. Create an SLScoreFormatter.strings file. The Score Definition section on the developer website offers a score formatter, to configure the score to meet your game's requirements. Edit, copy and save the score formatter to SLScoreFormatter.strings. Additionally, the "Get Leaderboard Widget" link offers a preview of the formatted scores. It is important that the SLScoreFormatter.strings file contains your modified configuration. The widget is useful to display your game's score on a website.

  2. Use the following bar-descriptor.xml entry to add the SLScoreFormatter.strings file to the Scoreloop directory of your game project. Make sure to first create the Scoreloop subdirectory.
    <asset path="SLScoreFormatter.strings">scoreloop/SLScoreFormatter.strings</asset>
    
  3. Use the client instance to get the score formatter by calling SC_Client_GetScoreFormatter().

  4. For each score in the score list that is returned, call SC_ScoreFormatter_FormatScore(). Release the SC_String instance that is created.

Steps 3 and 4 can be implemented in the load Leaderboard Completion callback or wherever you want to display scores (for example, during score submission). Sample code for this would look something like:

SC_Error_t errCode;
SC_Client_h client;
SC_ScoreFormatter_h scoreFormatter;
SC_ScoreList_h scoreList;

// Step 3
// client - assumes the handle to the client exists
SC_ScoreFormatter_h scoreFormatter = SC_Client_GetScoreFormatter(client);

// Step 4
unsigned int i, numScores = SC_ScoreList_GetCount(scoreList);
for (i = 0; i < numScores; ++i) {
SC_Score_h score = SC_ScoreList_GetAt(scoreList, i);
SC_User_h user = SC_Score_GetUser(score);
SC_String_h login = user ? SC_User_GetLogin(user) : NULL;
SC_String_h formattedScore;

//Format the score - we take ownership of string
errCode = SC_ScoreFormatter_FormatScore(scoreFormatter, score, SC_SCORE_FORMAT_DEFAULT, &formattedScore);

//logging the details
printf("Rank: %d, Result: %s, User: %s", SC_Score_GetRank(score), SC_String_GetData(formattedScore),
login ? SC_String_GetData(login) : "<unknown>");

// Release the string
SC_String_Release(formattedScore);
}

Navigation on leaderboard

Navigation is important to allow the user to view all the scores on the leaderboard facilitated through scrolling or paging.

Perform the following checks to determine the direction of navigation.

  1. If ranking of the first score is greater than 1, then show “Go to TOP”.

  2. Call SC_ScoresController_HasPreviousRange() to check if navigation to previous page is possible. Show “Go to PREV”.

  3. Call SC_ScoresController_HasNextRange() to check if navigation to next page is possible. Show “Go to NEXT”.

Reload the scores, when navigation is requested. The following navigation methods also reload the scores.

Wait for a successful server response via callbacks. Once the request is complete, access the scores that are returned by calling SC_ScoresController_GetScores().

Attach a score context

SC_Score object is used to set/retrieve a score context.

Controller

Task

SC_Score_SetContext()

Set a score context.

SC_Score_GetContext()

Retrieve a score context.

Default UI: Leaderboard

Fastest integration can be achieved when using Default UI - Leaderboard. The leaderboard view will present a navigable list of scores. It will show available Global, Friends' and 24h lists. The score-formatter definition, user logins and images are downloaded from Scoreloop server dynamically. This view is customizable based on the following parameters:
  • Range of modes

  • Number of scores

  • Active mode and score list at startup

  • Submit a score

For details on implementation, see Integrate Default UI.

Last modified: 2013-12-21

comments powered by Disqus