Integrate users

Models and controllers

SC_User models Scoreloop users. Instances of SC_User have access to the unique Scoreloop user login, as well as information regarding the state of a user, for example, whether they have been authenticated on the server.

Two distinct data controllers manage the SC_User:

Controller Function
SC_UserController Retrieves a single user’s details.
SC_UsersController Searches for users on the server. Filters search results according to some criteria.

The session user

An instance of SC_User is always available using the Scoreloop session object. This instance is referred to in the accompanying documentation as the current session user. When a Scoreloop-enabled device connects to the Scoreloop server, the current session user is automatically updated with the most recent information on the server. The session user can be accessed as below:

  1. Call SC_UserController to create a SC_User object.
  2. Load the user details with a call to SC_UserController_LoadUser(). If no user has been explicitly set, attributes for the current session user will be requested.
  3. Await a successful server response using callbacks.
  4. Access and display the retrieved user by calling SC_UserController_GetUser().
SC_Error_t errCode;
SC_Client_h client;
SC_User_h currentSessionUser;
SC_UserController_h myUserController;

//create user controller
//aCallback is the callback to be registered
errCode=SC_Client_CreateUserController(client, &myUserController, aCallback, aCookie);

//load user details

//Returns the current session user.
currentSessionUser = SC_Session_GetUser(mySession);
SC_User_h currentSessionUser;

//Returns the current session user.
currentSessionUser = SC_Session_GetUser(mySession);

Scoreloop APIs that return SC_User objects

SC_User objects can be created indirectly using a number of different methods. Along with the method outlined above, SC_User objects can be accessed through the following methods:

Scoreloop Class Method Comment
SC_Score SC_Score_GetUser() Score objects that you create by invoking the class constructor are automatically associated with the current session user. Calling SC_Score_GetUser() on these score objects returns the current session user. SC_Score objects may also be retrieved from the server using SC_ScoresController. Calling SC_Score_GetUser() on these objects will return the user who submitted that particular score.
SC_Challenge SC_Challenge_GetContender() SC_Challenge_GetContestant() SC_Challenge_GetWinner() SC_Challenge_GetLoser()

Calling SC_Challenge_GetContender() on challenge objects that are newly created returns the session user. The outcome of calling SC_Challenge_GetContestant() depends on whether the challenge is open or direct. For open challenges, calling SC_Challenge_GetContestant() returns null. For direct challenges, calling SC_Challenge_GetContestant() returns the user to whom the challenge was directly assigned. Calling SC_Challenge_GetWinner() and SC_Challenge_GetLoser() is only meaningful after a challenge is complete.

SC_UserController SC_UserController_GetUser() Returns the user that is explicitly associated with the controller, (by calling SC_UserController_SetUser()) If no user is explicitly set, the session user is returned instead.
SC_UsersController SC_UsersController_GetUsers() Returns the list of SC_User objects that is retrieved by one of the controller's requests to the server. The list that is returned will differ according to the search criteria that you use for the controller

Basic integration

The following code demonstrates how to implement some basic Scoreloop features that involve users and are based on the following use cases:

  1. Retrieving user details from the server.
  2. Updating user details on the server.
  3. Searching for users on the server.

Use Case 1: Retrieving user data from the server

  1. Create an instance of SC_UserController
  2. Use the controller's SC_UserController_RequestUser() method to request details for the current session user.
  3. Await successful server response using the delegate callbacks.
  4. After a successful request, use the controller's SC_UserController_GetUser() method to access the SC_User object.
  5. Access individual user properties using the accessor methods of SC_User.
SC_Error_t errCode;
SC_User_h myUser;
SC_String_h userLogin;
SC_String_h userEmail;
SC_UserController_h myUserController;

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

//Step 2
errCode = SC_UserController_RequestUser(myUserController);

//It is a good idea to show a progress indicator while making the server request

//Step 3 & 4
void controllerCallback( void* userData, SC_Error_t completionStatus) {
    myUser = SC_UserController_GetUser(myUserController);

//Step 5
userLogin = SC_User_GetLogin(myUser);
userEmail = SC_User_GetEmail(myUser);

Use Case 2: Updating User Data

  1. Create an instance of SC_UserController or reuse an existing instance.
  2. Get the user properties to be updated from the application UI.
  3. Get the current user from the Scoreloop Session object by calling SC_Session_GetUser().
  4. Use the setter methods of the SC_User to change the current user's properties with the new values from the UI.
  5. Use the controller's SC_UserController_UpdateUser() method to make the update on the server. Don't modify the User object while the asynchronous call is in progress, as this might result in unwanted data to be stored on the server.
SC_Error_t errCode;
SC_String_h username;
SC_String_h email;
SC_User_h myUser;
SC_UserController_h myUserController;

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

//Step 2
//Get values from the fields in the user interface
// Note that the methods in these examples are place-holders
// for custom methods that must be implemented by the developer.
username = nameView_get_username_fromUI();
email = emailView_get_email_fromUI();

// Get the current session user
// mySession -  assumes the handle to the current session exists
myUser = SC_Session_GetUser(mySession);

//Set the new user properties for the session user
SC_User_SetLogin(myUser, username);
SC_User_SetEmail(myUser, email);

//Use the controller to update the session user on the server
errCode = SC_UserController_UpdateUser(myUserController);

//Optionally show a progress indicator while making the server request

If the user update operation returns SC_INVALID_USER_DATA, you must call SC_UserController_GetValidationErrors() to obtain the exact cause of the failure, for example, (SC_EMAIL_ALREADY_TAKEN, SC_EMAIL_FORMAT_INVALID, SC_USERNAME_ALREADY_TAKEN, or SC_USERNAME_FORMAT_INVALID ). It may also return SC_EMAIL_ALREADY_TAKEN + SC_USERNAME_FORMAT_INVALID.

Take a look at SC_UserController_GetValidationErrors() for more information. You can also have a look at the model class, SC_Errors, for idea about what the error is and the value that corresponds to it.

Use Case 3: A simple user search function

The following examples show how to implement a simple user search function. The SC_UsersController is used to manage lists of SC_User objects and should be used in the following way.

  1. Create an instance of SC_UsersController
  2. Set the search limit for the controller using SC_UsersController_SetSearchLimit(). The search request stops returning user objects once this limit has been reached and will return only the number of matches instead. This number is limited to 999.
  3. Set the flag indicating whether the search should extend beyond users of the current game by calling SC_UsersController_SetSearchesGlobal().
  4. Make the server request by calling one of the following methods:
    • SC_UsersController_SearchByLogin()
    • SC_UsersController_SearchByEmail()
    • SC_UsersController_SearchBySocialProvider()
  5. Await a successful server response using delegate callbacks.
  6. Call SC_UsersController_GetUsers() to access the list of users retrieved from the server.
int aOffset, aLength;
SC_Error_t errCode;
SC_String_h aLogin;
SC_String_h email;
SC_UsersController_h myUsersController;
SC_UserList_h myUsersList;

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

//Step 2
//Set the limit for the controller (the search will stop after the specified number of matches). The default is 25.
errCode = SC_UsersController_SetSearchLimit(myUsersController, 15);

//Step 3
//Set the global search flag (SC_TRUE for searching all Scoreloop games)
SC_UsersController_GetSearchesGlobal(myUsersController, SC_TRUE);

//Step 4
SC_UsersController_SearchByLogin(myUsersController, aLogin, aOffset, aLength);

SC_UsersController_SearchByEmail(myUsersController, email, aOffset, aLength);

//Optionally show progress indicator while making server request

//Step 5 and 6
void controllerCallback( void* userData, SC_Error_t completionStatus) {
    myUsersList = SC_UsersController_GetUsers(myUsersController);

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