Integrate Default UI

Basic Integration

Below are some pointers before implementing Default UI.

  1. Default UI requires access to BlackBerry Platform Services (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.

Follow the steps below to integrate Default UI:

Step 1

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

Initialize the Default UI client as below:

SC_Error_t errCode;
SC_Client_h client;
SC_ClientConfig_h clientConf;
SCUI_Client_h uiClient;

// Client already created during initialization. Refer to initialization
errCode = SC_Client_NewWithConfig(&client, clientConf);

// Create the UI client
errCode = SCUI_Client_NewWithCallback(&uiClient, client, MyViewResultCallback, cookie);
// If SC_OK, UI client created. Else, handle the case based on the errCode.

Step 2

Pass events 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.

bps_event_t *event;

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

if (bps_event_get_domain(event) == SC_GetBPSEventDomain(&initData))
{
     // Continue to pass events to SC_Client
     // This should already exist in your code, if not refer Initialization section
     SC_HandleBPSEvent(&initData, event);
}
// Addtionally, pass events to the SCUI_Client
SCUI_Client_HandleEvent(uiClient, event);

Step 3

Optionally register a view-event callback, to notify that the overlay screen is about to be displayed. It will be called only once per screen show and just before the 'sliding-in-animation'. The purpose of this call is to allow you to hide 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 MyOptionalViewEventCallback(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);

The SetViewEventCallback is used to check if all the operations succeeded or failed to display the view. Parameter completionCode will inform about the status. Example of those operations might be:

  • Session authentication (if required)
  • Score submission
  • Achievements synchronization. Failure here will result in issuing a SetViewEventCallback with parameter not equal to SC_OK.

Step 4

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

  1. Edit user profile
  2. Favorite a game
  3. Leaderboard
  4. Awards & Achievements
  5. Challenges

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

void MyViewResultCallback(void *cookie, SCUI_Result_t result, const void *data) {
   // If 'result' = SCUI_RESULT_ERROR, display appropriate error message.
   // The 'data' arg can be cast to SC_Error_t for more information on the error.

   // If 'result' = SCUI_RESULT_OK, continue with application.

   // If 'result = 'SCUI_RESULT_START_CHALLENGE, start a game-play for challenge. This case is illustrated in Challenges section below.
   // The 'data' arg can be cast to SC_Client_h and has to be remembered until the challenge is submitted.
}

Edit user profile

SC_Error_t errCode;
SCUI_Client_h uiClient = ..;
SC_UserController_h myUserController = ..;

errCode = SCUI_Client_ShowUserProfileView(uiClient);
// If SC_OK, view will be displayed. Else, handle the case based on the errCode, no callbacks will be issued then.

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

// Wait for the MyViewResultCallback().

errCode = SC_UserController_LoadUser(myUserController);
// If SC_OK, success. Else, handle the case based on the errCode.

Remember to refresh the image when updated.

Favorite a game

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

SC_Error_t errCode;
SCUI_Client_h uiClient = ..;

errCode = SCUI_Client_ShowFavoritingView(uiClient);
// If SC_OK, view will be displayed. Else, handle the case based on the errCode, no callbacks will be issued then.

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

// Wait for the MyViewResultCallback().

Leaderboard

SC_Error_t errCode;
SCUI_Client_h uiClient = ..;
 
// Optionally, call this method to scroll-down to the user's current position
errCode = SCUI_Client_SetLeadearboardFlags(uiClient, SCUI_LEADERBOARD_FLAGS_SHOW_LIST_AROUND_USER);

errCode = SCUI_Client_ShowLeaderboardView(uiClient, modeSelected, listSelected, optionalScore);
// Pass @c Null as optionalScore to not post a score. 
// If SC_OK, view will be displayed. Else, handle the case based on the errCode, no callbacks will be issued then.

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

// Wait for the MyViewResultCallback().

It is also possible to specify a score along with other leaderboard parameters. A user made a score and wants to check out the leaderboard. By providing the score to the ShowLeaderboardView(), the score will be uploaded to the Scoreloop server before the UI is displayed. A score is create as below:

SC_Error_t errCode;
SC_Score_h score;

errCode = SC_Client_CreateScore(client, &score);

errCode = SC_Score_SetResult(score, value);

errCode = SC_Score_SetMode(score, mode);

// Request view by passing score to show leaderboard view method.
errCode = SCUI_Client_ShowLeaderboardView(uiClient, modeSelected, listSelected, score);

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

Awards and 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.
SC_Error_t errCode;
SCUI_Client_h uiClient = ..;
SCUI_AchievementFlags_t flags = 0;

// Optionally, display award icons in a grid
flags = (SCUI_AchievementFlags_t)(flags | SCUI_ACHIEVEMENT_FLAGS_LAYOUT_GRID_ICONS);

// Optionally, show rewards, if available
flags = (SCUI_AchievementFlags_t)(flags | SCUI_ACHIEVEMENT_FLAGS_REWARDS_SHOW);

// Set flags - if required
SCUI_Client_SetAchievementFlags(uiClient, flags);

errCode = SCUI_Client_ShowAchievementsView(uiClient);
// If SC_OK, view will be displayed. Else, handle the case based on the errCode, no callbacks will be issued then.

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

// Wait for the MyViewResultCallback().

Challenges

There are two use cases for Challenges:

  1. Start a new challenge
  2. Display/accept/reject existing challenges

Use case 1: Start a new challenge

Step 1: A challenge can be created with or without stakes. Any stakes are allowed by default. Set the flag to SCUI_CHALLENGE_FLAGS_STAKE_NONE for no stakes and SCUI_CHALLENGE_FLAGS_STAKE_NONZERO for non zero stakes.

SCUI_Client_h uiClient = ..;
SC_Error_t errCode;

// Set flag to enable/disable stakes in challenges
errCode = SCUI_Client_SetChallengeFlags(uiClient, SCUI_CHALLENGE_FLAGS_STAKE_ANY);
// SCUI_CHALLENGE_FLAGS_STAKE_NONE for no stakes
// SCUI_CHALLENGE_FLAGS_STAKE_NONZERO for non zero stakes

// Set the money format for stakes on the UI
// Required only when stakes are enabled 
errCode = SCUI_Client_SetSimpleMoneyFormat(uiClient, "%.2f Coin(s)");

Step 2: To create a challenge, call SCUI_Client_ShowChallengeCreateView().

SCUI_Client_h uiClient = ..;
SC_Error_t errCode;

// Display the create challenge view
errCode = SCUI_Client_ShowChallengeCreateView(uiClient);
// If SC_OK, view will be displayed. Else, handle the case based on the errCode, no callbacks will be issued then.

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

// Wait for the MyViewResultCallback().

Step 3: If the user created a challenge, the MyViewResultCallback() will be called with result set to SCUI_RESULT_START_CHALLENGE. Here, the 'data' argument should be cast to a challenge, and retained in your application before starting the gameplay.

void MyViewResultCallback(void *cookie, SCUI_Result_t result, const void *data) {
// If 'result' = SCUI_RESULT_ERROR, display appropriate error message.
// The 'data' arg can be cast to SC_Error_t for more information on the error.
// If 'result' = SCUI_RESULT_OK, continue with application.


// Check if the user wants to start a challenge
if (result == SCUI_RESULT_START_CHALLENGE)
{
   // Get details of the Challenge from 'data' argument by casting it.
   SC_Challenge_h challenge = (SC_Challenge_h)data;

   // Remember challenge in your application - increment retain count
   // To be written by the developer
   MyApplication_SetChallenge(getApplication(cookie), challenge);

   // Start Game-Play with this challenge.
}

Step 4: Submit the challenge result after the gameplay.

SC_Client client;
SC_Errot_t errCode;
SC_Score_h score = NULL;

SC_Challenge_h challenge = MyApplication_GetChallenge(app);// Developer's method

// Create a score to submit with the challenge.
errCode = SC_Client_CreateScore(client, &score);

errCode = SC_Score_SetResult(score, value);

errCode = SC_Score_SetMode(score, mode);

// Submit the challenge with score.
errCode = SCUI_Client_ShowChallengeSubmitView(uiClient, challenge, score);
// If SC_OK, view will be displayed. Else, handle the case based on the errCode, no callbacks will be issued.

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

// Wait for the MyViewResultCallback().

// Note, in the MyViewResultCallback() the user could have started yet another challenge.

Once the challenge is submitted, the user might want to have a rematch. The user has opted for a rematch in the MyViewResultCallback() if result is set to SCUI_RESULT_START_CHALLENGE. Go back to step 3 in this case.

Use case 2: Display/accept/reject existing challenges

Display the open/direct challenges available for the user and the challenge history. The user can view the available challenges and history, choose to accept and play an available challenge, reject an available challenge or opt for a rematch from the history. The user can also create a new challenge from this view. The sample code illustrates these scenarios.

SCUI_Client_h uiClient = ..;
SC_Error_t errCode;

// Optionally, add stakes to challenges
errCode = SCUI_Client_SetChallengeFlags(uiClient, SCUI_CHALLENGE_FLAGS_STAKE_ANY);

// Set the money format for stakes on the UI
errCode = SCUI_Client_SetSimpleMoneyFormat(uiClient, "%.2f Coin(s)");

// Display the challenges view
errCode = SCUI_Client_ShowChallengesView(uiClient);
// If SC_OK, view will be displayed. Else, handle the case based on the errCode, no callbacks will be issued then.

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

// Wait for the MyViewResultCallback().
// If 'result' = SCUI_RESULT_OK, user left without creating/accepting a challenge. The user might have rejected a challenge. The Default UI will handle the 'reject challenge' internally. 
// If 'result' = SCUI_RESULT_START_CHALLENGE, user either accepted an existing challenge or opted for a rematch or created a new challenge. See Step 3 of Use case 1 for details.

Click here to see if your implementation covers the essential features.

Last modified: 2014-05-14



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus