Integrate Awards and Achievements

Models and Controllers

Awards are modeled using SC_Award, which stores the award information that is configured on the Scoreloop developer website.

SC_Achievement object is used to determine if an award has been achieved by a user or not, and links a specific SC_Award object with a corresponding Boolean value to indicate the achieved/unachieved status.

Controller

Sample Tasks

SC_AchievementsController

  • Provide access to the achievements information for any game and any user

SC_LocalAchievementsController

  • Set an Award as being achieved for a user

  • Update achievement progress

  • Query for session user's achievements progress, as it is not stored on the server

  • Synchronize locally stored information about the session user's achievements with the Scoreloop server

Configure your project to use Scoreloop awards:

Configure awards on the developer website.

Configure awards on the developer website by navigating to the awards section. The configuration process includes choosing a unique reverse DNS identifier for every award, specifying the "achieving value" of an award, the number of stages required to reach it, and so on.

Add the awards bundle to your game project.

Once your awards are configured on the Scoreloop developer website, you should download the sl_awards_bundle.zip file that Scoreloop generates, extract it, and add the SLAwards.bundle folder to your project. This provides local access to information about the awards that are configured, including their identifiers and achieving values.

Any changes made to your awards on the developer website requires you to download the new sl_awards_bundle.zip from the site and update it in your game project for the changes to be reflected in your game.

Copy SLAwards.bundle to the correct path using the following bar-descriptor.xml entry: 

<asset path="SLAwards.bundle">scoreloop/SLAwards.bundle</asset>

Scoreloop looks for all the assets it needs in the Scoreloop subfolder (this can't be configured or changed).

The SLAward.bundle is typically structured as follows: 

SLAwards.bundle/
   <List of Award Icons>
   Info.json
   en.lproj/
       Localizable.strings

You can create different "lproj" folders with localizable.strings if you wish to support other languages. For example, another "lproj" folder called "he.lproj" is needed to support Hebrew. In this case, the SLAward.bundle is typically structured as follows: 

SLAwards.bundle/
   <List of Award Icons>
   Info.json
   en.lproj/
       Localizable.strings
   he.lproj/
       Localizable.strings

You can set any language in SC_Client_New() with the last parameter. It would then pick up the corresponding "lproj" subfolder. For example, if you specify "he" for Hebrew in the last parameter, "he.lproj" will be picked up at run time.

Basic integration

Use cases to integrate awards and achievements:

  1. Set an award as achieved or update achievement progress.

  2. Load achievements for the current game for any specific user.

Use case 1: Set an award as achieved or update achievement progress This step consists of the following:

  • Set SC_Award as achieved for a user.

  • Synchronize data that is stored locally with the Scoreloop server.

Set an award as achieved Check if an award has reached the achieving value by calling SC_LocalAchievementsController_IsAchievedForAwardIdentifier(). This method returns YES if the award has been achieved. When a user reaches the achieving value in a game, set SC_Award as achieved by calling one of the following APIs:

SC_Error_t errCode;
SC_Bool_t aRetValue;

//Step 1
// myLocalAchievementsController - Local Achievement Controller instance handle
// anAwardIndentifier is the unique reverse DNS string that you chose to identify the award.
// aValue - the value to be set for the award
// aRetValue - the return value that results in the award being achieved by the user for first time
errCode = SC_LocalAchievementsController_SetValueForAwardIdentifier(myAchievementsController, anAwardIndentifier, aValue, &aRetValue);

//Alternatively, the award can be set as achieved for the user by using its unique reverse DNS identifier
errCode = SC_LocalAchievementsController_SetAchievedValueForAwardIdentifier(myAchievementsController, anAwardIndentifier, &aRetValue);

//Alternatively, to increment the value by 1 each time, implement the following:
errCode = SC_LocalAchievementsController_IncrementValueForAwardIdentifier(myAchievementsController, anAwardIndentifier, &aRetValue);

//To check if the award has been achieved
aRetValue = SC_LocalAchievementsController_IsAchievedForAwardIdentifier(myAchievementsController, anAwardIndentifier);

Synchronize data that is stored locally with the Scoreloop server. The synchronization will upload only fully achieved awards. The achievements in progress that haven’t reached the achieved value will not be synchronized but stored locally until they are achieved. More than one achievement may be updated before synchronizing (this is why we have manual synchronization instead of automatic).

Steps involved are:

  1. Call SC_LocalAchievementsController_ShouldSynchronize() to check if there are fully achieved awards and synchronization is needed.

  2. If this returns true, call SC_LocalAchievementsController_Synchronize() to update the server with the local data.

//Steps 1 and 2
if (SC_LocalAchievementsController_ShouldSynchronize {
SC_LocalAchievementsController_Synchronize(myAchievementsController);
}

Check and synchronize awards as and when required. Awards must be synchronized at game start up, at the end of a gameplay, on minimizing the game and before the game shuts down.

Use case 2: Accessing the achievements information

Load achievements for the current game for any specific user:

The steps are as follows:

  1. Get an instance of SC_AchievementsController by using the client instance to create one or by reusing an existing instance.

  2. Call SC_AchievementsController_LoadAchievements() to make the request.

  3. Await successful response using callbacks.

  4. Upon successful response, access the retrieved SC_AchievementList by calling SC_AchievementsController_GetAchievements().

SC_Error_t errCode;
SC_AchievementsController_h myAchievementsController;
SC_AchievementList_h myAchievementList;

//Step 1
// client - assumes the handle to the client exists
// achievementsControllerCallback is the callback to be registered
errCode = SC_Client_CreateAchievementsController(client, &myAchievementsController, achievementsControllerCallback, aCookie);

//Step 2
//Load achievements for the local awards bundle
errCode =  SC_AchievementsController_LoadAchievements(myAchievementsController, user);

// Step 3 & 4
//to be written by the developer
//accessing loaded achievements from the callback
void achievementsControllerCallback(void* userData, SC_Error_t completionStatus) {
// Access the list that was retrieved
myAchievementList = SC_AchievementsController_GetAchievements(myAchievementsController);
}

Default UI: Awards and Achievements

The Awards and Achievements view displays the list of awards in achieved and unachieved state.

For details on implementation, see Integrate Default UI.