Users

Manage credentials with a cross platform system

Here you’ll learn

Basic user structure and concepts (profile, session… ).

How to create a user and log him in.

Other calls to the Gamedonia API specific to manage your users.

User API

A User is a special type of Entity inside Gamedonia that is stored under a name reserved collection named _users. Common operations with users include signup, login, update or logout.

Structure

A User has two different parts. One is only managed internally by Gamedonia and the other one can be customized to fit your needs. A User entity is composed by the following parts:

Credentials

The credentials object stores user account credentials to login and keep a session open in your app. This data is never returned to the app when querying or retrieving a user. Currently, there are seven credential types:

  • email. An email and password are used. The email shouldn't be already in use by another user.

  • silent. An internal identifier of the device is used. This allows to signup and register a user silently.

  • facebook. Facebook access token and facebook user identifier are used as credentials.

  • twitter. Twitter uid, token secret and token are used as credentials.

  • gamecenter. User GameCenterId is used as credential.

  • kongregate. Supported only for ActionScript. Allows the user to login using a kongregate user account.

  • google. Supported only for Unity. Login with a Google account.

Profile

Public profile user data. You can customize this object with anything you want (simple fields, other entities, ...). This data is always returned in retrieve or query operations.

Sessions

When one user of your game completes a signup and performs a login against Gamedonia, he obtains an active Session.A Session represents a person using your game with valid credentials. Only one session per user and game is currently supported. If a user tries to log in on a different device or platform when he already has an open session, the first one will be closed and the only valid one will be the newest. All operations performed in the Gamedonia API with an active Session are performed on behalf of the user represented by this session, ensuring that all the access control policies are respected.

Session tokens have a time to live of two weeks. This means that after 2 weeks of inactivity, a session will become inactive automatically requesting the user to login to the game explicitly. Each time a session is used, the time to live counter is reset to zero.

The session is stored and encrypted in the user's Keychain allowing you to auto login in the application if needed. This data persists even if the application is deleted. For example, if the app is reinstalled, the stored session will be reused to avoid your game asking for the user credentials again.

Mapping

The user API uses three types of entities to exchange information between the game and Gamedonia Backend.

GDUserProfile

This is the core object that defines a User Account. It contains the account identifier and the user profile public data. GDUserProfile includes an IDictionary profile property where you can store anything you want to customize the user profile in your app.

GDUser

This type is an extension of GDUserProfile that adds a login credentials property.

Credentials

This type models the different types of credentials that a user can use to login to Gamedonia. A single credentials object manages all the credentials types.

Function List

Create User

Before a user can start a session in your app, he has to register in the app with his desired credentials. This is the way to sign up a new user in your Gamedonia backend.

// First create the credentials object for the account. In this example email credentials are used
 
Credentials credentials = new Credentials();
credentials.email = "the_email";
credentials.password = "the_password";
 
// Create the user account with some profile data and attach it to the credentials created in the previous block  
         
GDUser user = new GDUser();
user.credentials = credentials;
user.profile["nickname"] = "the_nickname";
         
// Make the request to Gamedonia Backend to create the account and process the result in a block.   
GamedoniaUsers.CreateUser(user, delegate (bool success){
    if (success){
        //TODO Your success processing
    }
    else{
        //TODO Your fail processing
    }
});

Parameters

  • user. Type GDUser. The user we want to create in Gamedonia. At least one credential type has to be provided. Profile data can be added now or later thorught an update.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.
void MyClass::createUser(CCString* email, CCString* password, CCString* nickname) {
    // First create the credentials object for the account.
    // In this example email credentials are used.
    TCredentials credentials;
    credentials.setEmail(email->getCString());
    credentials.setPassword(password->getCString());

    // Create the user account with some profile data and attach it the created credentials.
    TGDUser* user = new TGDUser();
    user->credentials = credentials;
    user->getProfile()->AddMember("nickname", nickname->getCString(), user->getAllocator());

    // Make the request to Gamedonia Backend to create the account and process the result
    GamedoniaSDKUser::createUser(user, this, gamedoniaResponse_selector(MyClass::onCreateUserResponse));
}

void MyClass::onCreateUserResponse(bool success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}

Parameters

  • user. Type TGDUser. The user we want to create in Gamedonia. At least one credential type has to be provided. Profile data can be added now or later through an update.
  • target. Type CCObject. The target entity where the selector is implemented to handle the callback.
  • callback. Type gamedoniaResonse selector. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.
// First create the credentials object for the account.
// In this example email credentials are used.
Credentials *credentials = [[Credentials alloc] init];
[credentials setEmail:@"email"];
[credentials setPassword:@"password"];

// Create the user account with some profile data and attach it the created credentials.
GDUser * user = [GDUser alloc];
NSMutableDictionary *profile = [NSMutableDictionary dictionary];
[profile setObject:@"the_nickname" forKey:@"nickname"];
[user setProfile:profile];
[user setCredentials:credentials];

// Make the request to the Gamedonia Backend to create the account and process the result in a block.
[[Gamedonia users] createUser:user
                   callback:^(BOOL success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}];

Parameters

  • user. Type GDUser. The user we want to create in Gamedonia. At least one credential type has to be provided. Profile data can be added now or later through an update.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type BOOL. Indicates if the operation worked correctly.
// First create the credentials object for the account.
// In this example email credentials are used.
var credentials:Credentials = new Credentials();
credentials.email = "email";
credentials.password = "password";

// Create the user account with some profile data and attach it the created credentials.
var user:GDUser = new GDUser();
var profile:Object = new Object();
profile.nickname = "the_nickname";
user.credentials = credentials;
user.profile = profile;

// Make the request to the Gamedonia Backend to create the account and process the result in a block.
GamedoniaUsers.createUser(user, function (success:Boolean):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});

Parameters

  • user. Type GDUser. The user we want to create in Gamedonia. At least one credential type has to be provided. Profile data can be added now or later through an update.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type Boolean. Indicates if the operation worked correctly.
-- First create the credentials object for the account.
-- In this example email credentials are used.
local credential = {}
credential.email = "email";
credential.password = "password"

-- Create the user account with some profile data and attach it the created credentials.
local user = {}
user.credential = credential
user.profile = profile
local profile = {}
profile."nickname" = "the_nickname"

local CB = function (success)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

-- Make the request to the Gamedonia Backend to create the account and process the result in a block.
Gamedonia.Users.createuser ("user", success)

Parameters

  • user. The user we want to create in Gamedonia. At least one credential type has to be provided. Profile data can be added now or later through an update.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.
// Callback handler must inherit from GamedoniaCallbackHandler
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onCreateUserResponse(bool success)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

void MyClass::createUser(const std::string& email, const std::string& password)
{
    // First create the credentials object for the account.
    // In this example email credentials are used.
    TGDCredentials credentials;
    credentials.setEmail(email);
    credentials.setPassword(password);

    // Create the user account with some profile data and attach it the created credentials.
    TGDUser user;
    user.setCredentials(credentials);

    // Make the request to Gamedonia Backend to create the account and process the result
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::createUser(user, response, gamedoniaResponseLogin_selector(MyCbresponse::onCreateUserResponse));
    response->release();
}

Parameters

  • user. Type GDUser. The user we want to create in Gamedonia. At least one credential type has to be provided. Profile data can be added now or later through an update.
  • target. Type GamedoniaCallbackHandler. The target entity that implements the gamedoniaResponseLogin selector.
  • callback. Type gamedoniaResponseLogin selector. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.

User creation requires that the provided credentials are unique in your database so if you provide a duplicate credential (for instance, a user already registered with the same mail) the operation will fail and you will get success = false in the callback. If you are providing more than one credential, all of them must be unique.

Login User

Once the user has been created, a session on behalf of this user can start. The Login call will open a session for a specific user.

Login with email

There is a custom login method on Gamedonia SDK for each type of credentials. For example for a email/password login you will use:

GamedoniaUsers.LoginUserWithEmail("the_email", "the_password", delegate (bool success){
    if (success){
        //TODO Your success processing
    }
    else {
        //TODO Your fail processing
    }
});

Parameters

  • email. Type string. User email.
  • password. Type string. Password for that user email.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.
void MyClass::loginUser(CCString* email, CCString* password) {
    GamedoniaSDKUser::loginUserWithEmail(email->getCString(), password->getCString(), this, gamedoniaResponse_selector(MyClass::onLoginUserResponse));
}

void MyClass::onLoginUserResponse(bool success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}

Parameters

  • email.Type CCString*. User email.
  • password. Type CCString*. Password for that user email.
  • target. Type CCObject*. The target entity that implement the gamedoniaResponseSelector callback.
  • callback. Type gamedoniaResponseSelector. Function called as result to this operation. Takes the following parameters:
    • success. Type bool. Indicates if the operation worked correctly.
[[Gamedonia users] loginUserWithEmail:@"email"
                   password:@"password"
                   callback:^(BOOL success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}];

Parameters

  • email. Type NSString. User email.
  • password. Type NSString. Password for that user email.
  • callback. Block called as result to this operation. Takes the following parameters:
    • success. Type BOOL. Indicates if the operation worked correctly.
GamedoniaUsers.loginUserWithEmail("email", "password", function (success:Boolean):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});

Parameters

  • email. Type String. User email.
  • password. Type String. Password for that user email.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type Boolean. Indicates if the operation worked correctly.
local CB = function (success)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

Gamedonia.Users.loginWithEmail ("the_email", "password", CB)

Parameters

  • email. Type String. User email.
  • password. Type String. Password for that user email.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type Boolean. Indicates if the operation worked correctly.
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onLoginResponse(bool success)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

void MyClass::loginUser(const std::string& email, const std::string& password)
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::loginUserWithEmail(email, password, response, gamedoniaResponseLogin_selector(MyCbresponse::onLoginResponse));
    response->release();
}

Parameters

  • email. Type std::string. User email.
  • password. Type std::string. Password for that user email.
  • target. Type GamedoniaCallbackHandler. The entity that implements the gamedoniaResponseLogin selector function that will handle the response.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type bool. Indicates if the operation worked correctly.

Login with session token

Upon getting a response, all login methods will return an instance of GDSessionToken. That is, an Object that includes the Session Token string representation and its expiration date. GDSessionToken is managed internally, so you don't need to pass any additional parameters to the login method.

If you already initiated a session with Gamedonia you can use a fast process to restore the Gamedonia session without bothering the user. To restore the session using the stored Keychain session token you can use:

GamedoniaUsers.LoginUserWithSessionToken(delegate (bool success){
    if (success){
        //TODO Your success processing
    }
    else {  
        //TODO Your fail processing
    }
});

Parameters

  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.
void MyClass::loginUser() {
    GamedoniaSDKUser::loginUserWithSessionToken(this, gamedoniaResponse_selector(MyClass::onLoginUserResponse));
}

void MyClass::onLoginUserResponse(bool success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}

Parameters

  • target. Type CCObject*. The entity that implements the callback.
  • callback. Type gamedoniaResponse_selector. Function called as result to this operation. Takes the following parameters:
    • success. Type bool. Indicates if the operation worked correctly.
[[Gamedonia users] loginUserWithSessionToken:session_token
                   callback:^(BOOL success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}];

Parameters

  • session_token. Type NSString*. The session_token we want to revalidate. Can be retrieved from the user preferences.
  • callback. Block called as result to this operation. Takes the following parameters:
    • success. Type BOOL. Indicates if the operation worked correctly.
GamedoniaUsers.loginUserWithSessionToken(session_token, function (success:Boolean):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});

Parameters

  • session_token. Type String. The session_token we want to revalidate. Can be retrieved from the user preferences.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type Boolean. Indicates if the operation worked correctly.
local CB = function (success)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

Gamedonia.Users.loginWithSessionToken (session_token, CB)

Parameters

  • session_token. The session_token we want to revalidate. Can be retrieved from the user preferences.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onLoginResponse(bool success)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

void MyClass::loginUser()
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::loginUserWithSessionToken(GamedoniaUser::getSessionToken(), response, gamedoniaResponseLogin_selector(MyCbresponse::onLoginResponse));
    response->release();
}

Parameters

  • session_token. Type std:string. The session_token we want to revalidate. Can be retrieved from the user preferences.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type bool. Indicates if the operation worked correctly.

Parameters

  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.

The standard procedure should be to try an explicit login only if this LoginUserWithSessionToken method returns a false result.

Login with Facebook

For a login with Facebook credentials you will use:

GamedoniaUsers.LoginUserWithFacebook(fbuid, fbAccessToken, delegate (bool success){
    if (success){
        //TODO Your success processing
    }
    else {  
        //TODO Your fail processing
    }
});
void MyClass::loginUser(CCString* fbuid, CCString* fbAccessToken) {
    GamedoniaSDKUser::loginUserWithFacebook(fbuid->getCString(), fbAccessToken->getCString(), this, gamedoniaResponse_selector(MyClass::onLoginUserResponse));
}

void MyClass::onLoginUserResponse(bool success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
[[Gamedonia users] loginUserWithFacebook:@"the-fb-uid"
                   fbAccessToken:@"the-access-token"
                   callback:^(BOOL success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}];
GamedoniaUsers.loginUserWithFacebook("fb-uid","fb-access-token", function (success:Boolean):void {
    if (success) {
       //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
local CB = function (success)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

GamedoniaUsers.loginWithFacebook (fbuid, fbfbAccessToken, CB)
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onLoginResponse(bool success)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

void MyClass::loginUser(const std::string& fb_uid, const std::string& fb_access_token)
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::loginUserWithFacebook(fb_uid, fb_access_token, response, gamedoniaResponseLogin_selector(MyCbresponse::onLoginResponse));
    response->release();
}

Parameters

  • fbuid. Type string. Facebook user identifier.
  • accessToken. Type string. A valid Facebook accessToken for the fbuid provided.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.

Login with Facebook is covered in depth in the Facebook guide, so please read that guide if you want to know how you can get the user fbuid and accessToken to perform a login using these credentials.

This operation will fail if there is no registered user in Gamedonia with the specified Facebook credentials.

Login with Twitter

For a login with Twitter credentials you need:

GamedoniaUsers.LoginUserWithTwitter(twuid, twTokenSecret, twToken, delegate (bool success){
    if (success) {
        //TODO Your success processing
    }
    else {  
        //TODO Your fail processing
    }
});
void MyClass::loginUser(CCString* twuid, CCString* twTokenSecret, CCString* twToken) {
    GamedoniaSDKUser::loginUserWithTwitter(twuid->getCString(), twTokenSecret->getCString(), twToken->getCString(), this, gamedoniaResponse_selector(MyClass::onLoginUserResponse));
}

void MyClass::onLoginUserResponse(bool success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
[[Gamedonia users] loginUserWithTwitter:@"twuid" 
										twTokenSecret:@"tw_token_secret" 
										twToken:@"tw_token" 
										callback:^(BOOL success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}];
GamedoniaUsers.loginUserWithTwitter("twuid", "twTokenSecret", "twToken", function ():void{
if (success) {
       //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});

local CB = function (success)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end
 
GamedoniaUsers.loginWithTwitter (twuid, twTokenSecret, twToken, CB)

class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onLoginResponse(bool success)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

void MyClass::loginUser(const std::string& twuid, const std::string& twTokenSecret, const std::string& twToken)
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::loginUserWithTwitter(twuid, twTokenSecret, twToken, response, gamedoniaResponseLogin_selector(MyCbresponse::onLoginResponse));
    response->release();
}

Parameters

  • twuid. Type string. Twitter user identifier.
  • twAccessToken. Type string. A valid Twitter tokenSecret for the tw_uid provided.
  • twToken. Type string. A valid Twitter token for the tw_uid provided.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.

This operation will fail if there is no registered user in Gamedonia with the specified Twitter credentials.

Login with Gamecenter

For a login with GameCenter credentials you need:

GamedoniaUsers.LoginUserWithGameCenterId(gcuid, delegate (bool success){
    if (success) {
        //TODO Your success processing
    }
    else {  
        //TODO Your fail processing
    }
});
void MyClass::loginUser(CCString* gcuid) {
    GamedoniaSDKUser::loginUserWithGameCenterId(gcuid->getCString(), this, gamedoniaResponse_selector(MyClass::onLoginUserResponse));
}

void MyClass::onLoginUserResponse(bool success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
[[Gamedonia users] loginUserWithGameCenterId:@"gcuid" 
										callback:^(BOOL success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}];
GamedoniaUsers.loginUserWithGameCenterId("gcuid", function ():void{
if (success) {
       //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});

local CB = function (success)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end
 
GamedoniaUsers.loginWithGameCenterId (gcuid, CB)

class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onLoginResponse(bool success)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

void MyClass::loginUser(const std::string& gcuid)
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::loginUserWithGameCenterId(gcuid, response, gamedoniaResponseLogin_selector(MyCbresponse::onLoginResponse));
    response->release();
}

Parameters

  • gcuid. Type string. GameCenter user identifier.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.

This operation will fail if there is no registered user in Gamedonia with the specified GameCenter credentials.

Login with Kongregate

For a login with Kongregate credentials you need:

GamedoniaUsers.loginUserWithKongregate( konguid, kongAccessToken, function (success):void {

	if (success) {
	       //TODO Your success processing

    } else {
        //TODO Your fail processing
    }
});

Parameters

  • konguid. Type string. Kongregate user identifier.
  • kongAccessToken. Type string. A valid Kongregate token for the konguid provided.
  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.

This operation will fail if there is no registered user in Gamedonia with the specified Kongregate credentials.

Login with Google

For a login with Google credentials you need:

GamedoniaUsers.LoginUserWithGoogle( google_token_id, delegate( bool login_success) {
                 
    if( login_success) {
        //TODO Your success processing
         
    } else {
        //TODO Your fail processing
    }
});

Parameters

  • google_token_id. Type string. Google token.
  • callback.Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.

To setup your game to support Google Sign in, head to our Google Sign guide, so please read that guide if you want to know how you can get the user google_token_id to perform a login using this credential.

This operation will fail if there is no registered user in Gamedonia with the specified Google credentials.

Using nested calls

Now that we have introduced a couple of calls to the Gamedonia API, let's discuss the way these calls should connected. Calls to Gamedonia functions are asynchronous. That means the code will call the function and when the server response comes, the callback function will be executed. Meanwhile, the code execution will continue. As a consequence, you have no guarantee that the code located after a Gamedonia API call will be executed after the code in the callback.

The correct way to call a Gamedonia API method after another is to nest the calls, that means, to put your code in the callback function of the previous method call. That way you know that the server gave a response to the previous call and you can also check if it went all right or something went wrong by evaluating the success parameter.

In this example, the method CreateUser is called first and LoginUser will be called only when the callback function of CreateUser is executed as a consequence of the server response. In this case, the success parameter is checked to be sure that the user creation not only has been received and responded by the server, but that it was also successfully executed (the new user was created).

// First create the credentials object for the account. In this example email credentials are used
Credentials credentials = new Credentials();
credentials.email = "the_email";
credentials.password = "the_password";

// Create the user account with some profile data and attach it to the credentials created in the previous block
GDUser user = new GDUser();
user.credentials = credentials;
user.profile["nickname"] = "the_nickname";

// Make the request to Gamedonia Backend to create the account and process the result in a block.
GamedoniaUsers.CreateUser(user, delegate (bool create_success){

    if (create_success){

        // The user was created successfully, so we can log him in
        GamedoniaUsers.LoginUserWithEmail("the_email", "the_password", delegate (bool login_success){

   			if (login_success){
        		//TODO Your login user success processing
    		
    		} else {
        		//TODO Your login user fail processing
    		}
		});

    } else {
        //TODO Your create user fail processing
    }
});
    	
void MyClass::createUser() {
    // First create the credentials object for the account.
    // In this example email credentials are used
    // We take the mail and password from text fields, like in a login form

    TCredentials credentials;
    credentials.setEmail("the_email");
    credentials.setPassword("the_password");

    // Create the user account with some profile data and attach it the created credentials.
    TGDUser* user = new TGDUser();
    user->credentials = credentials;
    user->getProfile()->AddMember("email", "the_password", user->getAllocator());

    // Make the request to Gamedonia Backend to create the account and process the result
    GamedoniaSDKUser::createUser(user, this, gamedoniaResponse_selector(MyClass::onCreateUserResponse));
}

void MyClass::onCreateUserResponse(bool success) {
    if (success) {
        // The user was created successfully, so we can log him in
        MyClass::loginUser();
    } else {
        //TODO Your create user fail processing
    }
}

void MyClass::loginUser() {
    GamedoniaSDKUser::loginUserWithEmail("the_email", "the_password", this, gamedoniaResponse_selector(MyClass::onLoginUserResponse));
}

void MyClass::onLoginUserResponse(bool success) {
    if (success) {
        //TODO Your login user success processing

    } else {
        //TODO Your login user fail processing
    }
}

		
// First create the credentials object for the account.
// In this example email credentials are used.
Credentials *credentials = [[Credentials alloc] init];
[credentials setEmail:@"the_email"];
[credentials setPassword:@"password"];

// Create the user account with some profile data and attach it the created credentials.
GDUser * user = [GDUser alloc];
NSMutableDictionary *profile = [NSMutableDictionary dictionary];
[profile setObject:@"the_email" forKey:@"name"];
[user setProfile:profile];
[user setCredentials:credentials];

// Make the request to the Gamedonia Backend to create the account and process the result in a block.
[[Gamedonia users] createUser:user callback:^(BOOL create_success) {
    if (create_success) {
        // The user was created successfully, so we can log him in
    	[[Gamedonia users] loginUserWithEmail:@"the_email" password:@"the_password" callback:^(BOOL login_success) {
    			if (login_success) {
        			//TODO Your login user success processing
    			}
    			else {
        			//TODO Your login user fail processing
    			}
		}];

    } else {
        //TODO Your create user fail processing
    }
}];



		
// First create the credentials object for the account.
// In this example email credentials are used.
var credentials:Credentials = new Credentials();
credentials.email = "the_email";
credentials.password = "the_password";

// Create the user account with some profile data and attach it the created credentials.
var user:GDUser = new GDUser();
var profile:Object = new Object();
profile.email = "the_email";
user.credentials = credentials;
user.profile = profile;

// Make the request to the Gamedonia Backend to create the account and process the result in a block.
GamedoniaUsers.createUser(user, function (create_success:Boolean):void {
    if (create_success) {
        // The user was created successfully, so we can log him in
        GamedoniaUsers.loginUserWithEmail("the_email", "the_password", function (login_success:Boolean):void {
    		if (login_success) {
        		//TODO Your login user success processing
    		}
    		else {
        		//TODO Your login user fail processing
    		}
		});
    } else {
        //TODO Your create user fail processing
    }
});
		
-- First create the credentials object for the account.
-- In this example email credentials are used.
local credential = {}
credential.email = "the_email";
credential.password = "the_password"

-- Create the user account with some profile data and attach it the created credentials.
local user = {}
user.credential = credential
user.profile = profile
local profile = {}
profile."email" = "the_email"

local CB_create = function (create_success)
    if create_success then
        -- The user was created successfully, so we can log him in
        local CB_login = function (success)
    		if success then
        		-- TODO Your login user success processing
    		else
        		-- TODO Your login user fail processing
    		end
		end

		Gamedonia.Users.loginWithEmail ("the_email", "the_password", CB_login)
    else
        -- TODO Your create user fail processing
    end
end

-- Make the request to the Gamedonia Backend to create the account and process the result in a block.
Gamedonia.Users.createuser ("user", CB_create)

		
// Callback handler must inherit from GamedoniaCallbackHandler
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onCreateUserResponse(bool success)
    {
        if (success) {
            // The user was created successfully, so we can log him in
                MyCbresponse* response = new MyCbresponse();
                GamedoniaUser::loginUserWithEmail("the_email", "the_password", response, gamedoniaResponseLogin_selector(MyCbresponse::onLoginResponse));
                response->release();
        } else {
            //TODO Your create user fail processing
        }
    }
};

class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onLoginResponse(bool success)
    {
        if (success) {
            //TODO Your login user success processing
        } else {
            //TODO Your login user fail processing
        }
    }
};

void MyClass::createUser()
{
    // First create the credentials object for the account.
    // In this example email credentials are used.
    TGDCredentials credentials;
    credentials.setEmail("the_email");
    credentials.setPassword("the_password");

    // Create the user account with some profile data and attach it the created credentials.
    TGDUser user;
    user.setCredentials(credentials);

    // Make the request to Gamedonia Backend to create the account and process the result
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::createUser(user, response, gamedoniaResponseLogin_selector(MyCbresponse::onCreateUserResponse));
    response->release();
}
}
		

Logout User

This will end the current logged in session on the system. It also removes the stored Keychain session token from your app so next time you try to perform a LoginWithSessionToken the operation will fail and you'll need to ask the user for credentials to perform an explicit login using any of the available methods.

GamedoniaUsers.LogoutUser(delegate (bool success){
    if (success){
        //TODO Your success processing
    }
    else{
        //TODO Your fail processing
    }
});
void MyClass::logoutUser() {
    GamedoniaSDKUser::logoutUser(this, gamedoniaResponse_selector(MyClass::onLogoutUserResponse));
}

void MyClass::onLogoutUserResponse(bool success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
[[Gamedonia users] logoutUser:^(BOOL success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}];
GamedoniaUsers.logoutUser(function (success:Boolean):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
local CB = function (success)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

Gamedonia.Users.logout (CB)
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onLogoutUserResponse(bool success)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

void MyClass::logoutUser()
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::logoutUser(response, gamedoniaResponseLogin_selector(MyCbresponse::onLogoutUserResponse));
    response->release();
}

Parameters

  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.

This operation will only fail if we try to logout a user when there is no open session against Gamedonia.

Get Me

Calling this operations will retrieve the logged in user profile and return it as a callback parameter.

GamedoniaUsers.GetMe(delegate (bool success, GDUserProfile profiles){
    if (success){
        //TODO Your success processing
    }
    else {
        //TODO Your fail processing
    }
});
void MyClass::getMe() {
    GamedoniaSDKUser::getMe(this, gamedoniaResponseUserProfile_selector(MyClass::onGetMeResponse));
}

void MyClass::onGetMeResponse(bool success, TGDUserProfile* profile) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
[[Gamedonia users] getMe:^(BOOL success, GDUserProfile *userProfile) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}];
GamedoniaUsers.getMe(function (success:Boolean, me:GDUserProfile):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
local CB = function (success, profile)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

Gamedonia.Users.getMe (CB)
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onGetMeResponse(bool success, const TGDUserProfile& profile)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

void MyClass::getMe()
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::getMe(response, gamedoniaResponseUserProfile_selector(MyCbresponse::onGetMeResponse));
    response->release();
}

Parameters

  • callback. Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.
    • profile. Type GDUserProfile. Represents the user profile data stored in Gamedonia. This entity has an "_id" member variable (internal user identifier represented as string) and a "profile" that is a Dictionary where the keys are strings and the values can be of any type. You should know what you have stored inside the profile to access the data correctly. You can enable debug mode to print in the log the returned entity so you can check your profile structure.

Get User

You can easily recover a specific User from your game backend if you know the _id attribute of the user.

GamedoniaUsers.GetUser(user_id, delegate (bool success, GDUserProfile data) { 
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
void MyClass::GetUser(const char *userId) {
    GamedoniaSDKUser::getUser (userId, this, gamedoniaResponseData_selector(MyClass::UserInfoCallback));
}

void MyClass::UserInfoCallback(bool success, TGDUserProfile* movie) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
[[Gamedonia users] getUser:@"<the-user-id>" 
                  callback:^(BOOL success, GDUserProfile *data) {

    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }          
}];
GamedoniaUsers.getUser(userId, function (success:Boolean, user:GDUserProfile):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
local CB = function (success, profile)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

Gamedonia.Users.getUser (userId, CB)
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onGetUserResponse(bool success, const TGDUserProfile& profile)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

void MyClass::getUser(const std::string& userId)
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::getUser(userId, response, gamedoniaResponseUserProfile_selector(MyCbresponse::onGetUserResponse));
    response->release();
}

Parameters

  • user_id. Type String. The id of the user you want to obtain.
  • callback Function called as result to this operation. Takes the following parameters:
    • success. Type boolean. Indicates if the operation worked correctly.
    • profile. Type GDUserProfile. Represents the user profile data stored in Gamedonia. This entity has an "_id" member variable (internal user identifier represented as string) and a "profile" that is a Dictionary where the keys are strings and the values can be of any type. You should know what you have stored inside the profile to access the data correctly. You can enable debug mode to print in the log the returned entity so you can check your profile structure.

Update User

We have designed two ways to update the User Profile in Gamedonia Backend with the goal of saving as much bandwidth as possible. There are two typical cases of use for updating: Override and Merge.

Overriding a User

Imagine you have a user profile already stored in your Gamedonia Backend you need to modify, remove, or add new key-values to. The easiest way to perform this update is by sending the whole user profile to Gamedonia in override mode so that the previous profile will be completely overridden by the new one.

//Dictionary profile ...
GamedoniaUsers.UpdateUser(profile, delegate (bool success) {
	if (success) {
		//TODO Your success processing
	} else {
		//TODO Your fail processing
	}
}, true);
void MyClass::UpdateUserProfile(CCDictionary* profile) {
    //CCDictionary profile with all fields fulfilled ...
    GamedoniaSDKUser::updateUser (profile, true, this, gamedoniaResponseData_selector(MyClass::ProfileUpdatedCallback));
}

void MyClass::ProfileUpdatedCallback(bool success, TGDUserProfile* profile) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
//NSMutableDictionary profile ...
[movie setObject:25 forKey:@"age"];
[movie removeObjectForKey:@"photo"];
[movie setObject:@"daddy" forKey:@"nickname"];

[[Gamedonia users] update:profile
                  overwrite:true
                  callback:^(BOOL success, NSDictionary *data) {

    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }           
}];
//Object profile with all fields fulfilled ...
GamedoniaUsers.updateUser(profile, true, function(success:Boolean):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
local updateCB = function (succes, data)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

Gamedonia.Users.updateUser (profile, true, updateCB)
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onUpdateProfileResponse(bool success, const TGDUserProfile& profile)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

void MyClass::updateUser(const TGDUserProfile& profile)
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::updateUser(profile, true, response, gamedoniaResponseUserProfile_selector(MyCbresponse::onUpdateProfileResponse));
    response->release();
}

Merging a User

The other scenario is when you have a huge user profile, with a lot of data stored inside of it, and you only need to update a single or a few values of the profile. Moving the heavy profile up and down the servers is a waste of bandwidth. To solve this problem you can use the merge update solution that will allow you to just send to the servers the key-values you want to update.

GamedoniaUsers.UpdateUser(profile, delegate (bool success) {
	if (success) {
		//TODO Your success processing
	} else {
		//TODO Your fail processing
	}
});
void MyClass::UpdateUserProfile(CCDictionary* profile) {
    //CCDictionary movie with only the modified fields ...
    GamedoniaSDKUser::updateUser (profile, false, this, gamedoniaResponseData_selector(MyClass::ProfileUpdatedCallback));
}

void MyClass::ProfileUpdatedCallback(bool success, TGDUserProfile* profile) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
NSDictionary * movie = [NSDictionary dictionaryWithObjectsAndKeys:
                        25, @"age",
                        nil];

[[Gamedonia users] update:profile
                  overwrite:false
                  callback:^(BOOL success, NSDictionary *data) {

    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }           
}];
//Object movie with only the modified fields ...
GamedoniaUsers.updateUser(profile, false, function(success:Boolean):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
local updateCB = function (succes, data)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

Gamedonia.Users.updateUser (profile, false, updateCB)
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onUpdateProfileResponse(bool success, const TGDUserProfile& profile)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

//profile only contains few of the fields of the full profile to modify
void MyClass::updateUser(const TGDUserProfile& profile)
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::updateUser(profile, false, response, gamedoniaResponseUserProfile_selector(MyCbresponse::onUpdateProfileResponse));
    response->release();
}

Change Password

This will substitute the user's current password with a new one. You just need to send to the server the email of the user who wants to change his password, along with the current password and the new password.

GamedoniaUsers.ChangePassword("my@email.com", "my_current_password", "my_new_password", delegate (bool success) {
	if (success) {
		//TODO Your success processing
	} else {
		//TODO Your fail processing
	}
});
void MyClass::ChangeUserPassword(CCString* email, CCString* current_password, CCString* new_password) {
    GamedoniaSDKUser::changePassword (email, current_password, new_password, this, gamedoniaResponse_selector(MyClass::PaswordChangeCallback));
}

void MyClass::PaswordChangeCallback(bool success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
[[Gamedonia users] changePassword:@"my@email.com"
                  currentPassword:@"my_current_password"
                  newPassword:@"my_new_password"
                  callback:^(BOOL success) {

    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }           
}];
GamedoniaUsers.changePassword("my@email.com", "my_current_password", "my_new_password", function(success:Boolean):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
local changePasswordCB = function (succes)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

Gamedonia.Users.changePassword ("my@email.com", "my_current_password", "my_new_password", changePasswordCB)
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onChangePasswordResponse(bool success)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

void MyClass::changePassword(const std::string& email, const std::string& old_password, const std::string& new_password)
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::changePassword(email, old_password, new_password, response, gamedoniaResponseLogin_selector(MyCbresponse::onChangePasswordResponse));
    response->release();
}

Restore Password

These methods apply only for users with mail credentials. There are two ways to restore a user's password.

One is resetting a user password in a two step process. First, comunicate Gamedonia servers that a user needs a new password by sending the user's email. Second, a link is emailed to that user account. Clicking on the link will redirect the user to a webpage where he/she can insert a new password.

Another way to create a new password is by sending the restore token ( provided in an email sent to the user) and the new password with an API call. Here you can see one example for each method.

// First. Send the reset request for an email.
GamedoniaUsers.ResetPassword("my@email.com", delegate (bool success) {
	if (success) {
		//TODO Your success processing
	} else {
		//TODO Your fail processing
	}
});
		
// Second. Send the provided restore token along with the new password.
GamedoniaUsers.RestorePassword ("The_Restore_Token", "my_new_password", delegate (bool success) {
	if (success) {
		//TODO Your success processing
	} else {
		//TODO Your fail processing
	}
});
// First. Send the reset request for an email.
void MyClass::ResetPassword(CCString* email) {
    GamedoniaSDKUser::resetPassword (email, this, gamedoniaResponse_selector(MyClass::PaswordResetCallback));
}

// Second. Send the provided restore token along with the new password.
void MyClass::RestorePassword(CCString* restore_token, CCString* new_password) {
    GamedoniaSDKUser::restorePassword (restore_token, new_password, this, gamedoniaResponse_selector(MyClass::PasswordRestoreCallback));
}

void MyClass::PaswordResetCallback(bool success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}

void MyClass::PasswordRestoreCallback(bool success) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
// First. Send the reset request for an email.
[[Gamedonia users] resetPassword:@"my@email.com"
                  callback:^(BOOL success) {

    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }           
}];

// Second. Send the provided restore token along with the new password.
[[Gamedonia users] restorePassword:@"The_Restore_Token"
                   newPassword:"my_new_password"
                   callback:^(BOOL success) {

    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }           
}];
// First. Send the reset request for an email.
GamedoniaUsers.resetPassword("my@email.com", function(success:Boolean):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});

// Second. Send the provided restore token along with the new password.
GamedoniaUsers.restorePassword("The_Restore_Token", "my_new_password", function(success:Boolean):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
local resetPasswordCB = function (succes)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

local restorePasswordCB = function (succes)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

-- First. Send the reset request for an email.
Gamedonia.Users.resetPassword ("my@email.com", resetPasswordCB)

-- Second. Send the provided restore token along with the new password.
Gamedonia.Users.restorePassword ("The_Restore_Token", "my_new_password", restorePasswordCB)
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onResetPasswordResponse(bool success)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }

    void onRestorePasswordResponse(bool success)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

// First. Send the reset request for an email.
void MyClass::resetPassword(const std::string& email)
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::resetPassword(email, response, gamedoniaResponseLogin_selector(MyCbresponse::onResetPasswordResponse));
    response->release();
}

// Second. Send the provided restore token along with the new password.
void MyClass::restorePassword(const std::string& restore_token, const std::string& new_password)
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::restorePassword(restore_token, new_password, response, gamedoniaResponseLogin_selector(MyCbresponse::onRestorePasswordResponse));
    response->release();
}

Login Workflow

Logging a user in your game can be done in many ways and the whole process can be designed with different strategies. Here we provide an example of login workflow. These are the steps:

  1. Make a silent authentication. This will identify the user using his device ID, without the user even noticing it or being bothered by pop-ups. This is good for first time users, who at their first try just want to test the game.

  2. Use the Facebook API and retrieve Facebook user credentials.

  3. Link the logged in user (identified by the device) to the user credentials provided by Facebook. This will result in a user with both credentials (Silent and Facebook).

Silent Login

A silent login lets you create a user attached to the device ID so the current user does not have to fill any registration forms. Later on you can link that created user with any Facebook account, or insert an email and password to make the user persistent among devices.

After that, the user will be able to authenticate with any of the provided credentials and still maintain his profile. The piece of code below shows how to achieve that:

GamedoniaUsers.Authenticate(Gamedonia.CredentialsType.SILENT, new Dictionary<string,object>(), delegate (bool success){
	if (success){
		//TODO: The user has been authenticated correctly.
	}
	else {
		//TODO: Process your authentication failure.
	}
});
// Not implemented yet
// Not implemented yet
// Not implemented yet
-- Not implemented yet
// Not implemented yet

User account linkage

Using the call to the LinkUser function, you will be able to link different types of credentials to the same Gamedonia User. This way, a player can use any provided credentials to login and keep the same user profile.

To merge both credentials, you must have a user logged in to Gamedonia and a user token provided by an external service such as the Facebook API. This code snippet provides an example:

Querying Users

Whenever you want to query for specific users (for instance, those with a score higher than a specific number), you will need to call the Search method. Queries are peformed against Gamedonia backend using the standard NoSQL query syntax of our engine database. Gamedonia Backend user storage is based in a NoSQL MongoDB database and you can use its query syntax to perform your searches. You can find documentation related to doing queries using MongoDB syntax here.

All User queries are performed against Users created in your app. The query syntax is expressed in JSON format following the same pattern used to define the entities data. For example:

An empty query {} selects all the users in the game and could be acomplished with:

GamedoniaUsers.Search("{}", delegate (bool success, IList data) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
void MyClass::SearchUsers() {
    GamedoniaSDKUser::search ("{}", this, gamedoniaResponseData_selector(MyClass::UserSearchCallback));
}

void MyClass::UserSearchCallback(bool success, CCArray* users) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
[[Gamedonia users] search:@"{}" callback:^(BOOL success, NSArray *data) {
    if (success) {
        //TODO Your success processing
    } else {
       //TODO Your fail processing
    }
}];
GamedoniaUsers.search("{}", function(success:Boolean, data:Array):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
local searchCB = function (succes, data)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

Gamedonia.Users.search ("{}", searchCB)
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onSearchUsersResponse(bool success, const GDArray& users)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

//profile only contains few of the fields of the full profile to modify
void MyClass::searchUsers()
{
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::search("{}", response, gamedoniaResponseUserData_selector(MyCbresponse::onSearchUsersResponse));
    response->release();
}

A single-clause query selects all documents in a collection where a field has a certain value. In the following example we query to get users whose age is greater than 18.

GamedoniaUsers.Search("{\"profile.age\":{$gt:18}}", delegate (bool success, IList data) { 
    if (success) { 
        //TODO Your success processing 
    } else {
        //TODO Your fail processing 
    }
);
void MyClass::SearchUsers() {
    GamedoniaSDKUser::search ("{\"profile.age\":{$gt:18}}", this, gamedoniaResponseData_selector(MyClass::UsersSearchCallback));
}

void MyClass::UsersSearchCallback(bool success, CCArray* users) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}
[[Gamedonia users] search:@"{\"profile.age\":{$gt:18}}" callback:^(BOOL success, NSArray *data) {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
}];
GamedoniaUsers.search("{\"profile.age\":{$gt:18}}", function(success:Boolean, data:Object):void {
    if (success) {
        //TODO Your success processing
    } else {
        //TODO Your fail processing
    }
});
local searchCB = function (succes, data)
    if success then
        -- TODO Your success processing
    else
        -- TODO Your fail processing
    end
end

Gamedonia.Users.search ("{\"profile.age\":{$gt:18}}", searchCB)
class MyCbresponse : public GamedoniaCallbackHandler
{
public:
    void onSearchUsersResponse(bool success, const GDArray& users)
    {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
};

//profile only contains few of the fields of the full profile to modify
void MyClass::searchUsers()
{
    std::string query("{\"profile.age\":{$gt:18}}");
    MyCbresponse* response = new MyCbresponse();
    GamedoniaUser::search(query, response, gamedoniaResponseUserData_selector(MyCbresponse::onSearchUsersResponse));
    response->release();
}

Operators

To build more complex queries you will need to use query Operators. Let's review what kind of operators can be used to build queries:

Comparison

$ne. Selects the documents where the value of the field is not equal (i.e. !=) to the specified value. This includes documents that do not contain the field.

Syntax: {field: {$ne: value} }

$lt. Selects the documents where the value of the field is less than (i.e. <) the specified value.

Syntax: {field: {$lt: value} }

$lte. Selects the documents where the value of the field is less than or equal to (i.e. <=) the specified value.

Syntax: {field: {$lte: value} }

$gt. Selects those documents where the value of the field is greater than (i.e. >) the specified value.

Syntax: {field: {$gt: value} }

$gte. Selects the documents where the value of the field is greater than or equal to (i.e. >=) a specified value (e.g. value.)

Syntax: {field: {$gte: value} }

$in. Selects the documents where the field value equals any value in the specified array (e.g. <value1>, <value2>, etc.)

Syntax: {field: { $in: [<value1>, <value2>, ... <valueN> ] } }

$nin. Selects the documents where:

Syntax: {field: { $nin: [ <value1>, <value2> ... <valueN> ]} }

  • the field value is not in the specified array or
  • the field does not exist.

$all. Selects the documents where the field holds an array and contains all elements (e.g. <value>, <value1>, etc.) in the array.

Syntax: {field: { $all: [ <value> , <value1> ... ]} }

Logical

$and. Performs a logical AND operation on an array of two or more expressions (e.g. <expression1>, <expression2>, etc.) and selects the documents that satisfy all the expressions in the array. The $and operator uses short-circuit evaluation. If the first expression (e.g. <expression1>) evaluates to false, MongoDB will not evaluate the remaining expressions.

Syntax: {$and: [ { <expression1> }, { <expression2> } , ... , { <expressionN> } ] }

$or. Performs a logical OR operation on an array of two or more <expressions> and selects the documents that satisfy at least one of the <expressions>.

Syntax: {$or: [ { <expression1> }, { <expression2> }, ... , { <expressionN> } ]}

$nor. Performs a logical NOR operation on an array of two or more <expressions> and selects the documents that fail all the <expressions> in the array.

Syntax: {$nor: [ { <expression1> }, { <expression2> }, ... { <expressionN> } ] }

$not. Performs a logical NOT operation on the specified <operator-expression> and selects the documents that do not match the <operator-expression>. This includes documents that do not contain the field.

Syntax: {field: { $not: { <operator-expression> } } }

Element

$exist. Selects the documents that contain the field if <boolean> is true. If <boolean> is false, the query only returns the documents that do not contain the field. Documents that contain the field but has the value null are not returned.

Syntax: {field: { $exists: <boolean> } }

$type. Selects the documents where the value of the field is the specified BSON type. See supported data types here.

Syntax: {field: { $type: <BSON type> }}

$mod. Selects the documents where the field value divided by the divisor has the specified remainder.

Syntax: {field: { $mod: [ divisor, remainder ]} }

    Javascript

    $regexp. Provides regular expression capabilities for pattern matching strings in queries. MongoDB uses Perl compatible regular expressions (i.e. “PCRE.”).

    Syntax: {field: { $regex: <regular-expression>, $options: <options> } }.

    • $options. There are four option flags.
      • i toggles case insensitivity, and allows all letters in the pattern to match upper and lower cases.
      • m toggles multiline regular expression. Without this option, all regular expressions match within one line. If there are no newline characters (e.g. \n) or no start/end of line construct, the m option has no effect.
      • x toggles an “extended” capability. When set, $regex ignores all white space characters unless escaped or included in a character class.
        Additionally, it ignores characters between an un-escaped # character and the next new line, so that you may include comments in complicated patterns. This only applies to data characters; white space characters may never appear within special character sequences in a pattern.
      • s allows the dot (e.g. .) character to match all characters including newline characters.

    Modifiers

    Queries can also optionally include modifiers to limit, skip or sort the retrived results from Gamedonia Backend.

    Limit and Skip

    The most common case of use for these modifiers is the query results pagination. Imagine you have a huge collection of movies and you want to present a paginated table of 20 movies per page. You can achieve that by setting the limit=20 and the skip modifier to skip=20.

    GamedoniaUsers.Search("{}", 20, null, 20, delegate (bool success, IList list){
        if (success){
            //TODO Your success processing
        }
        else {
            //TODO Your fail processing
        }
    });
    void MyClass::SearchUsers() {
        // Search(query, limit, skip, object, delegate_method)
        GamedoniaSDKUser::search ("{}", 20, "", 20, this, gamedoniaResponseData_selector(MyClass::UsersSearchCallback));
    }
    
    void MyClass::UsersSearchCallback(bool success, CCArray* users) {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
    
    [[Gamedonia users] search:@"{}" limit:20 skip:20 callback:^(BOOL success, NSArray *data) {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }];
    
    GamedoniaUsers.search("{}", 20, null, 20, function(success:Boolean, data:Object):void {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    });
    
    local searchCB = function (succes, data)
        if success then
            -- TODO Your success processing
        else
            -- TODO Your fail processing
        end
    end
    
    Gamedonia.Users.search ("{}", searchCB, limit:20, nil, skip:20)
    
    class MyCbresponse : public GamedoniaCallbackHandler
    {
    public:
        void onSearchUsersResponse(bool success, const GDArray& users)
        {
            if (success) {
                //TODO Your success processing
            } else {
                //TODO Your fail processing
            }
        }
    };
    
    //profile only contains few of the fields of the full profile to modify
    void MyClass::searchUsers()
    {
        MyCbresponse* response = new MyCbresponse();
        GamedoniaUser::search("{}", 20, "", 20, response, gamedoniaResponseUserData_selector(MyCbresponse::onSearchUsersResponse));
        response->release();
    }
    

    Sort

    Query results can also be sorted in Ascending or Descending order. You just need to specify the field you want to sort with and choose the sorting direction.

    For example, let's sort our users by age in ascending order.

    GamedoniaUsers.Search("{}", 20, "{profile.age:1}", delegate (bool success, IList list){
        if (success){
            //TODO Your success processing
        }
        else {
            //TODO Your fail processing
        }
    });
    
    void MyClass::SearchUsers() {
        // Search(query, limit, skip, object, delegate_method)
        GamedoniaSDKUser::search ("{}", 20, "{'profile.age':1}", 20, this, gamedoniaResponseData_selector(MyClass::UsersSearchCallback));
    }
    
    void MyClass::UsersSearchCallback(bool success, CCArray* users) {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
    
    [[Gamedonia users] search:@"{}" limit:20 sort:@"{'profile.age':1}" skip:20 callback:^(BOOL success, NSArray *data) {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }];
    
    GamedoniaUsers.search("{}", 20, "{'profile.age':1}", 20, function(success:Boolean, data:Object):void {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    });
    
    local searchCB = function (succes, data)
        if success then
            -- TODO Your success processing
        else
            -- TODO Your fail processing
        end
    end
    
    Gamedonia.Users.search ("{}", searchCB, limit:20, "{'profile.age':1}", skip:20)
    
    class MyCbresponse : public GamedoniaCallbackHandler
    {
    public:
        void onSearchUsersResponse(bool success, const GDArray& users)
        {
            if (success) {
                //TODO Your success processing
            } else {
                //TODO Your fail processing
            }
        }
    };
    
    //profile only contains few of the fields of the full profile to modify
    void MyClass::searchUsers()
    {
        MyCbresponse* response = new MyCbresponse();
        GamedoniaUser::search("{}", 20, "{'profile.age':1}", 20, response, gamedoniaResponseUserData_selector(MyCbresponse::onSearchUsersResponse));
        response->release();
    }
    

    Count Users

    Another type of query we can use is the count function. This will return the number of items found on a given query. We can specify any query we specify for search users, but instead of returning the resulting objects, this will return the number of objects found.

    For example, this piece of code shows how to count the number of registered users aged over 18:

    GamedoniaUsers.Count("{\"profile.age\":{$gt:18}}", delegate (bool success, int count) { 
    	if (success) { 
    		//TODO Your success processing 
    	} else {
    		//TODO Your fail processing 
    	}
    });
    
    void MyClass::CountUsers() {
        GamedoniaSDKUser::count ("{\"profile.age\":{$gt:18}}", this, gamedoniaResponseLong_selector(MyClass::UsersCountCallback));
    }
    
    void MyClass::UsersCountCallback(bool success, long count) {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    }
    
    GamedoniaUsers.count("{\"profile.age\":{$gt:18}}", function(success:Boolean, count:Number):void {
        if (success) {
            //TODO Your success processing
        } else {
            //TODO Your fail processing
        }
    });
    
    local searchCB = function (succes, count)
        if success then
            -- TODO Your success processing
        else
            -- TODO Your fail processing
        end
    end
    
    Gamedonia.Users.count ("{\"profile.age\":{$gt:18}}", searchCB)
    
    class MyCbresponse : public GamedoniaCallbackHandler
    {
    public:
        void onCountUsersResponse(bool success, unsigned long count)
        {
            if (success) {
                //TODO Your success processing
            } else {
                //TODO Your fail processing
            }
        }
    };
    
    //profile only contains few of the fields of the full profile to modify
    void MyClass::searchUsers()
    {
        MyCbresponse* response = new MyCbresponse();
        GamedoniaUser::count("{\"profile.age\":{$gt:18}}", response, gamedoniaResponseUserLong_selector(MyCbresponse::onCountUsersResponse));
        response->release();
    }
    
     

    Checking the connectivity state

    Without a connection to Internet and to the Gamedonia servers you won't be able to use any of the calls we introduced in this section. In order to obtain a better error management you can use the isInternetConnectionAvailable method. It will return true in case you have access to the Gamedonia servers.

    GamedoniaBackend.isInternetConnectionAvailable(delegate (bool success) { 
    	if (success) { 
    		//TODO Your success processing
    	} else {
    		//TODO Your fail processing 
    	}
    });
    

    BSON Data types

    BSON is a binary serialization format used to store documents and make remote procedure calls in MongoDB. This is a list of BSON types and their coreesponding number, which can be used to query docuemnts using the $type operator.

    • Double: 1
    • String: 2
    • Object: 3
    • Array: 4
    • Binary data: 5
    • Object id: 7
    • Boolean: 8
    • Date: 9
    • Null: 10
    • Regular Expression : 11
    • JavaScript: 13
    • Symbol: 14
    • JavaScript (with scope): 15
    • 32-bit integer: 16
    • Timestamp: 17
    • 64-bit integer: 18
    • Min key: 255
    • Max key: 127

    Now you’ve seen how to manage users in Gamedonia, follow up with our Facebook login tutorial. Learn how to add a Facebok login mechanism to your game so you can start connecting to their social media profile.