Integrate Default UI

Basic Integration

Below are some pointers before implementing Default UI.

1. Default UI requires access to BPS events.

2. While using a third party game engine, you need to create a window group. You will find more information here on how to create a window group.

3. Default UI is currently available only on CoreNative environment.

Step 1

Create SC_Client and pass it into SCUI_Client. Refer project setup and initialization for more details on how to create SC_Client.

Initialize the Scoreloop UI client as below:

SC_Error_t errCode;
SC_Client_h client;
SCUI_Client_h uiclient;

// Client already created during initialization.
errCode = SC_Client_New(&client, &initData, aGameId, aGameSecret, aGameVersion, aCurrency, aLanguageCode);
// If SC_OK, client created. Otherwise, client creation failed.

// Create the UI client
errCode = SCUI_Client_New(&uiclient, client);
// If SC_OK, UI client created. Otherwise, UI client creation failed.

Step 2

Pass event to the UI client. SCUI_Client_HandleEvent() should receive all BPS messages in the main loop of your application. This step goes hand in hand with the dispatch of other BPS events as described in Project setup and initialization.

// get an event
bps_event_t *event;
bps_get_event(&event, -1); // blocking

SCUI_Client_HandleEvent(uiclient, event);

Step 3

Optionally register a callback, to notify that the overlay screen is about to be displayed. It will be called only once per screen show and just before sliding in animation. The purpose of this call is to allow you to hide the spinners or handle any other types of Scoreloop-related errors that might occur. Errors might be a part of some precondition check e.g., a valid network connectivity, Scoreloop authentication, etc.,. At this stage, it is suggested to pause the game, as the view will take control over the whole screen.

// Callback defined somewhere inside the game
void MyOptionalViewBeforeShownCallback(void *cookie, SC_Error_t completionCode)
{
// If completionCode is SC_OK, UI will be displayed.
}

...

SC_Error_t errCode = SCUI_Client_SetViewEventCallback(uiclient, MyOptionalViewBeforeShownCallback, cookie);

Step 4

Invoke the UI and display the selected view. The following views are available on Default UI:

1. Favorite a game

2. Leaderboard

3. Awards & Achievements

The MyViewClosedCallback() will be called once, after the view is closed by the gamer. At that stage, the control is redirected back to the game and the can resume gameplay.

Favorite a game

Make a call to SCUI_Client_ShowFavoriteGamesView() to show the favorite a game view.

void MyViewClosedCallback(void *cookie, SCUI_Result_t result, const void *data) {
 // returned from favorite view
}

...

SC_Error_t errCode;

errCode = SCUI_Client_ShowFavoriteGamesView(uiclient, MyViewClosedCallback, cookie);
// If SC_OK, view will be displayed. Wait for MyViewClosedCallback() after the view is closed.
// Else, failed to show favorites view, no callback will be issued then.

// Optionally, wait for a callback notification called just before displaying a view (set via SCUI_Client_SetViewEventCallback()).

Leaderboard

Make a call to SCUI_Client_ShowLeaderboardView() to show the leaderboard view.

void MyViewClosedCallback(void *cookie, SCUI_Result_t result, const void *data) {
 // returned from leaderboard view
}

...

SC_Error_t errCode;
SCUI_LeaderboardViewOptions_t leaderboardOptions;
memset(&leaderboardOptions, 0, sizeof(SCUI_LeaderboardViewOptions_t)); // reset to default

// Select mode '1' as default 
leaderboardOptions.modeSelected = 1;

// Define modes to display (creates 15 modes from 0 to 14)
leaderboardOptions.modeMin = 0;
leaderboardOptions.modeMax = 15;

// Display 'Global' list as default
leaderboardOptions.listSelected = SCUI_LEADERBOARD_ACTIVE_GLOBAL;

// Allow display modes, which has no name defined in score-formatter
// and scroll-down to the user's current position
leaderboardOptions.flags = SCUI_LEADERBOARD_FLAGS_SHOW_RANGE_FOR_USER;
 
errCode = SCUI_Client_ShowLeaderboardView(uiclient, MyViewClosedCallback, &leaderboardOptions, cookie);
// If SC_OK, view will be displayed. Wait for MyViewClosedCallback() after the view is closed.
// Else, failed to show leaderboard view, no callback will be issued then.

// Optionally wait for a callback notification called just before displaying a view (set via SCUI_Client_SetViewEventCallback()).

It is also possible to specify a score along with other leaderboard options. A user made a score and wants to check out the leaderboard. This score has to be uploaded to the Scoreloop server before displaying the view.

SC_Score_h score = NULL;

errCode = SC_Client_CreateScore(client, &score);

errCode = SC_Score_SetResult(score, value);

errCode = SC_Score_SetMode(score, mode);

leaderboardOptions.score = score;

// Setup other leaderboard options, like: flags, modes range, selected list...

// Request view

// Release the score retained by SCUI_Client_ShowLeaderboardView().
SC_Score_Release(score);

Awards & Achievements

• Achievements are synchronized automatically before showing the achievements view. The synchronization will upload only fully achieved awards. The achievements in progress that haven’t reached the achieved value will not be synchronized. Progress of one or more achievements may be updated before synchronizing.

  Additionally check and synchronize awards as and when required. It's a good practice to synchronize them at game start up, at the end of a gameplay, or when gamer minimizes the game.

• Call SCUI_Client_ShowAchievementsView() to show the achievements view.

void MyViewClosedCallback(void *cookie, SCUI_Result_t result, const void *data) {
 // returned from achievements view
}

...

SC_Error_t errCode;
SCUI_AchievementsViewOptions_t achievementsOptions;
memset(&achievementsOptions, 0, sizeof(SCUI_AchievementsViewOptions_t)); // reset all to default values

// Display award icons in a grid
achievementsOptions.layout = SCUI_ACHIEVEMENTS_LAYOUT_GRID_ICONS_TITLE;

// Show rewards, if available
achievementsOptions.flags = SCUI_ACHIEVEMENTS_FLAGS_SHOW_REWARDS;

errCode = SCUI_Client_ShowAchievementsView(uiclient, MyViewClosedCallback, &achievementsOptions, cookie);
// If SC_OK, view will be displayed. Wait for MyViewClosedCallback() after the view is closed.
// Else, failed to show achievements view, no callback will be issued then.

// Optionally, wait for a callback notification called just before displaying a view (set via SCUI_Client_SetViewEventCallback()).