NAV
C# C++ Objective-C Java JavaScript Cloud Code

Introduction

brainCloud Architecture

What is brainCloud?

brainCloud is a ready-made back-end platform for the development of feature-rich games, apps and things. brainCloud provides the features you need – along with comprehensive tools to support your team during development, testing and user support.

brainCloud consists of:

SDK libraries

There are custom brainCloud libraries for several languages including:

Engine Support

brainCloud supports the most popular gaming engines, including:

BrainCloudWrapper

The BrainCloudWrapper class provides an easier way for developers to handle user authentication when they are getting started with the authentication system. This includes persisting authentication data between application runs.

By using the wrapper authentication methods, the anonymous and profile IDs will be automatically persisted upon successful authentication. When authenticating, any stored anonymous/profile IDs will be sent to the server. This strategy is useful when using Anonymous authentication.

Note - you should initialize the wrapper before using it. It will in turn initialize the brainCloud client for you - don't do both!

AuthenticateAnonymous

BrainCloudWrapper::getInstance()->authenticateAnonymous(this);
BrainCloudWrapper.Instance.AuthenticateAnonymous(SuccessCallback, FailureCallback, cbObject);
BrainCloudWrapper.getInstance().authenticateAnonymous();
[[BrainCloudWrapper getInstance] authenticateAnonymous:successBlock
                                  errorCompletionBlock:failureBlock
                                              cbObject:nil];
brainCloudWrapper.authenticateAnonymous(callback);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "xpCapped": false,
        "experiencePoints": 230,
        "sent_events": [
        ],
        "playerSessionExpiry": 1200,
        "playerName": "Jimmy",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "loginCount": 23,
        "server_time": 1445545791711,
        "experienceLevel": 0,
        "entities": [
        ],
        "incoming_events": [
        ],
        "currency": {
            "gold": {
                "purchased": 0,
                "balance": 0,
                "consumed": 0,
                "awarded": 0
            }
        },
        "statistics": {
            "deaths": 0,
            "kills": 0
        },
        "abTestingId": 78,
        "id": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "sessionId": "bg6qf38p2btl0o825s99385nd1",
        "profileId": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "newUser": "false"
    }
}

Authenticate a user anonymously with brainCloud - used for apps that don't want to bother the user to login, or for users who are sensitive to their privacy.

Service Operation
"authenticate" "AUTHENTICATE"
Error returns
Show Example Error Handling { }
public void FailureCallback(int statusCode, int reasonCode, string statusMessage, object cbObject) {
    switch (reasonCode) {
        case ReasonCodes.MISSING_IDENTITY_ERROR: {  // Identity does not match any profile

            // Reset Profile ID and re-authenticate
            BrainCloudWrapper.Instance.ResetStoredProfileId();
            BrainCloudWrapper.Instance.AuthenticateAnonymous();
            break;
        }
        case ReasonCodes.SWITCHING_PROFILES: {  // Identity belongs to a different profile

            // Reset Profile ID and Anonymous id, and then re-authenticate
            BrainCloudWrapper.Instance.ResetStoredProfileId();
            BrainCloudWrapper.Instance.ResetStoredAnonymousId();
            BrainCloudWrapper.Instance.AuthenticateAnonymous();
            break;
        }
        default: { // Uncaught reasonCode  // Uncaught reasonCode

            // Log the error for debugging later
            // ...
            break;
        }
    }
}
Code Name Description
40206 MISSING_IDENTITY_ERROR Both an anonymousId and profileId were provided for authentication - but the anonymousId doesn't exist on the server. The profileId may or may not exist. It is possible that the user account was deleted via the Design Portal. The proper recourse is to reset the stored profile id, and re-authenticate. [There is no need to delete the anonymousId since it doesn't exist on the server anyway.]
40207 SWITCHING_PROFILES This means that the anonymousId provided does point to a profile, but not the same one that was saved in the client. This fails the anonymous security check. For any other authentication type, this might indicate that the user wants to switch accounts (thus the name of the error constant). For anonymous, the only response is to reset both the stored anonymousId and profileId, and then re-authenticate.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication

AuthenticateUniversal

const char* userId = "Username";
const char* password = "passwrd123";

BrainCloudWrapper::getInstance()->authenticateUniversal(userId, password, true, this);
string userId = "Username";
string password = "passwrd123";

BrainCloudWrapper.Instance.AuthenticateUniversal(userId, password, SuccessCallback, FailureCallback);
String userId = "Username";
String password = "passwrd123";

BrainCloudWrapper.getInstance().authenticateUniversal(userId, password, true, this);
NSString* userId = "UserId";
NSString* password = "password";

[[BrainCloudWrapper getInstance]
  authenticateUniversal:userId
               password:password
            forceCreate:true
        completionBlock:successBlock
   errorCompletionBlock:failureBlock
               cbObject:nil];
userId = "Username";
password = "passwrd123";

brainCloudWrapper.authenticateUniversal(userId, password, true, callback);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "xpCapped": false,
        "experiencePoints": 230,
        "sent_events": [
        ],
        "playerSessionExpiry": 1200,
        "playerName": "Jimmy",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "loginCount": 23,
        "server_time": 1445545791711,
        "experienceLevel": 0,
        "entities": [
        ],
        "incoming_events": [
        ],
        "currency": {
            "gold": {
                "purchased": 0,
                "balance": 0,
                "consumed": 0,
                "awarded": 0
            }
        },
        "statistics": {
            "deaths": 0,
            "kills": 0
        },
        "abTestingId": 78,
        "id": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "sessionId": "bg6qf38p2btl0o825s99385nd1",
        "profileId": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "newUser": "false"
    }
}

Universal authentication allows the developer to pass in any user/password string combination. As with all authentication methods, if the create new profile flag is specified as false, the authentication will fail if the user/password combination does not match a user in the database.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
userId The user's ID.
password The password of the user.
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Show Example Error Handling { }
public void FailureCallback(int statusCode, int reasonCode, string statusMessage, object cbObject) {
    switch (reasonCode) {
        case ReasonCodes.MISSING_IDENTITY_ERROR: {  // Identity does not exist (and client has orphaned profileId)

            // Reset profileId and re-authenticate
            BrainCloudWrapper.Instance.ResetStoredProfileId();
            BrainCloudWrapper.Instance.AuthenticateUniversal(userId, password, true);
            break;
        }
        case ReasonCodes.SWITCHING_PROFILES: {  // Identity belongs to a different profile

            // [Optional] Prompt user to confirm that they wish to switch accounts?

            // Reset profileId and re-authenticate
            BrainCloudWrapper.Instance.ResetStoredProfileId();
            BrainCloudWrapper.Instance.AuthenticateUniversal(userId, password, forceCreate);
            break;
        }
        case ReasonCodes.MISSING_PROFILE_ERROR: {  // Identity does not exist

            // The account doesn't exist - create it now.
            BrainCloudWrapper.Instance.AuthenticateUniversal(userId, password, true);
            break;
        }
        case ReasonCodes.TOKEN_DOES_NOT_MATCH_USER: {  // Wrong password

            // Display a dialog telling the user that the password provided was invalid,
            // and invite them to re-enter the password.
            // ...
            break;
        }
        default: { // Uncaught reasonCode

            // Log the error for debugging later
            // ...
            break;
        }
    }
}
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [and unrelated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials don't match (i.e. incorrect password).

AuthenticateEmailPassword

string email = "someEmail@somedomain.com";
string password = "userPassword";

BrainCloudWrapper.Instance.AuthenticateEmailPassword(
    email, password, true, SuccessCallback, FailureCallback);
const char* email = "someEmail@somedomain.com";
const char* password = "userPassword";

BrainCloudWrapper::getInstance()->authenticateEmailPassword(
    email,
    password,
    true,
    this);
- (void)authenticateEmailPassword:(NSString *)email
                         password:(NSString *)password
                      forceCreate:(BOOL)forceCreate
                  completionBlock:(BCCompletionBlock)completionBlock
             errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                         cbObject:(BCCallbackObject)cbObject;
String email = "someEmail@somedomain.com";
String password = "userPassword";

BrainCloudWrapper.getInstance().authenticateEmailPassword(
    email,
    password,
    true,
    this);
email = "someEmail@somedomain.com";
password = "userPassword";

brainCloudWrapper.authenticateEmailPassword(email, password, true, responseHandler);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "xpCapped": false,
        "experiencePoints": 230,
        "sent_events": [
        ],
        "playerSessionExpiry": 1200,
        "playerName": "Jimmy",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "loginCount": 23,
        "server_time": 1445545791711,
        "experienceLevel": 0,
        "entities": [
        ],
        "incoming_events": [
        ],
        "currency": {
            "gold": {
                "purchased": 0,
                "balance": 0,
                "consumed": 0,
                "awarded": 0
            }
        },
        "statistics": {
            "deaths": 0,
            "kills": 0
        },
        "abTestingId": 78,
        "id": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "sessionId": "bg6qf38p2btl0o825s99385nd1",
        "profileId": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "newUser": "false"
    }
}

Authenticate the user with a custom Email and Password. Note that the client app is responsible for collecting (and storing) the e-mail and potentially password (for convenience) in the client data. For the greatest security, force the user to re-enter their password at each login (or at least give them that option).

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
email The e-mail address of the user
password The password of the user
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Show Example Error Handling { }
public void FailureCallback(int statusCode, int reasonCode, string statusMessage, object cbObject) {
    switch (reasonCode) {
        case ReasonCodes.MISSING_IDENTITY_ERROR: {  // Identity does not exist (and client has orphaned profileId)

            // Reset profileId and re-authenticate
            BrainCloudWrapper.Instance.ResetStoredProfileId();
            BrainCloudWrapper.Instance.AuthenticateUniversal(userId, password, true);
            break;
        }
        case ReasonCodes.SWITCHING_PROFILES: {  // Identity belongs to a different profile

            // [Optional] Prompt user to confirm that they wish to switch accounts?

            // Reset profileId and re-authenticate
            BrainCloudWrapper.Instance.ResetStoredProfileId();
            BrainCloudWrapper.Instance.AuthenticateUniversal(userId, password, forceCreate);
            break;
        }
        case ReasonCodes.MISSING_PROFILE_ERROR: {  // Identity does not exist

            // The account doesn't exist - create it now.
            BrainCloudWrapper.Instance.AuthenticateUniversal(userId, password, true);
            break;
        }
        case ReasonCodes.TOKEN_DOES_NOT_MATCH_USER: {  // Wrong password

            // Display a dialog telling the user that the password provided was invalid,
            // and invite them to re-enter the password.
            // ...
            break;
        }
        default: { // Uncaught reasonCode

            // Log the error for debugging later
            // ...
            break;
        }
    }
}
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [and unrelated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials don't match (i.e. incorrect password).

AuthenticateExternal

string userId = "externalId";
string token = "externalTokenOrPassword";
string externalAuthName = "nameOfExternalAuthService";

BrainCloudWrapper.Instance.AuthenticateExternal(
    userId, token, externalAuthName, true,
    SuccessCallback, FailureCallback);
const char* userId = "externalId";
const char* token = "externalTokenOrPassword";
const char* externalAuthName = "nameOfExternalAuthService";

BrainCloudWrapper::getInstance()->authenticateExternal(
    userId,
    token,
    externalAuthName,
    true,
    this);
- (void)authenticateExternal:(NSString *)userID
         authenticationToken:(NSString *)authToken
  externalAuthenticationName:(NSString *)externalAuthName
                 forceCreate:(BOOL)forceCreate
             completionBlock:(BCCompletionBlock)completionBlock
        errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                    cbObject:(BCCallbackObject)cbObject;
String userId = "externalId";
String token = "externalTokenOrPassword";
String externalAuthName = "nameOfExternalAuthService";

BrainCloudWrapper.getInstance().authenticateExternal(
    userId,
    token,
    externalAuthName,
    true,
    this);
userId = "externalId";
token = "externalTokenOrPassword";
externalAuthName = "nameOfExternalAuthService";

brainCloudWrapper.authenticateExternal(userId, token, externalAuthName, true, responseHandler);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "xpCapped": false,
        "experiencePoints": 230,
        "sent_events": [
        ],
        "playerSessionExpiry": 1200,
        "playerName": "Jimmy",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "loginCount": 23,
        "server_time": 1445545791711,
        "experienceLevel": 0,
        "entities": [
        ],
        "incoming_events": [
        ],
        "currency": {
            "gold": {
                "purchased": 0,
                "balance": 0,
                "consumed": 0,
                "awarded": 0
            }
        },
        "statistics": {
            "deaths": 0,
            "kills": 0
        },
        "abTestingId": 78,
        "id": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "sessionId": "bg6qf38p2btl0o825s99385nd1",
        "profileId": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "newUser": "false"
    }
}

Authenticate the user via cloud code (which in turn validates the supplied credentials against an external system). This allows the developer to extend brainCloud authentication to support other backend authentication systems.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
userId The userId
token The user token (password etc)
externalAuthName The name of the custom authentication type (linked to a cloud script that performs authentication). Configured via the **Design
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials don't match (according to the 3rd party system). May also indicate an issue with the external authentication script.

AuthenticateFacebook

string facebookId = "userFacebookId";
string token = "tokenFromFacebook";

BrainCloudWrapper.Instance.AuthenticateFacebook(
    facebookId, token, true, SuccessCallback, FailureCallback);
const char* facebookId = "userFacebookId";
const char* token = "tokenFromFacebook";

BrainCloudWrapper::getInstance()->authenticateFacebook(
    userId,
    token,
    true,
    this);
- (void)authenticateFacebook:(NSString *)externalID
         authenticationToken:(NSString *)authToken
                 forceCreate:(BOOL)forceCreate
             completionBlock:(BCCompletionBlock)completionBlock
        errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                    cbObject:(BCCallbackObject)cbObject;
public void authenticateFacebook(String fbUserId, String fbAuthToken, boolean forceCreate, IAuthenticationServiceCallback callback)
facebookId = "userFacebookId";
token = "tokenFromFacebook";

brainCloudWrapper.authenticateFacebook(facebookId, token, true, responseHandler);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "xpCapped": false,
        "experiencePoints": 230,
        "sent_events": [
        ],
        "playerSessionExpiry": 1200,
        "playerName": "Jimmy",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "loginCount": 23,
        "server_time": 1445545791711,
        "experienceLevel": 0,
        "entities": [
        ],
        "incoming_events": [
        ],
        "currency": {
            "gold": {
                "purchased": 0,
                "balance": 0,
                "consumed": 0,
                "awarded": 0
            }
        },
        "statistics": {
            "deaths": 0,
            "kills": 0
        },
        "abTestingId": 78,
        "id": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "sessionId": "bg6qf38p2btl0o825s99385nd1",
        "profileId": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "newUser": "false"
    }
}

Authenticate the user with brainCloud using their Facebook Credentials.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
userId The userId
facebookId The Facebook ID of the user
facebookToken The validated token from the Facebook SDK
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials are invalid (i.e. bad Facebook id / token). May also indicate that Facebook integration is not properly configured.

AuthenticateGameCenter

string gameCenterId = "userGameCenterId";

BrainCloudWrapper.Instance.AuthenticateGameCenter(
    gameCenterId, true, SuccessCallback, FailureCallback);
const char* gameCenterId = "userGameCenterId";

BrainCloudWrapper::getInstance()->authenticateGameCenter(
    gameCenterId,
    true,
    this);
- (void)authenticateGameCenter:(NSString *)gameCenterID
                   forceCreate:(BOOL)forceCreate
               completionBlock:(BCCompletionBlock)completionBlock
          errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                      cbObject:(BCCallbackObject)cbObject;
// N/A
gameCenterId = "userGameCenterId";

brainCloudWrapper.authenticateGameCenter(gameCenterId, true, responseHandler);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "xpCapped": false,
        "experiencePoints": 230,
        "sent_events": [
        ],
        "playerSessionExpiry": 1200,
        "playerName": "Jimmy",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "loginCount": 23,
        "server_time": 1445545791711,
        "experienceLevel": 0,
        "entities": [
        ],
        "incoming_events": [
        ],
        "currency": {
            "gold": {
                "purchased": 0,
                "balance": 0,
                "consumed": 0,
                "awarded": 0
            }
        },
        "statistics": {
            "deaths": 0,
            "kills": 0
        },
        "abTestingId": 78,
        "id": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "sessionId": "bg6qf38p2btl0o825s99385nd1",
        "profileId": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "newUser": "false"
    }
}

Authenticate the user using their Game Center ID.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
gameCenterId The player's game center ID (use the playerID property from the local GKPlayer object)
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the design portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials are invalid (i.e. bad gameCenterId)

AuthenticateGoogle

string googleId = "myUser@gmail.com";
string token = "authTokenFromGoogle";

BrainCloudWrapper.Instance.AuthenticateGoogle(
    googleId, token, true, SuccessCallback, FailureCallback);
const char* googleId = "myUser@gmail.com";
const char* token = "authTokenFromGoogle";

BrainCloudWrapper::getInstance()->authenticateGoogle(
    googleId, token, true, this);
- (void)authenticateGoogle:(NSString *)userID
                     token:(NSString *)token
               forceCreate:(BOOL)forceCreate
           completionBlock:(BCCompletionBlock)completionBlock
      errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                  cbObject:(BCCallbackObject)cbObject;
String googleId = "myUser@gmail.com";
String token = "authTokenFromGoogle";

BrainCloudWrapper.getInstance().authenticateGoogle(
    googleId, token, true, this);
googleId = "myUser@gmail.com";
token = "authTokenFromGoogle";

brainCloudWrapper.authenticateGoogle(googleId, token, true, responseHandler);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "xpCapped": false,
        "experiencePoints": 230,
        "sent_events": [
        ],
        "playerSessionExpiry": 1200,
        "playerName": "Jimmy",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "loginCount": 23,
        "server_time": 1445545791711,
        "experienceLevel": 0,
        "entities": [
        ],
        "incoming_events": [
        ],
        "currency": {
            "gold": {
                "purchased": 0,
                "balance": 0,
                "consumed": 0,
                "awarded": 0
            }
        },
        "statistics": {
            "deaths": 0,
            "kills": 0
        },
        "abTestingId": 78,
        "id": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "sessionId": "bg6qf38p2btl0o825s99385nd1",
        "profileId": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "newUser": "false"
    }
}

Authenticate the user using a google user ID (email address) and google authentication token.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
googleId String representation of google+ userid (email)
googleToken The authentication token derived via the google apis.
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials are invalid (i.e. googleId and googleToken are invalid). May also indicate that Google Integration is not properly configured.

AuthenticateSteam

string steamId = "userSteamId";
string ticket = "sessionTicketFromSteam";

BrainCloudWrapper.Instance.AuthenticateSteam(
    steamId, ticket, true, SuccessCallback, FailureCallback);
const char* steamId = "userSteamId";
const char* ticket = "sessionTicketFromSteam";

BrainCloudWrapper::getInstance()->authenticateSteam(
    steamId, token, true, this);
- (void)authenticateSteam:(NSString *)userID
            sessionTicket:(NSString *)sessionticket
              forceCreate:(BOOL)forceCreate
          completionBlock:(BCCompletionBlock)completionBlock
     errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                 cbObject:(BCCallbackObject)cbObject;
Steam steamId = "userSteamId";
Steam ticket = "sessionTicketFromSteam";

BrainCloudWrapper.getInstance().authenticateSteam(
    steamId, token, true, this);
steamId = "userSteamId";
ticket = "sessionTicketFromSteam";

brainCloudWrapper.authenticateSteam(steamId, ticket, true, responseHandler);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "xpCapped": false,
        "experiencePoints": 230,
        "sent_events": [
        ],
        "playerSessionExpiry": 1200,
        "playerName": "Jimmy",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "loginCount": 23,
        "server_time": 1445545791711,
        "experienceLevel": 0,
        "entities": [
        ],
        "incoming_events": [
        ],
        "currency": {
            "gold": {
                "purchased": 0,
                "balance": 0,
                "consumed": 0,
                "awarded": 0
            }
        },
        "statistics": {
            "deaths": 0,
            "kills": 0
        },
        "abTestingId": 78,
        "id": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "sessionId": "bg6qf38p2btl0o825s99385nd1",
        "profileId": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "newUser": "false"
    }
}

Authenticate the user using a steam userId and session ticket (without any validation on the userId).

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
userId String representation of 64 bit steam ID
sessionTicket The session ticket of the user (hex encoded)
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials are invalid (i.e. bad Steam userId and/or sessionTicket). May also indicate that Steam Integration is not properly configured.

AuthenticateTwitter

string twitterId = "userTwitterId";
string token = "userAuthToken";
string secret = "secretFromTwitterApi";

BrainCloudWrapper.Instance.AuthenticateTwitter(
    twitterId, token, secret, true, SuccessCallback, FailureCallback);
const char* twitterId = "userTwitterId";
const char* token = "userAuthToken";
const char* secret = "secretFromTwitterApi";

BrainCloudWrapper::getInstance()->authenticateTwitter(
    twitterId, token, secret, true, this);
- (void)authenticateTwitter:(NSString *)userID
                      token:(NSString *)token
                     secret:(NSString *)secret
                forceCreate:(BOOL)forceCreate
            completionBlock:(BCCompletionBlock)cb
       errorCompletionBlock:(BCErrorCompletionBlock)ecb
                   cbObject:(BCCallbackObject)cbObject;
String twitterId = "userTwitterId";
String token = "userAuthToken";
String secret = "secretFromTwitterApi";

BrainCloudWrapper.getInstance().authenticateTwitter(
    twitterId, token, secret, true, this);
twitterId = "userTwitterId";
token = "userAuthToken";
secret = "secretFromTwitterApi";

brainCloudWrapper.authenticateTwitter(twitterId, token, secret, true, responseHandler);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "xpCapped": false,
        "experiencePoints": 230,
        "sent_events": [
        ],
        "playerSessionExpiry": 1200,
        "playerName": "Jimmy",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "loginCount": 23,
        "server_time": 1445545791711,
        "experienceLevel": 0,
        "entities": [
        ],
        "incoming_events": [
        ],
        "currency": {
            "gold": {
                "purchased": 0,
                "balance": 0,
                "consumed": 0,
                "awarded": 0
            }
        },
        "statistics": {
            "deaths": 0,
            "kills": 0
        },
        "abTestingId": 78,
        "id": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "sessionId": "bg6qf38p2btl0o825s99385nd1",
        "profileId": "47037fc9-ca7b-4f61-a71f-e5a37b0e8a03",
        "newUser": "false"
    }
}

Authenticate the user using a Twitter user ID, authentication token, and secret from Twitter.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
userId String representation of Twitter user ID
token The authentication token derived via the Twitter APIs
secret The secret given when attempting to link with Twitter
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials are invalid (i.e. bad Twitter userId / token / secret). May also indicate that Twitter integration is not properly configured.

GetAlwaysAllowProfileSwitch

bool allowSwitch = BrainCloudWrapper::getInstance()->getAlwaysAllowProfileSwitch();
bool allowSwitch = BrainCloudWrapper.Instance.GetAlwaysAllowProfileSwitch();
bool allowSwitch = BrainCloudWrapper.getInstance().getAlwaysAllowProfileSwitch();
BOOL allowSwitch = [BrainCloudWrapper getInstance].alwaysAllowProfileSwitch;
var allowSwitch = brainCloudWrapper.getAlwaysAllowProfileSwitch();

For non-anonymous authentication methods, a profile ID will be passed in when this value is set to false. This will generate an error on the server if the profile ID passed in does not match the profile associated with the authentication credentials.

By default, this value is true.

GetBC

BrainCloudWrapper::getBC();
BrainCloudWrapper.Client; //static property
BrainCloudClient.Get();
[BrainCloudWrapper getBC];
// N/A

Method returns a singleton instance of the BrainCloudClient.

GetInstance

BrainCloudWrapper::getInstance();
BrainCloudWrapper.Instance; //static property
BrainCloudWrapper.getInstance();
[BrainCloudWrapper getInstance];
// N/A

Method returns a singleton instance of the BrainCloudWrapper.

GetStoredAnonymousId

std::string anonymousId = BrainCloudWrapper::getInstance()->getStoredAnonymousId();
string anonymousId = BrainCloudWrapper.Instance.GetStoredAnonymousId();
String id = BrainCloudWrapper.getInstance().getStoredAnonymousId();
NSString* anonymousId = [[BrainCloudWrapper getInstance] getStoredAnonymousId];
var anonymousId = brainCloudWrapper.getStoredAnonymousId();

Returns the stored anonymous ID

GetStoredProfileId

std::string profileId = BrainCloudWrapper::getInstance()->getStoredProfileId();
string profileId = BrainCloudWrapper.Instance.GetStoredProfileId();
String id = BrainCloudWrapper.getInstance().getStoredProfileId();
NSString* profileId = [[BrainCloudWrapper getInstance] getStoredProfileId];
var profileId = brainCloudWrapper.getStoredProfileId();

Returns the stored profile ID

Initialize

const char* serverUrl = "https://sharedprod.braincloudservers.com/dispatcherv2";
const char* secret = "1234-1234-1234-1234";
const char* appId = "123456";

const char* company = "bitHeads";
const char* gameName = "Awesome Game";

BrainCloudWrapper::getInstance()->initialize(serverUrl, secret, appId, "1.0.0", company, gameName);
BrainCloudWrapper.Instance.Initialize();
public void initialize(Context ctx, String gameId, String secretKey, String gameVersion)
NSString* serverUrl = @"https://sharedprod.braincloudservers.com/dispatcherv2";
NSString* secret = @"1234-1234-1234-1234";
NSString* appId = @"123456";
NSString* company = @"bitHeads";
NSString* gameName = @"Awesome Game";

[[BrainCloudWrapper getInstance] initialize:serverUrl
                                  secretKey:secret
                                     gameId:appId
                                gameVersion:version
                                companyName:company
                                   gameName:gameName];
secret = "1234-1234-1234-1234";
appId = "123456";

brainCloudWrapper.initialize(appId, secret, "1.0.0");

Method initializes both BrainCloudWrapper and BrainCloudClient.

The parameters for this method vary by client (for example the Unity client takes none at all, as all data is pulled from the brainCloud editor menu data).

Method Parameters
Parameter Description
serverURL The URL to the brainCloud server
secretKey The secret key for your game
gameId The game ID
gameVersion The game version
companyName Client dependent - The company name used in the keychain for storing anonymous and profile IDs. You are free to pick anything you want.
gameName Client dependent - The game name used in the keychain for storing anonymous and profile IDs. You are free to pick anything you want.

Reconnect

BrainCloudWrapper::getInstance()->reconnect(this);
BrainCloudWrapper.Instance.Reconnect(cabblack, errorCallback, cbObject);
BrainCloudWrapper.getInstance().reconnect(this);
- (void)reconnect:(BCCompletionBlock)cb
 errorCompletionBlock:(BCErrorCompletionBlock)ecb
        cbObject:(BCCallbackObject)cbObject;
brainCloudWrapper.reconnect(callback);
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "experiencePoints": 100,
        "refundCount": 0,
        "playerSessionExpiry": 60,
        "server_time": 1464621990155,
        "experienceLevel": 0,
        "currency": {
            "credits": {
                "purchased": 0,
                "balance": 12211,
                "consumed": 133,
                "awarded": 12344
            }
        },
        "abTestingId": 8,
        "statistics": {
            "gamesWon": 0
        },
        "id": "323e861-b749-4ce4-a57a-175232e21b5d",
        "createdAt": 1459439058035,
        "profileId": "323e861-b749-4ce4-a57a-175232e21b5d",
        "newUser": "false",
        "xpCapped": false,
        "sent_events": [],
        "timeZoneOffset": -5,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "countryCode": "ca",
        "loginCount": 16,
        "emailAddress": "test@email.com",
        "previousLogin": 1464621979514,
        "incoming_events": [],
        "lastLogin": 1464621990118,
        "languageCode": "en",
        "pictureUrl": null,
        "sessionId": "v3grtg3ve0a089pekk8lneuk8k",
        "amountSpent": 0
    }
}

Re-authenticates the user with brainCloud

ResetStoredAnonymousId

BrainCloudWrapper::getInstance()->resetStoredAnonymousId();
BrainCloudWrapper.Instance.ResetStoredAnonymousId();
BrainCloudWrapper.getInstance().resetStoredAnonymousId();
[BrainCloudWrapper getInstance].storedAnonymousId = @"";
brainCloudWrapper.resetStoredAnonymousId();

Resets the anonymous ID to empty string. When the anonymousId is empty a new one will be generated automatically on authentication.

ResetStoredProfileId

BrainCloudWrapper::getInstance()->resetStoredProfileId();
BrainCloudWrapper.Instance.ResetStoredProfileId();
BrainCloudWrapper.getInstance().resetStoredProfileId();
[BrainCloudWrapper getInstance].storedProfileId = @"";
brainCloudWrapper.resetStoredProfileId();

Resets the profile ID to empty string.

RunCallbacks

BrainCloudWrapper::runCallbacks();
// N/A, uses Unity MonoBehavior Update
BrainCloudWrapper.getInstance().runCallbacks();
[BrainCloudWrapper update];
// N/A

Run callbacks, to be called once per frame from your main thread

SetAlwaysAllowProfileSwitch

BrainCloudWrapper::getInstance()->setAlwaysAllowProfileSwitch(true);
BrainCloudWrapper.Instance.SetAlwaysAllowProfileSwitch(true);
BrainCloudWrapper.getInstance().setAlwaysAllowProfileSwitch(true);
[BrainCloudWrapper getInstance].alwaysAllowProfileSwitch = YES;
brainCloudWrapper.setAlwaysAllowProfileSwitch(true);

For non-anonymous authentication methods, a profile ID will be passed in when this value is set to false. This will generate an error on the server if the profile ID passed in does not match the profile associated with the authentication credentials.

By default, this value is true.

Method Parameters
Parameter Description
alwaysAllow Controls whether the profile ID is passed in with non-anonymous authentications.

SetStoredAnonymousId

BrainCloudWrapper::getInstance()->setStoredAnonymousId("1234-1234-1234-1234");
BrainCloudWrapper.Instance.SetStoredAnonymousId("1234-1234-1234-1234");
// N/A
[BrainCloudWrapper getInstance].storedAnonymousId = @"1234-1234-1234-1234";
brainCloudWrapper.setStoredAnonymousId("1234-1234-1234-1234");

Sets the stored anonymous ID

Method Parameters
Parameter Description
anonymousId The anonymous ID to set

SetStoredProfileId

BrainCloudWrapper::getInstance()->setStoredProfileId("1234-1234-1234-1234");
BrainCloudWrapper.Instance.SetStoredProfileId("1234-1234-1234-1234");
BrainCloudWrapper.getInstance().setStoredProfileId("1234-1234-1234-1234");
[BrainCloudWrapper getInstance].storedProfileId = @"1234-1234-1234-1234";
brainCloudWrapper.setStoredProfileId("1234-1234-1234-1234");

Sets the stored profile ID

Method Parameters
Parameter Description
profileId The profile ID to set

Client API

Authentication

This section describes the key methods for implementing basic authentication in your app. These methods are all you'll need if you:

Consult the advanced (Identity) section if/when you want to get even more flexible with authentication (giving users more flexibility to choose their preferred authentication method, merging of profiles, etc.) When implementing brainCloud authentication, there are some key things to keep in mind:

brainCloud uses an anonymous installation ID (commonly referred to as the anonymous ID) to identify individual devices. This ID must be generated for first use, and saved by the client application. brainCloud provides a convenient method for generating the ID – or the developer can generate it themselves. brainCloud also requires the client to keep track of the most recent profile ID. This, together with the anonymous ID, provides additional security and allows brainCloud to better understand user intent during logins/reconnections. If the user has never connected before the profile ID should be null.

If you are using the API Explorer, the list of valid Platform IDs can be found here.

Handy tip: To log a user out of brainCloud, use the Logout method in PlayerState. Note that you don't absolutely need to log users out – their sessions will timeout on the server automatically anyway.

Version Enforcement

brainCloud's authentication mechanisms allow you to enforce minimum client version requirements – forcing users with obsolete versions of your client app to upgrade before continuing within your application. This is especially useful for scenarios where you've fixed critical client errors, made significant changes to the server-side data structures, or generally just want to ensure that your users all have the best possible experience.

The client app version (sometimes referred to as the gameVersion) is sent to the server during authentication. It is a string of format "X.X" or "X.X.X" – for example, "1.0.0". The app version is set via the Client or BrainCloudWrapper Initialize() methods.

The minimum versions that your app supports can be configured on the Core App Info | Platforms page of the design portal.

If the client app is older than the minimum version specified, authenticate will return a result similar to:

{ "status": 400, "reason_code": 40322, "upgradeAppId": "http://itunes.com/apps/myappname", "status_message": "Processing exception (message): Game version 1.0.0 is obsolete." }

Recommended behavior of the client is to pop up a dialog inviting the user to upgrade the client, and then redirect them to the appropriate software update page. Note that an upgrade URL may be data-filled with the minimum version # in the server portal.

Disabled Apps

brainCloud allows you to easily control whether your app is enabled or disabled via the Core App Info | Advanced Settings page of the portal.

If for some reason you do decide to disable your app, you are able to configure a custom JSON object to be returned to apps that attempt to login. This JSON is set via the [Edit Disabled Reason] button on that same portal page.

Once disabled, your provided JSON-data will be returned within an element called disabledReason within the error response. For example: { "reason_code": 40330, "status": 403, "status_message": "Processing exception (bundle): Game is disabled.", "disabledReason": { "message": "Apologies - we will be right back!" }, "severity": "ERROR" }

System Disabled

If for some reason your app is System Disabled by brainCloud operations, your app will receive a disabledReason with two elements: sysDisabled: true and message.

{ "reason_code": 40330, "status": 403, "status_message": "Processing exception (bundle): Game is disabled.", "disabledReason": { "sysDisabled": true, "message": "This app has been system disabled. Please contact support." }, "severity": "ERROR" }

Authentication Methods

Initialization
Authentication
Utility

AuthenticateAnonymous

// if it's a new user
const char* newAnonId = BrainCloudClient::getInstance()->generateGUID();
BrainCloudClient::getInstance()->initializeIdentity(NULL, newAnonId);
BrainCloudClient::getInstance()->getAuthenticationService()->authenticateAnonymous(true, this);

// if it's an existing user
const char* savedProfileId = yourMethodToGetSavedProfileId();
const char* savedAnonId = yourMethodToGetSavedAnonymousId();
BrainCloudClient::getInstance()->initializeIdentity(savedProfileId, savedAnonId);
BrainCloudClient::getInstance()->getAuthenticationService()->authenticateAnonymous(false, this);

// note you can also use the BrainCloudWrapper class
BrainCloudClient.Instance.GetAuthenticationService().AuthenticateAnonymous(true, SuccessCallback, FailureCallback, cbObject);
BrainCloudClient.GetInstance().GetAuthenticationService().AuthenticateAnonymous(true, callback);
[[[BrainCloudClient getInstance] getAuthenticationService] authenticateAnonymous];
brainCloudClient.authentication.authenticateAnonymous = function(forceCreate, callback);
n/a
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "experiencePoints": 100,
        "refundCount": 0,
        "playerSessionExpiry": 60,
        "server_time": 1464621990155,
        "experienceLevel": 0,
        "currency": {
            "credits": {
                "purchased": 0,
                "balance": 12211,
                "consumed": 133,
                "awarded": 12344
            }
        },
        "abTestingId": 8,
        "statistics": {
            "gamesWon": 0
        },
        "id": "323e861-b749-4ce4-a57a-175232e21b5d",
        "createdAt": 1459439058035,
        "profileId": "323e861-b749-4ce4-a57a-175232e21b5d",
        "newUser": "false",
        "xpCapped": false,
        "sent_events": [],
        "timeZoneOffset": -5,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "countryCode": "ca",
        "loginCount": 16,
        "emailAddress": "test@email.com",
        "previousLogin": 1464621979514,
        "incoming_events": [],
        "lastLogin": 1464621990118,
        "languageCode": "en",
        "pictureUrl": null,
        "sessionId": "v3grtg3ve0a089pekk8lneuk8k",
        "amountSpent": 0
    }
}

To authenticate anonymously you must have first called InitializeIdentity. You must supply an anonymous ID if you are creating a brand new profile or if you are logging into an already created profile you need to supply the anonymous ID AND the profile ID of the user.

Once you've logged in successfully make sure to save the anonymous and profile ID for future logins.

You can generate a new anonymous ID using the convenience method GenerateAnonymousId.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
forceCreate If set to true, create a new profile if anonymous ID not found. If set to false and anonymous ID does not exist on the server, return an error.
Show Example Error Handling { }
public void FailureCallback(int statusCode, int reasonCode, string statusMessage, object cbObject) {
    switch (reasonCode) {
        case ReasonCodes.MISSING_IDENTITY_ERROR: { // Anonymous id is invalid

            // Clear the profile id, generate a new Anonymous id, and re-authenticate
            BrainCloudClient.Get().AuthenticationService.ClearSavedProfileID();
            BrainCloudClient.Get().AuthenticationService.AnonymousId =
                BrainCloudClient.Get().AuthenticationService.GenerateAnonymousId();
            BrainCloudClient.Get().AuthenticationService.AuthenticateAnonymous(true, OnSuccess_Authenticate, OnError_AuthenticateAnonymous);
            break;
        }
        case ReasonCodes.MISSING_PROFILE_ERROR: { // Anonymous id doesn't exist in database

            // The account doesn't exist - create it now.
            BrainCloudClient.Get().AuthenticationService.AuthenticateAnonymous(true, OnSuccess_Authenticate, OnError_AuthenticateAnonymous);
            break;
        }
        case ReasonCodes.SWITCHING_PROFILES: {  // Identity belongs to a different profile

            // Clear the profile id, generate a new Anonymous id, and re-authenticate
            BrainCloudClient.Get().AuthenticationService.ClearSavedProfileID();
            BrainCloudClient.Get().AuthenticationService.AnonymousId =
                BrainCloudClient.Get().AuthenticationService.GenerateAnonymousId();
            BrainCloudClient.Get().AuthenticationService.AuthenticateAnonymous(true, OnSuccess_Authenticate, OnError_AuthenticateAnonymous);
            break;
        }
        case ReasonCodes.SECURITY_ERROR: { // Identity is invalid
            // Generate a new Anonymous id, and re-authenticate
            BrainCloudClient.Get().AuthenticationService.AnonymousId =
                BrainCloudClient.Get().AuthenticationService.GenerateAnonymousId();
            BrainCloudClient.Get().AuthenticationService.AuthenticateAnonymous(true, OnSuccess_Authenticate, OnError_AuthenticateAnonymous);
            break;
        }
        case ReasonCodes.MISSING_REQUIRED_PARAMETER: { // Anonymous id cannot be blank
            // Generate an Anonymous id before calling AuthenticateAnonymous
            BrainCloudClient.Get().AuthenticationService.AnonymousId =
                BrainCloudClient.Get().AuthenticationService.GenerateAnonymousId();
            BrainCloudClient.Get().AuthenticationService.AuthenticateAnonymous(true, OnSuccess_Authenticate, OnError_AuthenticateAnonymous);
            break;
        }
        default: { // Uncaught reasonCode
            /**
             * Log the unexpected reasonCode to your own internal logs,
             * to implement needed error handling later
             */
            break;
        }
    }
}
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR Both an anonymousId and profileId were provided for authentication - but the anonymousId doesn't exist on the server. The profileId may or may not exist. It is possible that the user account was deleted via the Design Portal. The proper recourse is to reset the stored profile id, and re-authenticate. [There is no need to delete the anonymousId since it doesn't exist on the server anyway.]
40207 SWITCHING_PROFILES This means that the anonymousId provided does point to a profile, but not the same one that was saved in the client. This fails the anonymous security check. For any other authentication type, this might indicate that the user wants to switch accounts (thus the name of the error constant). For anonymous, the only response is to reset both the stored anonymousId and profileId, and then re-authenticate.
40208 MISSING_PROFILE_ERROR The anonymousId provided is not associated with an existing profile and forceCreate = false. To create an account, retry with forceCreate = true.
40209 SECURITY_ERROR Occurs when attempting to authenticate anonymously to an existing user without providing the matching profile ID
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred on authentication
40358 MISSING_REQUIRED_PARAMETER The provided anonymous ID cannot be null

AuthenticateEmailPassword

string email = "someEmail@somedomain.com";
string password = "userPassword";

BrainCloudClient.Instance.AuthenticationService.AuthenticateEmailPassword(
    email, password, true, SuccessCallback, FailureCallback);
const char* email = "someEmail@somedomain.com";
const char* password = "userPassword";

BrainCloudClient::getInstance()->getAuthenticationService()->authenticateEmailPassword(
    email,
    password,
    true,
    this);
- (void)authenticateEmailPassword:(NSString *)email
                         password:(NSString *)password
                      forceCreate:(BOOL)forceCreate
                  completionBlock:(BCCompletionBlock)completionBlock
             errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                         cbObject:(BCCallbackObject)cbObject;
public void authenticateEmailPassword(String email, String password, boolean forceCreate, IAuthenticationServiceCallback callback)
brainCloudClient.authentication.authenticateEmailPassword = function(email, password, forceCreate, responseHandler)
N/A
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "experiencePoints": 100,
        "refundCount": 0,
        "playerSessionExpiry": 60,
        "server_time": 1464621990155,
        "experienceLevel": 0,
        "currency": {
            "credits": {
                "purchased": 0,
                "balance": 12211,
                "consumed": 133,
                "awarded": 12344
            }
        },
        "abTestingId": 8,
        "statistics": {
            "gamesWon": 0
        },
        "id": "323e861-b749-4ce4-a57a-175232e21b5d",
        "createdAt": 1459439058035,
        "profileId": "323e861-b749-4ce4-a57a-175232e21b5d",
        "newUser": "false",
        "xpCapped": false,
        "sent_events": [],
        "timeZoneOffset": -5,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "countryCode": "ca",
        "loginCount": 16,
        "emailAddress": "test@email.com",
        "previousLogin": 1464621979514,
        "incoming_events": [],
        "lastLogin": 1464621990118,
        "languageCode": "en",
        "pictureUrl": null,
        "sessionId": "v3grtg3ve0a089pekk8lneuk8k",
        "amountSpent": 0
    }
}

Authenticate the user with a custom Email and Password. Note that the client app is responsible for collecting (and storing) the e-mail and potentially password (for convenience) in the client data. For the greatest security, force the user to re-enter their password at each login (or at least give them that option).

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
email The e-mail address of the user
password The password of the user
forceCreate Should a new profile be created for this user if the account does not exist?
Show Example Error Handling { }
public void FailureCallback(int statusCode, int reasonCode, string statusMessage, object cbObject) {
    switch (reasonCode) {
        case ReasonCodes.MISSING_IDENTITY_ERROR: { // Identity does not exist (and client has orphaned profileId)

            // Reset profileId and re-authenticate
            BrainCloudClient.Get().AuthenticationService.ResetStoredProfileId();
            BrainCloudClient.Get().AuthenticationService.AuthenticateEmail(email, password, true);
            break;
        }
        case ReasonCodes.SWITCHING_PROFILES: { // Identity belongs to a different profile

            // Reset profileId and re-authenticate
            BrainCloudClient.Get().AuthenticationService.ResetStoredProfileId();
            BrainCloudClient.Get().AuthenticationService.AuthenticateEmail(email, password, forceCreate);
            break;
        }
        case ReasonCodes.MISSING_PROFILE_ERROR: { // Identity does not exist

            // The account doesn't exist - create it now.
            BrainCloudClient.Get().AuthenticationService.AuthenticateEmail(email, password, true);
            break;
        }
        case ReasonCodes.TOKEN_DOES_NOT_MATCH_USER: { // User auth information is incorrect

            // Display a dialog telling the user that the password provided was invalid,
            // and invite them to re-enter the password.
            // ...
            break;
        }
        default: { // Uncaught reasonCode

            // Log the error for debugging later
            // ...
            break;
        }
    }
}
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Most often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user's password is incorrect.

AuthenticateExternal

string userId = "externalId";
string token = "externalTokenOrPassword";
string externalAuthName = "nameOfExternalAuthService";

BrainCloudClient.Instance.AuthenticationService.AuthenticateExternal(
    userId, token, externalAuthName, true,
    SuccessCallback, FailureCallback);
const char* userId = "externalId";
const char* token = "externalTokenOrPassword";
const char* externalAuthName = "nameOfExternalAuthService";

BrainCloudClient::getInstance()->getAuthenticationService()->authenticateExternal(
    userId,
    token,
    externalAuthName,
    true,
    this);
- (void)authenticateExternal:(NSString *)userID
         authenticationToken:(NSString *)authToken
  externalAuthenticationName:(NSString *)externalAuthName
                 forceCreate:(BOOL)forceCreate
             completionBlock:(BCCompletionBlock)completionBlock
        errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                    cbObject:(BCCallbackObject)cbObject;
public void authenticateExternal(String userId,
    String token,
    String externalAuthName,
    boolean forceCreate,
    IAuthenticationServiceCallback callback)
brainCloudClient.authentication.authenticateExternal = function(userId, token, externalAuthName, forceCreate, responseHandler)
N/A
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "experiencePoints": 100,
        "refundCount": 0,
        "playerSessionExpiry": 60,
        "server_time": 1464621990155,
        "experienceLevel": 0,
        "currency": {
            "credits": {
                "purchased": 0,
                "balance": 12211,
                "consumed": 133,
                "awarded": 12344
            }
        },
        "abTestingId": 8,
        "statistics": {
            "gamesWon": 0
        },
        "id": "323e861-b749-4ce4-a57a-175232e21b5d",
        "createdAt": 1459439058035,
        "profileId": "323e861-b749-4ce4-a57a-175232e21b5d",
        "newUser": "false",
        "xpCapped": false,
        "sent_events": [],
        "timeZoneOffset": -5,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "countryCode": "ca",
        "loginCount": 16,
        "emailAddress": "test@email.com",
        "previousLogin": 1464621979514,
        "incoming_events": [],
        "lastLogin": 1464621990118,
        "languageCode": "en",
        "pictureUrl": null,
        "sessionId": "v3grtg3ve0a089pekk8lneuk8k",
        "amountSpent": 0
    }
}

Authenticate the user via cloud code (which in turn validates the supplied credentials against an external system). This allows the developer to extend brainCloud authentication to support other backend authentication systems.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
userId The userId
token The user token (password etc)
externalAuthName The name of the cloud script to call for external authentication
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials don't match (according to the 3rd party system). May also indicate an issue with the external authentication script.

AuthenticateFacebook

string facebookId = "userFacebookId";
string token = "tokenFromFacebook";

BrainCloudClient.Instance.AuthenticationService.AuthenticateFacebook(
    facebookId, token, true, SuccessCallback, FailureCallback);
const char* facebookId = "userFacebookId";
const char* token = "tokenFromFacebook";

BrainCloudClient::getInstance()->getAuthenticationService()->authenticateFacebook(
    userId,
    token,
    true,
    this);
- (void)authenticateFacebook:(NSString *)externalID
         authenticationToken:(NSString *)authToken
                 forceCreate:(BOOL)forceCreate
             completionBlock:(BCCompletionBlock)completionBlock
        errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                    cbObject:(BCCallbackObject)cbObject;
public void authenticateFacebook(String fbUserId, String fbAuthToken, boolean forceCreate, IAuthenticationServiceCallback callback)
brainCloudClient.authentication.authenticateFacebook = function(facebookId, facebookToken, forceCreate, responseHandler)
N/A
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "experiencePoints": 100,
        "refundCount": 0,
        "playerSessionExpiry": 60,
        "server_time": 1464621990155,
        "experienceLevel": 0,
        "currency": {
            "credits": {
                "purchased": 0,
                "balance": 12211,
                "consumed": 133,
                "awarded": 12344
            }
        },
        "abTestingId": 8,
        "statistics": {
            "gamesWon": 0
        },
        "id": "323e861-b749-4ce4-a57a-175232e21b5d",
        "createdAt": 1459439058035,
        "profileId": "323e861-b749-4ce4-a57a-175232e21b5d",
        "newUser": "false",
        "xpCapped": false,
        "sent_events": [],
        "timeZoneOffset": -5,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "countryCode": "ca",
        "loginCount": 16,
        "emailAddress": "test@email.com",
        "previousLogin": 1464621979514,
        "incoming_events": [],
        "lastLogin": 1464621990118,
        "languageCode": "en",
        "pictureUrl": null,
        "sessionId": "v3grtg3ve0a089pekk8lneuk8k",
        "amountSpent": 0
    }
}

Authenticate the user with brainCloud using their Facebook Credentials.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
userId The userId
facebookId The Facebook ID of the user
facebookToken The validated token from the Facebook SDK
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials are invalid (i.e. bad Facebook id / token). May also indicate that Facebook integration is not properly configured.

AuthenticateGameCenter

string gameCenterId = "userGameCenterId";

BrainCloudClient.Instance.AuthenticationService.AuthenticateGameCenter(
    gameCenterId, true, SuccessCallback, FailureCallback);
const char* gameCenterId = "userGameCenterId";

BrainCloudClient::getInstance()->getAuthenticationService()->authenticateGameCenter(
    gameCenterId,
    true,
    this);
- (void)authenticateGameCenter:(NSString *)gameCenterID
                   forceCreate:(BOOL)forceCreate
               completionBlock:(BCCompletionBlock)completionBlock
          errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                      cbObject:(BCCallbackObject)cbObject;
// N/A
brainCloudClient.authentication.authenticateGameCenter = function(gameCenterId, forceCreate, responseHandler)
N/A
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "experiencePoints": 100,
        "refundCount": 0,
        "playerSessionExpiry": 60,
        "server_time": 1464621990155,
        "experienceLevel": 0,
        "currency": {
            "credits": {
                "purchased": 0,
                "balance": 12211,
                "consumed": 133,
                "awarded": 12344
            }
        },
        "abTestingId": 8,
        "statistics": {
            "gamesWon": 0
        },
        "id": "323e861-b749-4ce4-a57a-175232e21b5d",
        "createdAt": 1459439058035,
        "profileId": "323e861-b749-4ce4-a57a-175232e21b5d",
        "newUser": "false",
        "xpCapped": false,
        "sent_events": [],
        "timeZoneOffset": -5,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "countryCode": "ca",
        "loginCount": 16,
        "emailAddress": "test@email.com",
        "previousLogin": 1464621979514,
        "incoming_events": [],
        "lastLogin": 1464621990118,
        "languageCode": "en",
        "pictureUrl": null,
        "sessionId": "v3grtg3ve0a089pekk8lneuk8k",
        "amountSpent": 0
    }
}

Authenticate the user using their Game Center ID.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
gameCenterId The player's game center ID (use the playerID property from the local GKPlayer object)
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the design portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials are invalid (i.e. bad gameCenterId)

AuthenticateGoogle

string googleId = "myUser@gmail.com";
string token = "authTokenFromGoogle";

BrainCloudClient.Instance.AuthenticationService.AuthenticateGoogle(
    googleId, token, true, SuccessCallback, FailureCallback);
const char* googleId = "myUser@gmail.com";
const char* token = "authTokenFromGoogle";

BrainCloudClient::getInstance()->getAuthenticationService()->authenticateGoogle(
    googleId, token, true, this);
- (void)authenticateGoogle:(NSString *)userID
                     token:(NSString *)token
               forceCreate:(BOOL)forceCreate
           completionBlock:(BCCompletionBlock)completionBlock
      errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                  cbObject:(BCCallbackObject)cbObject;
public void authenticateGoogle(String googleUserId, String googleAuthToken, boolean forceCreate, IAuthenticationServiceCallback callback)
brainCloudClient.authentication.authenticateGoogle = function(googleId, googleToken, forceCreate, responseHandler)
N/A
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "experiencePoints": 100,
        "refundCount": 0,
        "playerSessionExpiry": 60,
        "server_time": 1464621990155,
        "experienceLevel": 0,
        "currency": {
            "credits": {
                "purchased": 0,
                "balance": 12211,
                "consumed": 133,
                "awarded": 12344
            }
        },
        "abTestingId": 8,
        "statistics": {
            "gamesWon": 0
        },
        "id": "323e861-b749-4ce4-a57a-175232e21b5d",
        "createdAt": 1459439058035,
        "profileId": "323e861-b749-4ce4-a57a-175232e21b5d",
        "newUser": "false",
        "xpCapped": false,
        "sent_events": [],
        "timeZoneOffset": -5,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "countryCode": "ca",
        "loginCount": 16,
        "emailAddress": "test@email.com",
        "previousLogin": 1464621979514,
        "incoming_events": [],
        "lastLogin": 1464621990118,
        "languageCode": "en",
        "pictureUrl": null,
        "sessionId": "v3grtg3ve0a089pekk8lneuk8k",
        "amountSpent": 0
    }
}

Authenticate the user using a google user ID (email address) and google authentication token.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
googleId String representation of google+ userid (email)
googleToken The authentication token derived via the google apis.
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials are invalid (i.e. googleId and googleToken are invalid). May also indicate that Google Integration is not properly configured.

AuthenticateParse

string parseId = "someId1234";
string token = "authToken";

BrainCloudClient.Instance.AuthenticationService.AuthenticateParse(
    parseId, token, true, SuccessCallback, FailureCallback);
const char* parseId = "someId1234";
const char* token = "authToken";

BrainCloudClient::getInstance()->getAuthenticationService()->authenticateParse(
    parseId, token, true, this);
- (void)authenticateParse:(NSString *)userID
                     token:(NSString *)token
               forceCreate:(BOOL)forceCreate
           completionBlock:(BCCompletionBlock)completionBlock
      errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                  cbObject:(BCCallbackObject)cbObject;
public void authenticateParse(String parseUserId, String parseAuthToken, boolean forceCreate, IAuthenticationServiceCallback callback)
brainCloudClient.authentication.authenticateParse = function(parseId, parseToken, forceCreate, responseHandler)
N/A
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "experiencePoints": 100,
        "refundCount": 0,
        "playerSessionExpiry": 60,
        "server_time": 1464621990155,
        "experienceLevel": 0,
        "currency": {
            "credits": {
                "purchased": 0,
                "balance": 12211,
                "consumed": 133,
                "awarded": 12344
            }
        },
        "abTestingId": 8,
        "statistics": {
            "gamesWon": 0
        },
        "id": "323e861-b749-4ce4-a57a-175232e21b5d",
        "createdAt": 1459439058035,
        "profileId": "323e861-b749-4ce4-a57a-175232e21b5d",
        "newUser": "false",
        "xpCapped": false,
        "sent_events": [],
        "timeZoneOffset": -5,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "countryCode": "ca",
        "loginCount": 16,
        "emailAddress": "test@email.com",
        "previousLogin": 1464621979514,
        "incoming_events": [],
        "lastLogin": 1464621990118,
        "languageCode": "en",
        "pictureUrl": null,
        "sessionId": "v3grtg3ve0a089pekk8lneuk8k",
        "amountSpent": 0
    }
}

Authenticate the user using a Parse user ID and authentication token.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
parseId String representation of Parse user ID
parseToken The authentication token from Parse
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials are invalid (i.e. parseId and parseToken are invalid). May also indicate that Parse Integration is not properly configured.

AuthenticateSteam

string steamId = "userSteamId";
string ticket = "sessionTicketFromSteam";

BrainCloudClient.Instance.AuthenticationService.AuthenticateSteam(
    steamId, ticket, true, SuccessCallback, FailureCallback);
const char* steamId = "userSteamId";
const char* ticket = "sessionTicketFromSteam";

BrainCloudClient::getInstance()->getAuthenticationService()->authenticateSteam(
    steamId, token, true, this);
- (void)authenticateSteam:(NSString *)userID
            sessionTicket:(NSString *)sessionticket
              forceCreate:(BOOL)forceCreate
          completionBlock:(BCCompletionBlock)completionBlock
     errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                 cbObject:(BCCallbackObject)cbObject;
public void authenticateSteam(String steamUserId, String steamSessionTicket, boolean forceCreate, IAuthenticationServiceCallback callback)
brainCloudClient.authentication.authenticateSteam = function(userId, sessionTicket, forceCreate, responseHandler)
N/A
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "experiencePoints": 100,
        "refundCount": 0,
        "playerSessionExpiry": 60,
        "server_time": 1464621990155,
        "experienceLevel": 0,
        "currency": {
            "credits": {
                "purchased": 0,
                "balance": 12211,
                "consumed": 133,
                "awarded": 12344
            }
        },
        "abTestingId": 8,
        "statistics": {
            "gamesWon": 0
        },
        "id": "323e861-b749-4ce4-a57a-175232e21b5d",
        "createdAt": 1459439058035,
        "profileId": "323e861-b749-4ce4-a57a-175232e21b5d",
        "newUser": "false",
        "xpCapped": false,
        "sent_events": [],
        "timeZoneOffset": -5,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "countryCode": "ca",
        "loginCount": 16,
        "emailAddress": "test@email.com",
        "previousLogin": 1464621979514,
        "incoming_events": [],
        "lastLogin": 1464621990118,
        "languageCode": "en",
        "pictureUrl": null,
        "sessionId": "v3grtg3ve0a089pekk8lneuk8k",
        "amountSpent": 0
    }
}

Authenticate the user using a steam userId and session ticket (without any validation on the userId).

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
userId String representation of 64 bit steam ID
sessionTicket The session ticket of the user (hex encoded)
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials are invalid (i.e. bad Steam userId and/or sessionTicket). May also indicate that Steam Integration is not properly configured.

AuthenticateTwitter

string twitterId = "userTwitterId";
string token = "userAuthToken";
string secret = "secretFromTwitterApi";

BrainCloudClient.Instance.AuthenticationService.AuthenticateTwitter(
    twitterId, token, secret, true, SuccessCallback, FailureCallback);
const char* twitterId = "userTwitterId";
const char* token = "userAuthToken";
const char* secret = "secretFromTwitterApi";

BrainCloudClient::getInstance()->getAuthenticationService()->authenticateTwitter(
    twitterId, token, secret, true, this);
- (void)authenticateTwitter:(NSString *)userID
                      token:(NSString *)token
                     secret:(NSString *)secret
                forceCreate:(BOOL)forceCreate
            completionBlock:(BCCompletionBlock)cb
       errorCompletionBlock:(BCErrorCompletionBlock)ecb
                   cbObject:(BCCallbackObject)cbObject;
public void authenticateTwitter(String userId,
                                String token,
                                String secret,
                                boolean forceCreate,
                                IAuthenticationServiceCallback callback)
brainCloudClient.authentication.authenticateTwitter = function(userId, token, secret, forceCreate, responseHandler)
N/A
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "experiencePoints": 100,
        "refundCount": 0,
        "playerSessionExpiry": 60,
        "server_time": 1464621990155,
        "experienceLevel": 0,
        "currency": {
            "credits": {
                "purchased": 0,
                "balance": 12211,
                "consumed": 133,
                "awarded": 12344
            }
        },
        "abTestingId": 8,
        "statistics": {
            "gamesWon": 0
        },
        "id": "323e861-b749-4ce4-a57a-175232e21b5d",
        "createdAt": 1459439058035,
        "profileId": "323e861-b749-4ce4-a57a-175232e21b5d",
        "newUser": "false",
        "xpCapped": false,
        "sent_events": [],
        "timeZoneOffset": -5,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "countryCode": "ca",
        "loginCount": 16,
        "emailAddress": "test@email.com",
        "previousLogin": 1464621979514,
        "incoming_events": [],
        "lastLogin": 1464621990118,
        "languageCode": "en",
        "pictureUrl": null,
        "sessionId": "v3grtg3ve0a089pekk8lneuk8k",
        "amountSpent": 0
    }
}

Authenticate the user using a Twitter user ID, authentication token, and secret from Twitter.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
userId String representation of Twitter user ID
token The authentication token derived via the Twitter APIs
secret The secret given when attempting to link with Twitter
forceCreate Should a new profile be created for this user if the account does not exist?
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [but un-associated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the provided profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials are invalid (i.e. bad Twitter userId / token / secret). May also indicate that Twitter integration is not properly configured.

AuthenticateUniversal

const char* userId = "Username";
const char* password = "passwrd123";

if (newUser)
{
    BrainCloudClient::getInstance()->getAuthenticationService()->authenticateUniversal(userId, password, true, callback);
}
else
{
    BrainCloudClient::getInstance()->getAuthenticationService()->authenticateAnonymous(userId, password, false, callback);
}

// note you can also use the BrainCloudWrapper class
BrainCloudClient.Instance.AuthenticationService.AuthenticateUniversal(userId, password, SuccessCallback, FailureCallback);
BrainCloudClient.GetInstance().GetAuthenticationService().AuthenticateUniversal(userId, password, SuccessCallback, FailureCallback, cbObject);
NSString* userId = "UserId";
NSString* password = "password";

[[m_client authenticationService]
    authenticateUniversal:userId
                 password:password
              forceCreate:true
          completionBlock:successBlock
     errorCompletionBlock:failureBlock
                 cbObject:nil];
brainCloudAuthentication = function(callback)
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "experiencePoints": 100,
        "refundCount": 0,
        "playerSessionExpiry": 60,
        "server_time": 1464621990155,
        "experienceLevel": 0,
        "currency": {
            "credits": {
                "purchased": 0,
                "balance": 12211,
                "consumed": 133,
                "awarded": 12344
            }
        },
        "abTestingId": 8,
        "statistics": {
            "gamesWon": 0
        },
        "id": "323e861-b749-4ce4-a57a-175232e21b5d",
        "createdAt": 1459439058035,
        "profileId": "323e861-b749-4ce4-a57a-175232e21b5d",
        "newUser": "false",
        "xpCapped": false,
        "sent_events": [],
        "timeZoneOffset": -5,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "rewards": {
            "rewardDetails": {},
            "rewards": {},
            "currency": {}
        },
        "countryCode": "ca",
        "loginCount": 16,
        "emailAddress": "test@email.com",
        "previousLogin": 1464621979514,
        "incoming_events": [],
        "lastLogin": 1464621990118,
        "languageCode": "en",
        "pictureUrl": null,
        "sessionId": "v3grtg3ve0a089pekk8lneuk8k",
        "amountSpent": 0
    }
}

Universal authentication allows the developer to pass in any user/password string combination. As with all authentication methods, if the create new profile flag is specified as false, the authentication will fail if the user/password combination does not match a user in the database.

Service Operation
"authenticate" "AUTHENTICATE"
Method Parameters
Parameter Description
userId The user's ID.
password The password of the user.
forceCreate If set to true, create a new profile if userId not found. If set to false and anonymous ID does not exist on the server, return an error.
Show Example Error Handling { }
public void FailureCallback(int statusCode, int reasonCode, string statusMessage, object cbObject) {
    switch (reasonCode) {
        case ReasonCodes.MISSING_IDENTITY_ERROR: { // Identity does not exist (and client has orphaned profileId)

            // Reset profileId and re-authenticate
            BrainCloudClient.Get().AuthenticationService.ResetStoredProfileId();
            BrainCloudClient.Get().AuthenticationService.AuthenticateUniversal(userId, password, true);
            break;
        }
        case ReasonCodes.SWITCHING_PROFILES: { // Identity belongs to a different profile

            // [Optional] Prompt user to confirm that they wish to switch accounts?

            // Reset profileId and re-authenticate
            BrainCloudClient.Get().AuthenticationService.ResetStoredProfileId();
            BrainCloudClient.Get().AuthenticationService.AuthenticateUniversal(userId, password, forceCreate);
            break;
        }
        case ReasonCodes.MISSING_PROFILE_ERROR: { // Identity does not exist

            // The account doesn't exist - create it now.
            BrainCloudClient.Get().AuthenticationService.AuthenticateUniversal(userId, password, true);
            break;
        }
        case ReasonCodes.TOKEN_DOES_NOT_MATCH_USER: { // Wrong password

            // Display a dialog telling the user that the password provided was invalid,
            // and invite them to re-enter the password.
            // ...
            break;
        }
        default: { // Uncaught reasonCode

            // Log the error for debugging later
            // ...
            break;
        }
    }
}
Error returns
Code Name Description
40206 MISSING_IDENTITY_ERROR The identity does not exist on the server and forceCreate was false [and a profileId was provided - otherwise 40208 would have been returned]. Will also occur when forceCreate is true and a saved [and unrelated] profileId is provided. The error handler should reset the stored profile id (if there is one) and re-authenticate, setting forceCreate to true to create a new account. A common cause of this error is deleting the user's account via the Design Portal.
40207 SWITCHING_PROFILES Indicates that the identity credentials are valid, and the saved profileId is valid, but the identity is not associated with the profileId. This may indicate that the user wants to switch accounts in the app. Often an app will pop-up a dialog confirming that the user wants to switch accounts, and then reset the stored profileId and call authenticate again.
40208 MISSING_PROFILE_ERROR Returned when the identity cannot be located, no profileId is provided, and forceCreate is false. The normal response is to call Authenticate again with forceCreate set to true.
40217 UNKNOWN_AUTH_ERROR An unknown error has occurred during authentication.
40307 TOKEN_DOES_NOT_MATCH_USER The user credentials don't match (i.e. incorrect password).

ClearSavedProfileId

BrainCloudClient.Instance.AuthenticationService.ClearSavedProfileID();
BrainCloudClient::getInstance()->getAuthenticationService()->clearSavedProfileID();
- (void)clearSavedProfile;
public void clearSavedProfileId();
brainCloudClient.authentication.clearSavedProfileId();
N/A

Used to clear the saved profile ID - to use in cases when the user is attempting to switch to a different game profile.

GenerateAnonymousId

string anonId = BrainCloudClient.Instance.AuthenticationService.GenerateAnonymousId();
std::string anonId = BrainCloudClient::getInstance()->getAuthenticationService()->generateAnonymousId();
- (NSString *)generateAnonymousId;
String anonId = BrainCloudClient.getInstance().getAuthenticationService().generateAnonymousId();
var anonId = brainCloudClient.authentication.generateAnonymousId();
N/A

Generates a GUID for use as an anonymous installation ID for brainCloud. Normally only called once when the application starts for the first time.

The generated ID is used in conjunction with InitializeIdentity in the BrainCloudClient.

Initialize

BrainCloudClient.Instance.AuthenticationService.Initialize("profileId", "anonId");
BrainCloudClient::getInstance()->getAuthenticationService()->initialize("profileId", "anonId");
- (void)initialize:(NSString *)profileID anonymousID:(NSString *)anonymousID;
public void initialize(String profileId, String anonymousId);
brainCloudClient.authentication.initialize(profileId, anonymousId);
N/A

Initializes the authentication service with an anonymous installation ID and most recently used profile ID. You will need to call this method before authenticating anonymously.

Note that calling this is the same as calling InitializeIdentity in the BrainCloudClient.

Method Parameters
Parameter Description
profileId The ID of the profile ID that was most recently used by the app (on this device)
anonymousId The anonymous installation ID that was generated for this device

ResetEmailPassword

string email = "userEmail@somedomain.com";

BrainCloudClient.Instance.AuthenticationService.ResetEmailPassword(
    email, ApiSuccess, ApiError)
const char* email = "userEmail@somedomain.com";

BrainCloudClient::getInstance()->getAuthenticationService()->resetEmailPassword(email, this);
- (void)resetEmailPassword:(NSString *)email
       withCompletionBlock:(BCCompletionBlock)completionBlock
      errorCompletionBlock:(BCErrorCompletionBlock)errorCompletionBlock
                  cbObject:(BCCallbackObject)cbObject;
public void resetEmailPassword(String email, IAuthenticationServiceCallback callback)
brainCloudClient.authentication.resetEmailPassword = function(email, responseHandler)
N/A
Show Example JSON Return
{
    "status": 200,
    "data": null
}

Sends a password reset email to the specified address.

Service Operation
"authenticate" "RESET_EMAIL_PASSWORD"
Method Parameters
Parameter Description
email The email address to send the reset email to.

Async Match

Many mobile games today feature a type of multi-player game capability known as asynchronous or turn-based gaming. This is where player #1 would take a turn, then player #2 is notified that it is their turn (via push notification). Player #2 would then take their turn and player #1 is then notified it is again their turn and so on until the game is completed (think of playing a game of chess via mail).

This page describes the design used to facilitate this type of multi-player game within brainCloud.

Match Lifecycle

An Async Match can exist in four states that define where it is in its lifecycle. Certain operations are only supported in specific states.

The current state is returned in the "status" field of the match data.

NOT_STARTED

A match has been created but has not had any turns submitted. A match in this state cannot be completed (status set to COMPLETE).

PENDING

The match has had at least one turn submitted.

COMPLETE

A match that has been explicitly completed via the CompleteMatch API. A match cannot be completed if its current status is NOT_STARTED.

EXPIRED

A match that has been explicitly abandoned via the AbandonMatch API. A match cannot be abandoned if its current status is COMPLETE.

Data Model

The following diagram illustrates the data model implemented in brainCloud to support this feature:

Async Match Data Model

Match Entity

The Match entity represents a single asynchronous match between two or more players (for example a single game of chess or tic-tac-toe).

MatchHistory Entity

The MatchHistory entity represents the turn-by-turn history of the state related to a particular match.

Player Entity

The Player entity represents the actual player. We are simply using the "lastLogin" attribute to identify those Player's that have been pre-created by the AsyncMatchService (by checking if the "lastLogin" field is NULL).

Summary

Match Management
Turns
Match Data

AbandonMatch

const char* ownerProfileId = "1234-1234-1234-1234";
const char* matchId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getAsyncMatchService()->abandonMatch(
    ownerProfileId,
    matchId,
    this);
string ownerProfileId = "1234-1234-1234-1234";
string matchId = "1234-1234-1234-1234";

BrainCloudClient.Instance.AsyncMatchService.AbandonMatch(
    ownerProfileId,
    matchId,
    ApiSuccess, ApiError);
public void abandonMatch(String in_ownerId, String in_matchId, IServerCallback callback)
- (void)abandonMatch:(NSString *)ownerId
             matchId:(NSString *)matchId
     completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
            cbObject:(BCCallbackObject)cbObject;
brainCloudClient.asyncMatch.abandonMatch = function(ownerId, matchId, callback)
var ownerId = "1234-1234-1234-1234";
var matchId = "1234-1234-1234-1234";

var asyncMatchProxy = bridge.getAsyncMatchServiceProxy();
var retVal = asyncMatchProxy.abandonMatch(ownerId, matchId);
Show Example JSON Return
{
    "status": 200,
    "data": null
}

Marks the given match as abandoned and sets the matchState to EXPIRED.

Service Operation
"asyncMatch" "ABANDON"
Method Parameters
Parameter Description
ownerId Match owner identifier
matchId Match identifier

CompleteMatch

const char* ownerProfileId = "1234-1234-1234-1234";
const char* matchId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getAsyncMatchService()->completeMatch(
    ownerProfileId,
    matchId,
    this);
string ownerProfileId = "1234-1234-1234-1234";
string matchId = "1234-1234-1234-1234";

BrainCloudClient.Instance.AsyncMatchService.CompleteMatch(
    ownerProfileId,
    matchId,
    ApiSuccess, ApiError);
public void completeMatch(String in_ownerId, String in_matchId, IServerCallback callback)
- (void)completeMatch:(NSString *)ownerId
              matchId:(NSString *)matchId
      completionBlock:(BCCompletionBlock)cb
 errorCompletionBlock:(BCErrorCompletionBlock)ecb
             cbObject:(BCCallbackObject)cbObject;
brainCloudClient.asyncMatch.completeMatch = function(ownerId, matchId, callback)
var ownerId = "1234-1234-1234-1234";
var matchId = "1234-1234-1234-1234";

var asyncMatchProxy = bridge.getAsyncMatchServiceProxy();
var retVal = asyncMatchProxy.completeMatch(ownerId, matchId);
Show Example JSON Return
{
    "status": 200,
    "data": null
}

Marks the given match as complete.

Service Operation
"asyncMatch" "COMPLETE"
Method Parameters
Parameter Description
ownerId Match owner identifier
matchId Match identifier

CreateMatch

const char* playersJson; // [ { "platform": "BC", "id": "1234-1234-1234-1234" } ]
const char* notificationMessage = "Push message";

BrainCloudClient::getInstance()->getAsyncMatchService()->createMatch(
    playersJson,
    notificationMessage,
    this);
string playersJson; // [ { "platform": "BC", "id": "1234-1234-1234-1234" } ]
string notificationMessage = "Push message";

BrainCloudClient.Instance.AsyncMatchService.CreateMatch(
    playersJson,
    notificationMessage,
    ApiSuccess, ApiError);
public void createMatch(
    String jsonOpponentIds,
    String pushNotificationMessage,
    IServerCallback callback)
- (void)createMatch:(NSString *)jsonOpponentIds
    pushNotificationMessage:(NSString *)pushMessage
            completionBlock:(BCCompletionBlock)cb
       errorCompletionBlock:(BCErrorCompletionBlock)ecb
                   cbObject:(BCCallbackObject)cbObject;
brainCloudClient.asyncMatch.createMatch = function(opponentIds, pushNotificationMessage, callback)
var players = [ { "platform": "BC", "id": "1234-1234-1234-1234" } ];
var notificationMessage = "Push message";

var asyncMatchProxy = bridge.getAsyncMatchServiceProxy();
var retVal = asyncMatchProxy.createMatch(ownerId, notificationMessage);
Show Example JSON Return
{
    "status" : 200,
    "data" :
    {
        "gameId": "com.dnadpk.football",
        "ownerId": "0df9f282-183b-4d67-866e-670fb35a2376",
        "matchId": "match1",
        "version": 0,
        "players": [
            {
                "playerId": "0df9f282-183b-4d67-866e-670fb35a2376",
                "playerName": "",
                "pictureUrl": null
            },
            {
                "playerId": "4693ec75-3a99-4577-aef7-0f41d299339c",
                "playerName": "Presto1",
                "pictureUrl": null
            }
        ],
        "status": {
            "status": "NOT_STARTED",
            "currentPlayer": "0df9f282-183b-4d67-866e-670fb35a2376"
        },
        "summary": null,
        "createdAt": 1415641372974,
        "updatedAt": 1415641372974
    }
}

Creates an instance of an asynchronous match.

Opponents is a JSON array containing objects with a Platform and player ID. Platforms are identified as:

An example of this string would be:

[{ "platform":"BC", "id": "some-braincloud-profile" }, { "platform":"FB", "id": "some-facebook-id" }]

Service Operation
"asyncMatch" "CREATE"
Method Parameters
Parameter Description
opponents List of objects identifying the opponent platform and id for this match.
pushNotificationMessage Optional push notification message to send to the other party. Refer to the Push Notification functions for the syntax required.

CreateMatchWithInitialTurn

const char* playersJson; // [ { "platform": "BC", "id": "1234-1234-1234-1234" } ]
const char* matchStateJson; // { "level" : 01 }
const char* notificationMessage = "Push message";
const char* opponentId = "1234-1234-1234-1234";
const char* matchSummaryJson; // { "teamPoints" : 22 }

BrainCloudClient::getInstance()->getAsyncMatchService()->createMatchWithInitialTurn(
    playersJson,
    matchStateJson,
    notificationMessage,
    opponentId,
    matchSummaryJson,
    this);
string playersJson; // [ { "platform": "BC", "id": "1234-1234-1234-1234" } ]
string matchStateJson; // { "level" : 01 }
string notificationMessage = "Push message";
string opponentId = "1234-1234-1234-1234";
string matchSummaryJson; // { "teamPoints" : 22 }

BrainCloudClient.Instance.AsyncMatchService.CreateMatchWithInitialTurn(
    playersJson,
    matchStateJson,
    notificationMessage,
    opponentId,
    matchSummaryJson,
    ApiSuccess, ApiError)
public void createMatchWithInitialTurn(
    String jsonOpponentIds,
    String jsonMatchState,
    String pushNotificationMessage,
    String nextPlayer,
    String jsonSummary,
    IServerCallback callback)
- (void)createMatchWithInitialTurn:(NSString *)jsonOpponentIds
                    jsonMatchState:(NSString *)matchState
           pushNotificationMessage:(NSString *)pushMessage
                        nextPlayer:(NSString *)nextPlayer
                       jsonSummary:(NSString *)summary
                   completionBlock:(BCCompletionBlock)cb
              errorCompletionBlock:(BCErrorCompletionBlock)ecb
                          cbObject:(BCCallbackObject)cbObject;
brainCloudClient.asyncMatch.createMatchWithInitialTurn = function(opponentIds, matchState,
        pushNotificationMessage, nextPlayer, summary, callback)
var players = [ { "platform": "BC", "id": "1234-1234-1234-1234" } ];
var matchState = { "something" : 1234 };
var notificationMessage = "Push message";
var nextPlayer = null;
var summary = { "something" : 1234 };

var asyncMatchProxy = bridge.getAsyncMatchServiceProxy();
var retVal = asyncMatchProxy.createMatchWithInitialTurn(ownerId, matchState, notificationMessage, nextPlayer, summary);
Show Example JSON Return
{
    "data" : {
        "createdAt" : 1449737412088,
        "gameId" : "102345",
        "matchId" : "af876cc7-1dd1-4fbe-959d-a9awdsab9a1c",
        "ownerId" : "c76009c3-ea92-41c5-8560-e1dwasc07ce6b",
        "players" : [
            {
                "pictureUrl" : null,
                "playerId" : "c76009c3-ea92-41c5-8560-e1dwasc07ce6b",
                "playerName" : "UserA_CPP_96764398"
            },
            {
                "pictureUrl" : null,
                "playerId" : "3bb9dwasdd-9c9a-454f-ae17-9703a66973c8",
                "playerName" : "UserB_CPP_80148460"
            }
        ],
        "status" : {
            "currentPlayer" : "3bb9dwasdd-9c9a-454f-ae17-9703a66973c8",
            "status" : "PENDING"
        },
        "summary" : {
            "map" : "level01"
        },
        "updatedAt" : 1449737412092,
        "version" : 1
    },
    "status" : 200
}

Creates an instance of an asynchronous match with an initial turn.

Opponent IDs is a JSON array containing objects with a Platform and player ID. Platforms are identified as:

An example of this string would be:

[{ "platform":"BC", "id": "some-braincloud-profile" }, { "platform":"FB", "id": "some-facebook-id" }]

Service Operation
"asyncMatch" "CREATE"
Method Parameters
Parameter Description
jsonOpponentIds List of objects identifying the opponent platform and id for this match.
jsonMatchState JSON string blob provided by the caller
pushNotificationMessage Optional push notification message to send to the other party. Refer to the Push Notification functions for the syntax required.
nextPlayer Optionally, force the next player player to be a specific player
jsonSummary Optional JSON string defining what the other player will see as a summary of the game when listing their games

DeleteMatch

const char* ownerProfileId = "1234-1234-1234-1234";
const char* matchId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getAsyncMatchService()->deleteMatch(
    ownerProfileId,
    matchId,
    this);
string ownerProfileId = "1234-1234-1234-1234";
string matchId = "1234-1234-1234-1234";

BrainCloudClient.Instance.AsyncMatchService.DeleteMatch(
    ownerProfileId,
    matchId,
    ApiSuccess, ApiError);
public void deleteMatch(String in_ownerId, String in_matchId, IServerCallback callback)
- (void)deleteMatch:(NSString *)ownerId
              matchId:(NSString *)matchId
      completionBlock:(BCCompletionBlock)cb
 errorCompletionBlock:(BCErrorCompletionBlock)ecb
             cbObject:(BCCallbackObject)cbObject;
brainCloudClient.asyncMatch.deleteMatch = function(ownerId, matchId, callback)
var ownerId = "1234-1234-1234-1234";
var matchId = "1234-1234-1234-1234";

var asyncMatchProxy = bridge.getAsyncMatchServiceProxy();
var retVal = asyncMatchProxy.deleteMatch(ownerId, matchId);
Show Example JSON Return
{
 "status": 200,
 "data": null
}

Removes the match and match history from the server.

Service Operation
"asyncMatch" "DELETE_MATCH"
Method Parameters
Parameter Description
ownerId Match owner identifier
matchId Match identifier

FindCompleteMatches

BrainCloudClient::getInstance()->getAsyncMatchService()->findCompleteMatches(this);
BrainCloudClient.Instance.AsyncMatchService.FindCompleteMatches(
                ApiSuccess, ApiError);
public void findCompleteMatches(IServerCallback callback)
- (void)findCompleteMatches:(BCCompletionBlock)cb
       errorCompletionBlock:(BCErrorCompletionBlock)ecb
                   cbObject:(BCCallbackObject)cbObject;
brainCloudClient.asyncMatch.findCompleteMatches = function(callback)
var asyncMatchProxy = bridge.getAsyncMatchServiceProxy();
var retVal = asyncMatchProxy.findCompleteMatches();
Show Example JSON Return
{
    "status": 200,
    "data": {
        "results": [
            {
                "gameId": "109999",
                "ownerId": "9ad4f990-5466-4d00-a334-de834e1ac4ec",
                "matchId": "877dd25d-ea21-4857-ba2a-2134d0f5ace2",
                "version": 2,
                "players": [
                    {
                        "playerId": "9ad4f990-5466-4d00-a334-de834e1ac4ec",
                        "playerName": "",
                        "pictureUrl": null
                    },
                    {
                        "playerId": "963a2079-6e7a-48de-a4f2-8ab16c811975",
                        "playerName": "",
                        "pictureUrl": null
                    }
                ],
                "status": {
                    "status": "COMPLETE",
                    "currentPlayer": "963a2079-6e7a-48de-a4f2-8ab16c811975"
                },
                "summary": null,
                "createdAt": 1442586358023,
                "updatedAt": 1442586374787
            }
        ]
    }
}

Returns all matches that are in a COMPLETE state for which the player is involved.

Service Operation
"asyncMatch" "FIND_MATCHES_COMPLETED"

FindMatches

BrainCloudClient::getInstance()->getAsyncMatchService()->findMatches(this);
BrainCloudClient.Instance.AsyncMatchService.FindMatches(
    ApiSuccess, ApiError);
public void findMatches(IServerCallback callback)
- (void)findMatches:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
            cbObject:(BCCallbackObject)cbObject;
brainCloudClient.asyncMatch.findMatches = function(callback)
var asyncMatchProxy = bridge.getAsyncMatchServiceProxy();
var retVal = asyncMatchProxy.findMatches();
Show Example JSON Return
{
    "status": 200,
    "data": {
        "results": [
            {
                "gameId": "123456",
                "ownerId": "7630f98e-1236-4ead-88ee-27ce63b2db2c",
                "matchId": "97c8d087-40d8-45c2-aa2b-6d0d83424ec5",
                "version": 1,
                "players": [
                    {
                        "playerId": "7630f98e-13b6-4ead-88ee-27ce63b2db2c",
                        "playerName": "UserA-122217922",
                        "pictureUrl": null
                    },
                    {
                        "playerId": "b28ff14a-364a-40b3-ac4e-d2b23983519c",
                        "playerName": "UserC-338593317",
                        "pictureUrl": null
                    }
                ],
                "status": {
                    "status": "PENDING",
                    "currentPlayer": "efab2d0b-90a1-48cf-8678-ae81d7aaed89"
                },
                "summary": null,
                "createdAt": 1442586020180,
                "updatedAt": 1442586020188
            }
        ]
    }
}

Returns all matches that are NOT in a COMPLETE state for which the player is involved.

Service Operation
"asyncMatch" "FIND_MATCHES"

ReadMatch

const char* ownerProfileId = "1234-1234-1234-1234";
const char* matchId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getAsyncMatchService()->readMatch(
    ownerProfileId,
    matchId,
    this);
string ownerProfileId = "1234-1234-1234-1234";
string matchId = "1234-1234-1234-1234";

BrainCloudClient.Instance.AsyncMatchService.ReadMatch(
    ownerProfileId,
    matchId,
    ApiSuccess, ApiError);
public void readMatch(String in_ownerId, String in_matchId, IServerCallback callback)
- (void)readMatch:(NSString *)ownerId
              matchId:(NSString *)matchId
      completionBlock:(BCCompletionBlock)cb
 errorCompletionBlock:(BCErrorCompletionBlock)ecb
             cbObject:(BCCallbackObject)cbObject;
brainCloudClient.asyncMatch.readMatch = function(ownerId, matchId, callback)
var ownerId = "1234-1234-1234-1234";
var matchId = "1234-1234-1234-1234";

var asyncMatchProxy = bridge.getAsyncMatchServiceProxy();
var retVal = asyncMatchProxy.readMatch(ownerId, matchId);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "gameId": "11004",
        "ownerId": "35e8698f-b14d-48ae-a37c-4b2962308b8d",
        "matchId": "cfa752d6-d408-4671-9603-b22bf55d5379",
        "version": 1,
        "players": [{
            "playerId": "35e8698f-b14d-48ae-a37c-4b2962308b8d",
            "playerName": "",
            "pictureUrl": null
        }, {
            "playerId": "e84c16ea-bd62-4307-83f9-d32f8ac18bca",
            "playerName": "",
            "pictureUrl": null
        }],
        "status": {
            "status": "PENDING",
            "currentPlayer": "e84c16ea-bd62-4307-83f9-d32f8ac18bca"
        },
        "summary": null,
        "statistics": {},
        "matchState": {
            "testKey": "testValue"
        },
        "createdAt": 1472293357985,
        "updatedAt": 1472293357996
    }
}

Returns the current state of the given match.

Service Operation
"asyncMatch" "READ_MATCH"
Method Parameters
Parameter Description
ownerId Match owner identifier
matchId Match identifier

ReadMatchHistory

const char* ownerProfileId = "1234-1234-1234-1234";
const char* matchId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getAsyncMatchService()->readMatchHistory(
    ownerProfileId,
    matchId,
    this);
string ownerProfileId = "1234-1234-1234-1234";
string matchId = "1234-1234-1234-1234";

BrainCloudClient.Instance.AsyncMatchService.ReadMatchHistory(
    ownerProfileId,
    matchId,
    ApiSuccess, ApiError);
public void readMatchHistory(String in_ownerId, String in_matchId, IServerCallback callback)
- (void)readMatchHistory:(NSString *)ownerId
              matchId:(NSString *)matchId
      completionBlock:(BCCompletionBlock)cb
 errorCompletionBlock:(BCErrorCompletionBlock)ecb
             cbObject:(BCCallbackObject)cbObject;
brainCloudClient.asyncMatch.readMatchHistory = function(ownerId, matchId, callback)
var ownerId = "1234-1234-1234-1234";
var matchId = "1234-1234-1234-1234";

var asyncMatchProxy = bridge.getAsyncMatchServiceProxy();
var retVal = asyncMatchProxy.readMatchHistory(ownerId, matchId);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "gameId": "14577",
        "ownerId": "2bd32bc6-c2ec-4916-a1a8-02b7a38540ad",
        "matchId": "1aac24b2-7976-4fd7-b7c6-44d32e6d26a4",
        "turns": [
            {
                "playerId": "2bd32bc6-c2ec-4916-a1a8-02b7a38540ad",
                "matchState": {
                    "color": "red"
                },
                "createdAt": 1442507319697
            },
            {
                "playerId": "11c9324d-9ed1-416d-b124-5228c1efafac",
                "matchState": {},
                "createdAt": 1442507703667
            }
        ]
    }
}

Returns the match history of the given match.

Service Operation
"asyncMatch" "READ_MATCH_HISTORY"
Method Parameters
Parameter Description
ownerId Match owner identifier
matchId Match identifier

SubmitTurn

const char* ownerProfileId = "1234-1234-1234-1234";
const char* matchId = "1234-1234-1234-1234";
uint64_t matchVersion; //Retreived from previous calls to AsyncMatch or by calling ReadMatch
const char* matchStateJson; // { "level" : 01 }
const char* notificationMessage = "Push message";
const char* matchSummaryJson; // { "teamPoints" : 22 }
const char* matchStatsJson; // { "points " : 22 }

BrainCloudClient::getInstance()->getAsyncMatchService()->submitTurn(
    ownerProfileId,
    matchId,
    matchVersion,
    matchStateJson,
    notificationMessage,
    NULL, //let the server pick the next player automatically
    matchSummaryJson,
    matchStatsJson,
    this);
string ownerProfileId = "1234-1234-1234-1234";
string matchId = "1234-1234-1234-1234";
ulong matchVersion; //Retreived from previous calls to AsyncMatch or by calling ReadMatch
string matchStateJson; // { "level" : 01 }
string notificationMessage = "Push message";
string matchSummaryJson; // { "teamPoints" : 22 }
string matchStatsJson; // { "points " : 22 }

BrainCloudClient.Instance.AsyncMatchService.SubmitTurn(
    ownerProfileId,
    matchId,
    matchVersion,
    matchStateJson,
    notificationMessage,
    null, //let the server pick the next player automatically
    matchSummaryJson,
    matchStatsJson,
    ApiSuccess, ApiError)
public void submitTurn(
    String in_ownerId,
    String in_matchId,
    BigInteger in_version,
    String in_jsonMatchState,
    String in_pushNotificationMessage,
    String in_nextPlayer,
    String in_jsonSummary,
    String in_jsonStatistics,
    IServerCallback callback)
- (void)submitTurn:(NSString *)ownerId
                    matchId:(NSString *)matchId
                    version:(uint64_t)version
             jsonMatchState:(NSString *)matchState
    pushNotificationMessage:(NSString *)pushMessage
                 nextPlayer:(NSString *)nextPlayer
                jsonSummary:(NSString *)summary
             jsonStatistics:(NSString *)stats
            completionBlock:(BCCompletionBlock)cb
       errorCompletionBlock:(BCErrorCompletionBlock)ecb
                   cbObject:(BCCallbackObject)cbObject;
brainCloudClient.asyncMatch.submitTurn = function(ownerId, matchId, version, matchState,
        pushNotificationMessage, nextPlayer, summary, statistics)
string ownerId = "1234-1234-1234-1234";
string matchId = "1234-1234-1234-1234";
var version = 1;
var matchState = { "something" : 1234 };
var notificationMessage = "Push message";
var nextPlayer = null;
var summary = { "something" : 1234 };
var stats = { "something" : 1234 };

var asyncMatchProxy = bridge.getAsyncMatchServiceProxy();
var retVal = asyncMatchProxy.submitTurn(ownerId, matchId, version, matchState,
    notificationMessage, nextPlayer, summary, stats);
Show Example JSON Return
{
    "data" : {
        "createdAt" : 1449737412088,
        "gameId" : "102345",
        "matchId" : "af876cc7-1dd1-4fbe-959d-a9awdsab9a1c",
        "ownerId" : "c76009c3-ea92-41c5-8560-e1dwasc07ce6b",
        "players" : [
            {
                "pictureUrl" : null,
                "playerId" : "c76009c3-ea92-41c5-8560-e1dwasc07ce6b",
                "playerName" : "UserA_CPP_96764398"
            },
            {
                "pictureUrl" : null,
                "playerId" : "3bb9dwasdd-9c9a-454f-ae17-9703a66973c8",
                "playerName" : "UserB_CPP_80148460"
            }
        ],
        "status" : {
            "currentPlayer" : "3bb9dwasdd-9c9a-454f-ae17-9703a66973c8",
            "status" : "PENDING"
        },
        "summary" : {
            "map" : "level01"
        },
        "updatedAt" : 1449737412092,
        "version" : 1
    },
    "status" : 200
}

Submits a turn for the given match.

Service Operation
"asyncMatch" "SUBMIT_TURN"
Method Parameters
Parameter Description
ownerId Match owner identifier
matchId Match identifier
version Game state version to ensure turns are submitted once and in order
jsonMatchState JSON string blob provided by the caller
pushNotificationMessage Optional push notification message to send to the other party. Refer to the Push Notification functions for the syntax required.
nextPlayer Optionally, force the next player player to be a specific player
jsonSummary Optional JSON string defining what the other player will see as a summary of the game when listing their games
jsonStatistics Optional JSON string blob provided by the caller

UpdateMatchSummaryData

const char* ownerProfileId = "1234-1234-1234-1234";
const char* matchId = "1234-1234-1234-1234";
uint64_t matchVersion; //Retreived from previous calls to AsyncMatch or by calling ReadMatch
const char* matchSummaryJson; // { "teamPoints" : 22 }

BrainCloudClient::getInstance()->getAsyncMatchService()->updateMatchSummaryData(
    ownerProfileId,
    matchId,
    matchVersion,
    matchSummaryJson,
    this);
string ownerProfileId = "1234-1234-1234-1234";
string matchId = "1234-1234-1234-1234";
ulong matchVersion; //Retreived from previous calls to AsyncMatch or by calling ReadMatch
string matchSummaryJson; // { "teamPoints" : 22 }

BrainCloudClient.Instance.AsyncMatchService.UpdateMatchSummaryData(
    ownerProfileId,
    matchId,
    matchVersion,
    matchSummaryJson,
    ApiSuccess, ApiError)
public void updateMatchSummaryData(
    String in_ownerId,
    String in_matchId,
    BigInteger in_version,
    String in_jsonSummary,
    IServerCallback callback)
- (void)updateMatchSummaryData:(NSString *)ownerId
                       matchId:(NSString *)matchId
                       version:(uint64_t)version
                   jsonSummary:(NSString *)summary
               completionBlock:(BCCompletionBlock)cb
          errorCompletionBlock:(BCErrorCompletionBlock)ecb
                      cbObject:(BCCallbackObject)cbObject;
brainCloudClient.asyncMatch.updateMatchSummaryData = function(ownerId, matchId, version, summary, callback)
string ownerId = "1234-1234-1234-1234";
string matchId = "1234-1234-1234-1234";
var version = 21;
var summary = { "something" : 1234 };

var asyncMatchProxy = bridge.getAsyncMatchServiceProxy();
var retVal = asyncMatchProxy.updateMatchSummaryData(ownerId, matchId, version, summary);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "gameId": "145677",
        "ownerId": "2bd723c6-c2ec-4946-a1a8-02b7a38540ad",
        "matchId": "1aac24b2-7976-4fd7-b7c6-44d7ae6d26a4",
        "version": 2,
        "players": [
            {
                "playerId": "2bd723c6-c2ec-4946-a1a8-02b7a38540ad",
                "playerName": "UserA",
                "pictureUrl": null
            },
            {
                "playerId": "11c2dd4d-9ed1-416d-bd04-5228c1efafac",
                "playerName": "UserB",
                "pictureUrl": null
            }
        ],
        "status": {
            "status": "PENDING",
            "currentPlayer": "11c2dd4d-9ed1-416d-bd04-5228c1efafac"
        },
        "summary": {
            "resources": 2564
        },
        "createdAt": 1442507219609,
        "updatedAt": 1442507550372
    }
}

Allows the current player (only) to update Summary data without having to submit a whole turn.

Service Operation
"asyncMatch" "UPDATE_SUMMARY"
Method Parameters
Parameter Description
ownerId Match owner identifier
matchId Match identifier
version Game state version to ensure turns are submitted once and in order
jsonSummary JSON string provided by the caller that other players will see as a summary of the game when listing their games

Client

The BrainCloudClient class is the core of the brainCloud API. From the BrainCloudClient you can access all of brainCloud's services (Authentication, Entity, etc) and from there the individual API's they contain.

The Client also contains many setup and configuration methods for timeouts, global callbacks, and more.

Summary

Critical

Functions that are necessary to use the brianCloud library.

Callbacks

Functions to register and deregister callbacks for specific events.

Timeouts

Functions to configure network timeouts.

Status

Functions to query the client state or reset network communications.

File Upload

Functions to register for file upload callbacks and configure upload specific timeouts.

Network Error Caching

Functions to enable and manage network error message caching.

Compatibility

Compatibility settings for older brainCloud versions.

DeregisterEventCallback

BrainCloudClient.Instance.DeregisterEventCallback();
BrainCloudClient::getInstance()->deregisterEventCallback();
[[[BrainCloudClient getInstance] deregisterEventCallback];
BrainCloudClient.getInstance().deregisterEventCallback();
brainCloudClient.deregisterEventCallback();

Deregisters the event callback.

DeregisterFileUploadCallback

BrainCloudClient.Instance.DeregisterFileUploadCallback();
BrainCloudClient::getInstance()->deregisterFileUploadCallback();
[[[BrainCloudClient getInstance] deregisterFileUploadCallback];
//Coming soon
N/A

Deregisters the file upload callback

DeregisterGlobalErrorCallback

BrainCloudClient.Instance.DeregisterGlobalErrorCallback();
BrainCloudClient::getInstance()->deregisterGlobalErrorCallback();
[[[BrainCloudClient getInstance] deregisterGlobalErrorCallback];
public void deregisterGlobalErrorCallback();
N/A

Deregisters the global error callback.

DeregisterNetworkErrorCallback

BrainCloudClient.Instance.DeregisterNetworkErrorCallback();
BrainCloudClient::getInstance()->deregisterNetworkErrorCallback();
[[[BrainCloudClient getInstance] deregisterNetworkErrorCallback];
public void deregisterNetworkErrorCallback();
N/A

Deregisters the network error callback.

DeregisterRewardCallback

BrainCloudClient.Instance.DeregisterRewardCallback();
BrainCloudClient::getInstance()->deregisterRewardCallback();
[[[BrainCloudClient getInstance] deregisterRewardCallback];
BrainCloudClient.getInstance().deregisterRewardCallback();
brainCloudClient.deregisterRewardCallback();

Deregisters the event callback.

EnableLogging

BrainCloudClient.Instance.EnableLogging(true);
BrainCloudClient::getInstance()->enableLogging(true);
[[[BrainCloudClient getInstance] enableLogging:true];
BrainCloudClient.getInstance().enableLogging(true);
brainCloudClient.enableLogging(true);

Enables console logging of outgoing/incoming packets and other informational logs from the client.

Parameter Description
enabled True if logging should be enabled

EnableNetworkErrorMessageCaching

BrainCloudClient.Instance.EnableNetworkErrorMessageCaching(true);
BrainCloudClient::getInstance()->enableNetworkErrorMessageCaching(true);
[[[BrainCloudClient getInstance] enableNetworkErrorMessageCaching:true];
BrainCloudClient.getInstance().enableNetworkErrorMessageCaching(true);
N/A

Enables the timeout message caching which is disabled by default. Once enabled, if a client side timeout is encountered (i.e. brainCloud server is unreachable presumably due to the client network being down) the SDK will do the following:

  1. cache the currently queued messages to brainCloud
  2. call the network error callback
  3. then expect the app to call either:
    • RetryCachedMessages() to retry sending to brainCloud
    • FlushCachedMessages() to dump all messages in the queue.

Between steps 2 & 3, the app can prompt the user to retry connecting to brainCloud to determine whether to follow path 3a or 3b.

Note that if path 3a is followed, and another timeout is encountered, the process will begin all over again from step 1.

Parameter Description
enabled True if message should be cached on timeout

FlushCachedMessages

BrainCloudClient.Instance.FlushCachedMessages(false);
BrainCloudClient::getInstance()->flushCachedMessages(true);
[[[BrainCloudClient getInstance] flushCachedMessages:true];
BrainCloudClient.getInstance().flushCachedMessages(true);
N/A

Flushes the cached messages to resume API call processing. This will dump all of the cached messages in the queue.

Parameter Description
sendApiErrorCallbacks If set to true API error callbacks will be called for every cached message with statusCode CLIENT_NETWORK_ERROR and reasonCode CLIENT_NETWORK_ERROR_TIMEOUT.

GetAuthenticationPacketTimeout

int timeout = BrainCloudClient.Instance.GetAuthenticationPacketTimeout();
int timeout = BrainCloudClient::getInstance()->getAuthenticationPacketTimeout();
int timeout = [[[BrainCloudClient getInstance] getAuthenticationPacketTimeout];
int timeout = BrainCloudClient.getInstance().getAuthenticationPacketTimeout();
N/A

Gets the authentication packet timeout which is tracked separately from all other packets. Note that authentication packets are never retried and so this value represents the total time a client would wait to receive a reply to an authentication API call.

By default this timeout is set to 15 seconds.

GetInstance

//C# uses a property instead of GetInstance
BrainCloudClient client = BrainCloudClient.Instance;
brainCloudClient* client = BrainCloudClient::getInstance();
brainCloudClient* client = [[BrainCloudClient getInstance];
BrainCloudClient client = BrainCloudClient::getInstance();
N/A

Returns the BrainCloudClient instance.

GetPacketTimeouts

List<int> timeouts = BrainCloudClient.Instance.GetPacketTimeouts();
std::vector<int> timeouts = BrainCloudClient::getInstance()->getPacketTimeouts();
NSArray* timeouts = [[[BrainCloudClient getInstance] getPacketTimeouts];
ArrayList<Integer> timeouts = BrainCloudClient.getInstance().getPacketTimeouts();
N/A

Returns the list of packet timeouts.

GetSessionId

string sessionId = BrainCloudClient.Instance.GetSessionId();
const char * sessionId = BrainCloudClient::getInstance()->getSessionId();
const char * sessionId = [[[BrainCloudClient getInstance] sessionId];
String sessionId = BrainCloudClient.getInstance().getSessionId();
var sessionId = brainCloudClient.getSessionId();

Returns the session id if a connection with brainCloud has been established.

GetUploadLowTransferRateThreshold

int bytesPerSecThreshold = BrainCloudClient.Instance.GetUploadLowTransferRateThreshold();
int bytesPerSecThreshold = BrainCloudClient::getInstance()->getUploadLowTransferRateThreshold();
int bytesPerSecThreshold = [[[BrainCloudClient getInstance] getUploadLowTransferRateThreshold];
N/A
N/A

Returns the low transfer rate threshold in bytes/sec.

GetUploadLowTransferRateTimeout

int timeout = BrainCloudClient.Instance.GetUploadLowTransferRateTimeout();
int timeout = BrainCloudClient::getInstance()->getUploadLowTransferRateTimeout();
int timeout = [[[BrainCloudClient getInstance] getUploadLowTransferRateTimeout];
N/A
N/A

Returns the low transfer rate timeout in seconds.

Initialize

To initialize, use this code:

const char* serverUrl = "https://sharedprod.braincloudservers.com/dispatcherv2";
const char* secret = "1234-1234-1234-1234";
const char* appId = "123456";

BrainCloudClient::getInstance()->initialize(serverUrl, secret, appId, "1.0.0");
// If you're using Unity, you can make use of the brainCloudSettings toolbar
string serverUrl = "https://sharedprod.braincloudservers.com/dispatcherv2";
string secret = "1234-1234-1234-1234";
string appId = "123456";

BrainCloudClient.Instance.Initialize(serverUrl, secret, appId, "1.0.0");
String serverUrl = "https://sharedprod.braincloudservers.com/dispatcherv2";
String secret = "1234-1234-1234-1234";
String appId = "123456";

BrainCloudClient.getInstance().initialize(appId, secret, "1.0.0", serverUrl);
NSString* serverUrl = "https://sharedprod.braincloudservers.com/dispatcherv2";
NSString* secret = "1234-1234-1234-1234";
NSString* appId = "123456";

[[BrainCloudClient getInstance] initialize:serverUrl
                                 secretKey:secret
                                    gameId:appId
                                    gameVersion:"1.0.0"];
var secret = "1234-1234-1234-1234";
var appId = "123456";

brainCloudClient.initialize(appId, secret, "1.0.0");

This method initializes the brainCloud client SDK. The information required to initialize can be found on the Application IDs page of the portal.

Method Parameters
Parameter Description
serverUrl The url of the brainCloud server.
secretKey The secret key for your game found in the brainCloud portal.
gameId The id of your game found in the brainCloud portal.
gameVersion The version of your game. This can be used to prevent older versions of your game from logging into brainCloud
appId (C++) Deprecated - use NULL
region (C++) The user's region code or NULL if not available.

InitializeIdentity

BrainCloudClient::getInstance()->initializeIdentity("myProfileId", "myAnonymousId");
BrainCloudClient.Instance.InitializeIdentity("myProfileId", "myAnonymousId");
BrainCloudClient.getInstance().initializeIdentity("myProfileId", "myAnonymousId");
[[[BrainCloudClient getInstance] initializeIdentity] etc...;
brainCloudClient.initializeIdentity = function(profileId, anonymousId)

Initializes the authentication service with an anonymous installation ID and most recently used profile ID. You will need to call this method before authenticating anonymously.

Note that calling this is the same as calling Initialize in the BrainCloudAuthentication service.

Method Parameters
Parameter Description
profileId The profile id of the user
anonymousId The anonymous id of the user

InsertEndOfMessageBundleMarker

BrainCloudClient::getInstance()->insertEndOfMessageBundleMarker();
BrainCloudClient.Instance.InsertEndOfMessageBundleMarker();
BrainCloudClient.getInstance().insertEndOfMessageBundleMarker();
[[BrainCloudClient getInstance] insertEndOfMessageBundleMarker];
brainCloudClient.insertEndOfMessageBundleMarker();

Inserts a marker which will tell the brainCloud comms layer to close the message bundle off at this point. Any messages queued before this method was called will likely be bundled together in the next send to the server.

IsAuthenticated

bool isAuthenticated = BrainCloudClient::getInstance()->isInitialized();
bool isAuthenticated = BrainCloudClient.Instance.Authenticated;
boolean isAuthenticated = BrainCloudClient.getInstance().isAuthenticated();
bool isAuthenticated = [[[BrainCloudClient getInstance] isAuthenticated];
var isAuthenticated = brainCloudClient.isAuthenticated();

Returns true if the user is currently authenticated. If a session time out or session invalidation is returned from executing a sever API call, this flag will reset back to false.

IsInitialized

bool isInitialized = BrainCloudClient::getInstance()->isInitialized();
bool isInitialized = BrainCloudClient.Instance.Initialized;
boolean isInitialized = BrainCloudClient.getInstance().isInitialized();
bool isInitialized = [[BrainCloudClient getInstance] isInitialized];
var isInitialized = brainCloudClient.isInitialized();

Returns whether the BrainCloudClient has been initialized using the Initialize() method.

OverrideCountryCode

const char* countryCode = "CA";
BrainCloudClient::getInstance()->overrideCountryCode(countryCode);
string countryCode = "CA";
BrainCloudClient.Instance.OverrideCountryCode(countryCode);
String countryCode = "CA";
BrainCloudClient.getInstance().overrideCountryCode(countryCode);
NSString* countryCode = "CA";
[[BrainCloudClient getInstance] overrideCountryCode:countryCode];
var countryCode = "CA";
brainCloudClient.overrideCountryCode(countryCode);

Sets the country code sent to brainCloud when a user authenticates. Will override any auto detected country.

These methods should be called before authenticating so that they are sent to the server.

Parameter Description
countryCode ISO 3166-1 two-letter country code

OverrideLanguageCode

const char* languageCode = "en";
BrainCloudClient::getInstance()->overrideLanguageCode(languageCode);
string languageCode = "en";
BrainCloudClient.Instance.OverrideLanguageCode(languageCode);
String languageCode = "en";
BrainCloudClient.getInstance().overrideLanguageCode(languageCode);
NSString* languageCode = "en";
[[BrainCloudClient getInstance] overrideLanguageCode:languageCode];
var languageCode = "en";
brainCloudClient.overrideLanguageCode(languageCode);

Sets the language code sent to brainCloud when a user authenticates. If the language is set to a non-ISO 639-1 standard value the game default will be used instead. The supported languages and the default can be set on the Localization page of the portal.

These methods should be called before authenticating so that they are sent to the server.

Will override any auto detected language.

Parameter Description
languageCode ISO 639-1 two-letter language code

RegisterEventCallback

BrainCloudClient.Instance.RegisterEventCallback(callbackFunction);
BrainCloudClient::getInstance()->registerEventCallback(this);
eventBlock = ^(NSString *eventsJson) {  };

[[BrainCloudClient getInstance] registerEventCallback:eventBlock];
BrainCloudClient.getInstance().registerEventCallback(callback);
brainCloudClient.registerEventCallback(eventCallback);
Show Example JSON Return
{
    "events": [
        {
            "fromPlayerId": "178ed06a-d575-4591-8970-e23a5d35f9df",
            "eventId": 3967,
            "createdAt": 1441742105908,
            "gameId": "123",
            "toPlayerId": "178ed06a-d575-4591-8970-e23a5d35f9df",
            "eventType": "test",
            "eventData": {
                "testData": 117
            }
        }
    ]
}

Sets a callback handler for any out of band event messages that come from brainCloud.

Parameter Description
eventCallback A function which takes a JSON string as it's only parameter.

RegisterFileUploadCallback

BrainCloudClient.Instance.RegisterFileUploadCallbacks(successCallback, successCallback);
BrainCloudClient::getInstance()->registerEventCallback(this);
fileUploadCompletedBlock = ^(NSString *fileUploadId, NSString *jsonResponse) { };

fileUploadFailedBlock = ^(NSString *fileUploadId, NSInteger status, NSInteger reasonCode, NSString *jsonResponse) { };

[[BrainCloudClient getInstance] registerFileUploadCallback:fileUploadCompletedBlock failedBlock:fileUploadFailedBlock];
// Coming soon
N/A
Show Example JSON Return
// SUCCESS JSON
{
    "status": 200,
    "data": {
        "fileDetails": {
            "updatedAt": 1452616408147,
            "fileSize": 100,
            "fileType": "User",
            "expiresAt": 1452702808146,
            "shareable": true,
            "uploadId": "cf9a075c-587e-4bd1-af0b-eab1a79b958f",
            "createdAt": 1452616408147,
            "profileId": "bf8a1433-62d2-448e-b396-f3dbffff44",
            "gameId": "99999",
            "path": "dir1/dir2",
            "filename": "filename",
            "replaceIfExists": true,
            "cloudPath": "bc/g/99999/u/bf8a1433-62d2-448e-b396-f3dbffff44/f/dir1/dir2/filename"
        }
    }
}

// FAILURE JSON
{
    "status": 403,
    "reason_code": 40300,
    "status_message": "Message describing failure",
    "severity": "ERROR"
}

Registers the file upload callbacks.

Parameter Description
fileUploadCallback The file upload callback handler.

RegisterNetworkErrorCallback

BrainCloudClient.Instance.RegisterNetworkErrorCallback(callback);
BrainCloudClient::getInstance()->registerNetworkErrorCallback(this);
networkErrorBlock = ^() {  };

[[BrainCloudClient getInstance] registerNetworkErrorCallback:networkErrorBlock];
BrainCloudClient.getInstance().registerNetworkErrorCallback(callback);
N/A

Registers a callback that is invoked for network errors. Note this is only called if EnableNetworkErrorMessageCaching has been set to true.

Parameter Description
callback The callback handler.

RegisterRewardCallback

BrainCloudClient.Instance.RegisterRewardCallback(callbackFunction);
BrainCloudClient::getInstance()->registerRewardCallback(this);
rewardBlock = ^(NSString *rewardsJson) {  };

[[BrainCloudClient getInstance] registerRewardCallback:rewardBlock];
BrainCloudClient.getInstance().registerRewardCallback(callback);
brainCloudClient.registerRewardCallback(rewardCallback);
Show Example JSON Return
{
    "status": 200,
    "apiRewards": [{
        "service": "authenticationV2",
        "operation": "AUTHENTICATE",
        "rewards": {
            "rewardDetails": {
                // the reward depending on type (see docs)
            }
        }
    }]
}

Sets a reward handler for any API call results that return rewards.

Parameter Description
rewardCallback The reward callback handler.

ResetCommunication

BrainCloudClient.Instance.ResetCommunication();
BrainCloudClient::getInstance()->resetCommunication();
[[BrainCloudClient getInstance] resetCommunication];
BrainCloudClient.getInstance().resetCommunication();
brainCloudClient.resetCommunication();

Clears any pending messages from communication library and clears all session information.

RetryCachedMessages

BrainCloudClient.Instance.RetryCachedMessages();
BrainCloudClient::getInstance()->retryCachedMessages();
[[BrainCloudClient getInstance] retryCachedMessages];
BrainCloudClient.getInstance().retryCachedMessages();
N/A

Attempts to resend any cached messages. If no messages are in the cache, this method does nothing.

RunCallbacks

BrainCloudClient.Instance.Update();
BrainCloudClient::getInstance()->runCallbacks();
[[BrainCloudClient getInstance] runCallbacks];
BrainCloudClient.getInstance().runCallbacks();
N/A

Run callbacks, to be called once per frame from your main thread

SetErrorCallbackOn202Status

N/A
BrainCloudClient::getInstance()->setErrorCallbackOn202Status(true);
[[BrainCloudClient getInstance] setErrorCallbackOn202Status:true];
N/A
N/A

Sets whether the error callback is triggered when a 202 status is received from the server. By default this is true.

Parameter Description
isError If set to true, 202 is treated as an error

SetAuthenticationPacketTimeout

int timeoutInSeconds = 30;
BrainCloudClient.Instance.SetAuthenticationPacketTimeout(timeoutInSeconds);
int timeoutInSeconds = 30;
BrainCloudClient::getInstance()->setAuthenticationPacketTimeout(timeoutInSeconds);
int timeoutInSeconds = 30;
[[BrainCloudClient getInstance] setAuthenticationPacketTimeout:timeoutInSeconds];
int timeoutInSeconds = 30;
BrainCloudClient.getInstance().setAuthenticationPacketTimeout(timeoutInSeconds);
N/A

Sets the authentication packet timeout which is tracked separately from all other packets. Note that authentication packets are never retried and so this value represents the total time a client would wait to receive a reply to an authentication API call.

By default this timeout is set to 15 seconds.

Parameter Description
timeoutSecs The timeout in seconds.

SetOldStyleStatusMessageErrorCallback

BrainCloudClient.Instance.SetOldStyleStatusMessageErrorCallback(false);
BrainCloudClient::getInstance()->setOldStyleStatusMessageErrorCallback(false);
[[BrainCloudClient getInstance] setOldStyleStatusMessageErrorCallback:false];
BrainCloudClient.getInstance().setOldStyleStatusMessageErrorCallback(false);
N/A

Sets the error callback to return the status message instead of the error JSON string. This flag is used to conform to pre-2.17 client behavior.

Parameter Description
enabled If set to true, enable legacy error message format

SetPacketTimeouts

var packetTimeouts = new List<int> { 10, 10, 10 };
BrainCloudClient.Instance.SetPacketTimeouts(packetTimeouts);
std::vector<int> packetTimeouts;
packetTimeouts.push_back(10);
packetTimeouts.push_back(10);
packetTimeouts.push_back(10);

BrainCloudClient::getInstance()->setPacketTimeouts(packetTimeouts);
NSArray* packetTimeouts = @[@10, @10, @10];
[[BrainCloudClient getInstance] setPacketTimeouts:packetTimeouts];
ArrayList<Integer> packetTimeouts = new ArrayList<Integer>(
    Arrays.asList(10, 10, 10));
BrainCloudClient.getInstance().setPacketTimeouts(packetTimeouts);
N/A

Sets the packet timeouts using a list of integers that represent timeout values in seconds for each packet retry. The first item in the list represents the timeout for the first packet attempt, the second for the second packet attempt, and so on.

The number of entries in this array determines how many packet retries will occur. By default, the packet timeout array is {10, 10, 10}

Parameter Description
intervalInSeconds The time between heartbeats in milliseconds

SetPacketTimeoutsToDefault

BrainCloudClient.Instance.SetPacketTimeoutsToDefault();
BrainCloudClient::getInstance()->setPacketTimeoutsToDefault();
[[BrainCloudClient getInstance] setPacketTimeoutsToDefault];
BrainCloudClient.getInstance().setPacketTimeoutsToDefault();
N/A

Sets the packet timeouts back to default.

SetUploadLowTransferRateThreshold

int minTransferRate = 1500;
BrainCloudClient.Instance.SetUploadLowTransferRateThreshold(minTransferRate);
int minTransferRate = 1500;
BrainCloudClient::getInstance()->setUploadLowTransferRateThreshold(minTransferRate);
int minTransferRate = 1500;
[[BrainCloudClient getInstance] setUploadLowTransferRateThreshold:minTransferRate];
N/A
N/A

Sets the low transfer rate threshold of an upload in bytes/sec.

If the transfer rate dips below the given threshold longer than the specified timeout, the transfer will fail.

By default this is set to 50 bytes/sec.

Parameter Description
bytesPerSec The low transfer rate threshold in bytes/sec

SetUploadLowTransferRateTimeout

int timeoutSecs = 60;
BrainCloudClient.Instance.SetUploadLowTransferRateTimeout(timeoutSecs);
int timeoutSecs = 60;
BrainCloudClient::getInstance()->setUploadLowTransferRateTimeout(timeoutSecs);
int timeoutSecs = 60;
[[BrainCloudClient getInstance] setUploadLowTransferRateTimeout:timeoutSecs];
N/A
N/A

Sets the timeout in seconds of a low speed upload (ie transfer rate which is underneath the low transfer rate threshold).

By default this is set to 120 seconds. Setting this value to 0 will turn off the timeout.

Parameter Description
timeoutSecs The timeout in seconds

Update

BrainCloudClient.Instance.Update();
// See RunCallbacks
// See RunCallbacks
// See RunCallbacks
N/A

Update method needs to be called regularly in order to process incoming and outgoing messages.

See RunCallbacks function for other platforms.

Data Stream

The data stream service allows you to send information about your users and their activity to brainCloud.

Combined with Integrations configured in the brainCloud portal you can pipe this data to hundreds of tools for analytics, marketing, and data warehousing.

CustomPageEvent

const char* eventName = "testPageEvent";
const char* jsonEventData; // { "test1": 1332 }

BrainCloudClient::getInstance()->getDataStreamService()->customPageEvent(
    eventName,
    jsonEventData,
    this
);
string eventName = "testPageEvent";
string jsonEventData; // { "test1": 1332 }

BrainCloudClient.Instance.DataStreamService.CustomPageEvent(
    eventName,
    jsonEventData,
    ApiSuccess, ApiError);
public void customPageEvent(String in_eventName, String in_jsonEventProperties, IServerCallback callback)
- (void)customPageEvent:(NSString *)eventName
    jsonEventProperties:(NSString *)jsonEventProperties
        completionBlock:(BCCompletionBlock)completionBlock
   errorCompletionBlock:(BCErrorCompletionBlock)ecb
               cbObject:(BCCallbackObject)cbObject;
brainCloudClient.dataStream.customPageEvent = function(eventName, eventProperties, callback)
var eventName = "testEvent";
var eventData = { "test1": 1332 };

var dataStreamProxy = bridge.getDataStreamServiceProxy();
var retVal = dataStreamProxy.customPageEvent(eventName, eventData);
Show Example JSON Return
{
    "status": 200,
    "data": null
}

Creates custom data stream page event

Service Operation
"dataStream" "CUSTOM_PAGE_EVENT"
Method Parameters
Parameter Description
eventName The name of the event
eventProperties The properties of the event

CustomScreenEvent

const char* eventName = "testPageEvent";
const char* jsonEventData; // { "test1": 1332 }

BrainCloudClient::getInstance()->getDataStreamService()->customScreenEvent(
    eventName,
    jsonEventData,
    this
);
string eventName = "testTrackEvent";
string jsonEventData; // { "test1": 1332 }

BrainCloudClient.Instance.DataStreamService.CustomScreenEvent(
    eventName,
    jsonEventData,
    ApiSuccess, ApiError);
public void customScreenEvent(String in_eventName, String in_jsonEventProperties, IServerCallback callback)
- (void)customScreenEvent:(NSString *)eventName
    jsonEventProperties:(NSString *)jsonEventProperties
        completionBlock:(BCCompletionBlock)completionBlock
   errorCompletionBlock:(BCErrorCompletionBlock)ecb
               cbObject:(BCCallbackObject)cbObject;
brainCloudClient.dataStream.customScreenEvent = function(eventName, eventProperties, callback)
var eventName = "testEvent";
var eventData = { "test1": 1332 };

var dataStreamProxy = bridge.getDataStreamServiceProxy();
var retVal = dataStreamProxy.customScreenEvent(eventName, eventData);
Show Example JSON Return
{
    "status": 200,
    "data": null
}

Creates custom data stream screen event

Service Operation
"dataStream" "CUSTOM_SCREEN_EVENT"
Method Parameters
Parameter Description
eventName The name of the event
eventProperties The properties of the event

CustomTrackEvent

const char* eventName = "testPageEvent";
const char* jsonEventData; // { "test1": 1332 }

BrainCloudClient::getInstance()->getDataStreamService()->customTrackEvent(
    eventName,
    jsonEventData,
    this
);
string eventName = "testTrackEvent";
string jsonEventData; // { "test1": 1332 }

BrainCloudClient.Instance.DataStreamService.CustomTrackEvent(
    eventName,
    jsonEventData,
    ApiSuccess, ApiError);
public void customTrackEvent(String in_eventName, String in_jsonEventProperties, IServerCallback callback)
- (void)customTrackEvent:(NSString *)eventName
    jsonEventProperties:(NSString *)jsonEventProperties
        completionBlock:(BCCompletionBlock)completionBlock
   errorCompletionBlock:(BCErrorCompletionBlock)ecb
               cbObject:(BCCallbackObject)cbObject;
brainCloudClient.dataStream.customTrackEvent = function(eventName, eventProperties, callback)
var eventName = "testEvent";
var eventData = { "test1": 1332 };

var dataStreamProxy = bridge.getDataStreamServiceProxy();
var retVal = dataStreamProxy.customTrackEvent(eventName, eventData);
Show Example JSON Return
{
    "status": 200,
    "data": null
}

Creates custom data stream track event

Service Operation
"dataStream" "CUSTOM_TRACK_EVENT"
Method Parameters
Parameter Description
eventName The name of the event
eventProperties The properties of the event

Entity

brainCloud User Entities (also called Player Entities) are full json objects (similar to Global Entities) except that are private to a brainCloud user. User entities can be as simple or complex as you would like. All User Entities:

User Entities are normally retrieved in bulk after a user logs in, and then updated in real-time as the user interacts with them.

Note that User Entities are by default private (only accessible by the owner), but you can make the accessible to other users via the GetSharedEntityForPlayerId and GetSharedEntitiesForPlayerId APIs. To do so, you must make them shareable to others via the ACL settings.

User Entity methods are organized into the following categories:

Core Access:
Singleton
Shared Data

For more information on how brainCloud organizes data, refer to the Cloud Data Overview.

CreateEntity

const char* entityType = "address";
std::string entityDataJson; // { "street" : "1309 Carling" }
std::string aclJson; // { "other": 0 }

BrainCloudClient::getInstance()->getEntityService()->createEntity(
    entityType,
    entityDataJson,
    aclJson,
    this);
string entityType = "address";
string entityDataJson; // { "street" : "1309 Carling" }
ACL acl = new ACL(ACL.Access.None);

BrainCloudClient.Instance.EntityService.CreateEntity(
    entityType,
    entityDataJson,
    acl.ToJsonString(),
    ApiSuccess,
    ApiError);
public void createEntity(String entityType, String jsonEntityData, String jsonEntityAcl, IServerCallback callback)
- (void)createEntity:(NSString *)entityType
      jsonEntityData:(NSString *)jsonEntityData
       jsonEntityAcl:(NSString *)jsonEntityAcl
     completionBlock:(BCCompletionBlock)completionBlock
errorCompletionBlock:(BCErrorCompletionBlock)ecb
            cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.createEntity = function(entityType, data, acl, callback)
var entityType = "address";
var entityData = { "street" : "1309 Carling" };
var acl = { "other": 0 };

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.createEntity(entityType, entityData, acl);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entityId": "113db68a-48ad-4fc9-9f44-5fd36fc6445f",
        "entityType": "person",
        "version": 1,
        "data": {
            "name": "john",
            "age": 30
        },
        "acl": {
            "other": 0
        },
        "createdAt": 1395943044322,
        "updatedAt": 1395943044322
    }
}

Method creates a new entity on the server.

Service Operation
"entity" "CREATE"
Method Parameters
Parameter Description
entityType The entity type as defined by the user
jsonEntityData The entity's data object
jsonEntityAcl The entity's Access Control List as object. A null ACL implies default permissions which make the entity readable/writeable by only the player.

DeleteEntity

const char* entityId = "address";
int64_t version; //last known version of the entity

BrainCloudClient::getInstance()->getEntityService()->deleteEntity(
    entityId,
    version,
    this);
string entityId = "1234-1234-1234-1234";
int version; //last known version of the entity

 BrainCloudClient.Instance.EntityService.DeleteEntity(entityId, version, ApiSuccess, ApiError);
public void deleteEntity(String entityId, int version, IServerCallback callback)
- (void)deleteEntity:(NSString *)entityId
             version:(int64_t)version
     completionBlock:(BCCompletionBlock)completionBlock
errorCompletionBlock:(BCErrorCompletionBlock)ecb
            cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.deleteEntity = function(entityId, version, callback)
var entityId = "1234-1234-1234-1234";
var version = 2;

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.deleteEntity(entityId, version);
Show Example JSON Return
{
    "status":200,
    "data":null
}

Method deletes the given entity on the server.

This method is affected by versioning. See the versioning documentation for more information.

Service Operation
"entity" "DELETE"
Method Parameters
Parameter Description
entityId The entity type as defined by the user
version The entity's data object
Error returns
Code Name Description
40344 ENTITY_VERSION_MISMATCH The version parameter does not match the current version on the server

DeleteSingleton

const char* entityType = "address";
int64_t version; //last known version of the entity

BrainCloudClient::getInstance()->getEntityService()->deleteSingleton(
    entityType, version, this);
string entityType = "address";
int version; //last known version of the entity

 BrainCloudClient.Instance.EntityService.DeleteEntity(entityType, version, ApiSuccess, ApiError);
public void deleteSingleton(String entityType, int version, IServerCallback callback)
- (void)deleteSingleton:(NSString *)entityType
                version:(int64_t)version
        completionBlock:(BCCompletionBlock)completionBlock
   errorCompletionBlock:(BCErrorCompletionBlock)ecb
               cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.deleteSingleton = function(entityType, version, callback)
var entityType = "test";
var version = 2;

var retVal = entityProxy.deleteEntity(entityType, version);
Show Example JSON Return
{
    "status":200,
    "data":null
}

Method deletes the given singleton on the server.

Singletons are defined by their entity type, so no two singletons of the same type can exist at once.

This method is affected by versioning. See the versioning documentation for more information.

Service Operation
"entity" "DELETE_SINGLETON"
Method Parameters
Parameter Description
entityType The entity type as defined by the user
version The entity's data object
Error returns
Code Name Description
40344 ENTITY_VERSION_MISMATCH The version parameter does not match the current version on the server

GetList

std::string whereJson; //{ "entityType" : "testEntity" }
std::string orderByJson; //{ "data.name" : 1 }

BrainCloudClient::getInstance()->getEntityService()->getList(
    whereJson, orderByJson, this);
string whereJson; //{ "entityType" : "testEntity" }
string orderByJson; //{ "data.name" : 1 }

 BrainCloudClient.Instance.EntityService.GetList(
    whereJson,
    orderByJson,
    10,
    ApiSuccess, ApiError);
public void getList(String in_whereJson, String in_orderByJson, int in_maxReturn, IServerCallback callback)
- (void)getList:(NSString *)whereJson
                 orderByJson:(NSString *)orderBy
                   maxReturn:(int64_t)maxReturn
             completionBlock:(BCCompletionBlock)completionBlock
        errorCompletionBlock:(BCErrorCompletionBlock)ecb
                    cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.getList = function(where, orderBy, maxReturn, callback)
var where = { "entityType" : "testEntity" };
var orderBy = { "data.name" : 1 };

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.getList(where, orderBy, 20);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entityListCount": 1,
        "entityList": [{
            "gameId": "123455",
            "entityId": "a3def0eb-3993-4a95-8fef-27f50a6d0f69",
            "ownerId": "11c9dd4d-9ed1-416d-bd04-5228c1efafac",
            "entityType": "address",
            "version": 1,
            "data": {
                "street": "123 Ave"
            },
            "acl": {
                "other": 1
            },
            "createdAt": 1449870753354,
            "updatedAt": 1449870753354
        }]
    }
}

Method gets list of entities from the server base on type and/or where clause.

Fields available for use in the 'where' clause are:

Along with all custom data (using data.). For more information on the query syntax see here.

Service Operation
"entity" "GET_LIST"
Method Parameters
Parameter Description
whereJson Mongo style query string
orderByJson Specifies the order in which the query returns matching documents. The sort parameter consists of a field followed by an ascending(1)/descending flag(-1). eg. { "name" : 1} sorts by name in ascending order
maxReturn The maximum number of entities to return

GetListCount

std::string whereJson; //{ "entityType" : "testEntity" }

BrainCloudClient::getInstance()->getEntityService()->getListCount(
    whereJson, this);
string whereJson; //{ "entityType" : "testEntity" }

 BrainCloudClient.Instance.EntityService.GetListCount(
    whereJson,
    ApiSuccess, ApiError);
public void getListCount(String in_whereJson, IServerCallback callback)
- (void)getListCount:(NSString *)whereJson
      completionBlock:(BCCompletionBlock)completionBlock
 errorCompletionBlock:(BCErrorCompletionBlock)ecb
             cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.getListCount = function(where, callback)
var where = { "entityType" : "testEntity" };

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.getListCount(where);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entityListCount": 5
    }
}

Method gets a count of entities based on the where clause.

Fields available for use in the 'where' clause are:

Along with all custom data (using data.). For more information on the query syntax see here.

Service Operation
"entity" "GET_LIST_COUNT"
Method Parameters
Parameter Description
whereJson Mongo style query string

GetSingleton

const char* entityType = "address";

BrainCloudClient::getInstance()->getEntityService()->getSingleton(
    entityType, this);
string entityType = "address";

 BrainCloudClient.Instance.EntityService.GetSingleton(entityType, ApiSuccess, ApiError);
public void getSingleton(String entityType, IServerCallback callback)
- (void)getSingleton:(NSString *)entityType
     completionBlock:(BCCompletionBlock)completionBlock
errorCompletionBlock:(BCErrorCompletionBlock)ecb
            cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.getSharedEntitiesForPlayerId = function(playerId, callback)
var entityType = "testEntity";

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.getSingleton(entityType);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entityId": "113db68a-48ad-4fc9-9f44-5fd36fc6445f",
        "entityType": "person",
        "version": 1,
        "data": {
            "name": "john",
            "age": 30
        },
        "acl": {
            "other": 0
        },
        "createdAt": 1395943044322,
        "updatedAt": 1395943044322
    }
}

Method retrieves a singleton entity on the server. If the entity doesn't exist, null is returned.

Service Operation
"entity" "READ_SINGLETON"
Method Parameters
Parameter Description
entityType The entity type as defined by the user

GetEntitiesByType

const char* entityType = "address";

BrainCloudClient::getInstance()->getEntityService()->getEntitiesByType(
    entityType, this);
string entityType = "address";

 BrainCloudClient.Instance.EntityService.GetEntitiesByType(entityType, ApiSuccess, ApiError);
public void getEntitiesByType(String entityType, IServerCallback callback)
- (void)getEntitiesByType:(NSString *)entityType
          completionBlock:(BCCompletionBlock)completionBlock
     errorCompletionBlock:(BCErrorCompletionBlock)ecb
                 cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.getEntitiesByType = function(entityType, callback)
var entityType = "testEntity";

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.getEntitiesByType(entityType);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entities": [
            {
                "entityId": "96f77c80-4257-45ee-aed7-f1c6dd1ac44c",
                "entityType": "address",
                "version": 1,
                "data": {
                    "street": "1309 Carling"
                },
                "acl": {
                    "other": 0
                },
                "createdAt": 1453926510649,
                "updatedAt": 1453926510649
            }
        ]
    }
}

Method returns all player entities that match the given type.

Service Operation
"entity" "READ_BY_TYPE"
Method Parameters
Parameter Description
entityType The entity type to search for

GetEntity

const char* entityId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getEntityService()->getEntity(entityId, this);
string entityId = "1234-1234-1234-1234";

BrainCloudClient.Instance.EntityService.GetEntity(entityId, ApiSuccess, ApiError);
public void getEntity(String entityId, IServerCallback callback)
- (void)getEntity:(NSString *)entityId
         completionBlock:(BCCompletionBlock)completionBlock
    errorCompletionBlock:(BCErrorCompletionBlock)ecb
                cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.getEntity = function(entityId, callback)
var entityId = "1234-1234-1234-1234";

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.getEntity(entityId);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entityId": "113db68a-48ad-4fc9-9f44-5fd36fc6445f",
        "entityType": "person",
        "version": 1,
        "data": {
            "name": "john",
            "age": 30
        },
        "acl": {
            "other": 0
        },
        "createdAt": 1395943044322,
        "updatedAt": 1395943044322
    }
}

Method to get a specific entity.

Service Operation
"entity" "READ"
Method Parameters
Parameter Description
entityId The id of the entity

GetPage

// Context example
{
    "pagination": {
        "rowsPerPage": 50,
        "pageNumber": 1
    },
    "searchCriteria": {
        "entityType": "address"
    },
    "sortCriteria": {
        "createdAt": 1,
        "updatedAt": -1
    }
}
const char* contextJson; //See Generic Paged Queries documentation

BrainCloudClient::getInstance()->getEntityService()->getPage(contextJson, this);
string contextJson; //See Generic Paged Queries documentation

BrainCloudClient.Instance.EntityService.GetPage(contextJson, ApiSuccess, ApiError);
public void getPage(String in_jsonContext, IServerCallback in_callback)
- (void)getPage:(NSString *)context
completionBlock:(BCCompletionBlock)completionBlock
errorCompletionBlock:(BCErrorCompletionBlock)ecb
       cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.getPage = function(context, callback)
var context = {
    "pagination": {
        "rowsPerPage": 50,
        "pageNumber": 1
    },
    "searchCriteria": {
        "entityType": "address"
    },
    "sortCriteria": {
        "createdAt": 1,
        "updatedAt": -1
    }
};

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.getPage(context);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "results": {
            "moreBefore": false,
            "count": 200,
            "items": [{
                "entityId": "00edfd8e-5028-45d5-95d4-b1869cf2afaa",
                "entityType": "testEntity",
                "version": 1,
                "data": {
                    "testName": "Test Name 01"
                },
                "acl": {
                    "other": 2
                },
                "createdAt": 1437505537168,
                "updatedAt": 1437505537168
            }],
            "page": 1,
            "moreAfter": true
        },
        "context": "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjoiYnVpbGRpbmciLCJnYW
        1lSWQiOiIxMDI4NyIsIiRvciI6W3sib3duZXJJZCI6Ijk5MjM4ZmFiLTkxYTItNDdiYy1
        iMDExLWJjMThhN2IyOWY3NiJ9LHsiYWNsLm90aGVyIjp7IiRuZSI6MH19XX0sInNvcnRD
        cml0ZXJpYSI6eyJjcmVhdGVkQXQiOjEsInVwZGF0ZWRBdCI6LTF9LCJwYWdpbmF0aW9uI
        jp7InJvd3NQZXJQYWdlIjo1MCwicGFnZU51bWJlciI6NH0sIm9wdGlvbnMiOm51bGx9"
    }
}

Method uses a paging system to iterate through user entities.

After retrieving a page of entities with this method use getPageOffset to retrieve previous or next pages.

See the Generic Paged Queries documentation for creating the context object.

Service Operation
"entity" "GET_PAGE"
Method Parameters
Parameter Description
context The JSON context for the page request.
Error returns
Code Name Description
40384 INVALID_QUERY_CONTEXT Invalid query context

GetPageOffset

const char* contextJson; //See Generic Paged Queries documentation
int32_t pageOffset = 2;

BrainCloudClient::getInstance()->getEntityService()->getPageOffset(contextJson, pageOffset, this);
string contextJson; //From return of GetPage Call
int pageOffset = 2;

BrainCloudClient.Instance.EntityService.GetPageOffset(contextJson, pageOffset, ApiSuccess, ApiError);
public void getPageOffset(String in_context, int in_pageOffset, IServerCallback in_callback)
- (void)getPageOffset:(NSString *)context
           pageOffset:(int)pageOffset
      completionBlock:(BCCompletionBlock)completionBlock
 errorCompletionBlock:(BCErrorCompletionBlock)ecb
             cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.getPageOffset = function(context, pageOffset, callback)
var returnedContext;

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.getPageOffset(returnedContext, 1);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "results": {
            "moreBefore": false,
            "count": 200,
            "items": [{
                "entityId": "00edfd8e-5028-45d5-95d4-b1869cf2afaa",
                "entityType": "testEntity",
                "version": 1,
                "data": {
                    "testName": "Test Name 01"
                },
                "acl": {
                    "other": 2
                },
                "createdAt": 1437505537168,
                "updatedAt": 1437505537168
            }],
            "page": 2,
            "moreAfter": false
        },
        "context": "eyJzZWFyY2hDcml0ZXJpYSI6eyJlbnRpdHlUeXBlIjoiYnVpbGRpbmciLCJnYW
        1lSWQiOiIxMDI4NyIsIiRvciI6W3sib3duZXJJZCI6Ijk5MjM4ZmFiLTkxYTItNDdiYy1
        iMDExLWJjMThhN2IyOWY3NiJ9LHsiYWNsLm90aGVyIjp7IiRuZSI6MH19XX0sInNvcnRD
        cml0ZXJpYSI6eyJjcmVhdGVkQXQiOjEsInVwZGF0ZWRBdCI6LTF9LCJwYWdpbmF0aW9uI
        jp7InJvd3NQZXJQYWdlIjo1MCwicGFnZU51bWJlciI6NH0sIm9wdGlvbnMiOm51bGx9"
    }
}

Method to retrieve previous or next pages after having called the GetPage method.

Service Operation
"entity" "GET_PAGE_BY_OFFSET"
Method Parameters
Parameter Description
context The context string returned from the server from a previous call to GetPage or GetPageOffset
pageOffset The positive or negative page offset to fetch. Uses the last page retrieved using the context string to determine a starting point.
Error returns
Code Name Description
40383 DECODE_CONTEXT Unable to decode context

GetSharedEntityForPlayerId

const char* playerId = "1234-1234-1234-1234";
const char* entityId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getEntityService()->getSharedEntityForPlayerId(playerId, entityId, this);
string playerId = "1234-1234-1234-1234";
string entityId = "1234-1234-1234-1234";

BrainCloudClient.Instance.EntityService.GetSharedEntityForPlayerId(playerId, entityId, ApiSuccess, ApiError);
public void getSharedEntityForPlayerId(String playerId, String entityId, IServerCallback callback)
- (void)getSharedEntityForPlayerId:(NSString *)playerId
                          entityId:(NSString*)entityId
                   completionBlock:(BCCompletionBlock)completionBlock
              errorCompletionBlock:(BCErrorCompletionBlock)ecb
                          cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.getSharedEntityForPlayerId = function(playerId, entityId, callback)
var playerId = "1234-1234-1234-1234";
var entityId = "1234-1234-1234-1234";

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.getSharedEntityForPlayerId(playerId, entityId);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entityId": "544db68a-48ad-4fc9-9f44-5fd36fc6445f",
        "entityType": "publicInfo",
        "version": 1,
        "data": {
            "name": "john",
            "age": 30
        },
        "acl": {
            "other": 1
        },
        "createdAt": 1395943044322,
        "updatedAt": 1395943044322
    }
}

Method returns a shared entity for the given player and entity ID.

An entity is shared if its ACL allows for the currently logged in player to read the data.

Service Operation
"entity" "READ_SHARED_ENTITY"
Method Parameters
Parameter Description
playerId The player id to retrieve shared entities for
entityId The ID of the entity that will be retrieved

GetSharedEntitiesForPlayerId

const char* playerId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getEntityService()->getSharedEntitiesForPlayerId(playerId, this);
string playerId = "1234-1234-1234-1234";

BrainCloudClient.Instance.EntityService.GetSharedEntitiesForPlayerId(playerId, ApiSuccess, ApiError);
public void getSharedEntitiesForPlayerId(String playerId, IServerCallback callback)
- (void)getSharedEntitiesForPlayerId:(NSString *)playerId
                     completionBlock:(BCCompletionBlock)completionBlock
                errorCompletionBlock:(BCErrorCompletionBlock)ecb
                            cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.getSharedEntitiesForPlayerId = function(playerId, callback)
var playerId = "1234-1234-1234-1234";

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.getSharedEntitiesForPlayerId(playerId);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entities": [
            {
                "entityId": "544db68a-48ad-4fc9-9f44-5fd36fc6445f",
                "entityType": "publicInfo",
                "version": 1,
                "data": {
                    "name": "john",
                    "age": 30
                },
                "acl": {
                    "other": 1
                },
                "createdAt": 1395943044322,
                "updatedAt": 1395943044322
            }
        ]
    }
}

Method returns all shared entities for the given player id.

An entity is shared if its ACL allows for the currently logged in player to read the data.

Service Operation
"entity" "READ_SHARED"
Method Parameters
Parameter Description
playerId The player id to retrieve shared entities for

GetSharedEntitiesListForPlayerId

const char* targetPlayerId = "1234-1234-1234-1234";
std::string whereJson; //{ "entityType" : "testEntity" }
std::string orderByJson; //{ "data.name" : 1 }

BrainCloudClient::getInstance()->getEntityService()->getSharedEntitiesListForPlayerId(
    targetPlayerId, whereJson, orderByJson, this);
string targetPlayerId = "1234-1234-1234-1234";
string whereJson; //{ "entityType" : "testEntity" }
string orderByJson; //{ "data.name" : 1 }

 BrainCloudClient.Instance.EntityService.GetSharedEntitiesListForPlayerId(
    targetPlayerId,
    whereJson,
    orderByJson,
    10,
    ApiSuccess, ApiError);
public void getSharedEntitiesListForPlayerId(
    String in_playerId,
    String in_whereJson,
    String in_orderByJson,
    int in_maxReturn,
    IServerCallback callback)
- (void)getSharedEntitiesListForPlayerId:(NSString *)playerId
                               whereJson:(NSString *)whereJson
                             orderByJson:(NSString *)orderByJson
                               maxReturn:(int32_t)maxReturn
                         completionBlock:(BCCompletionBlock)completionBlock
                    errorCompletionBlock:(BCErrorCompletionBlock)ecb
                                cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.getSharedEntitiesListForPlayerId = function(
    playerId,
    where,
    orderBy,
    maxReturn,
    callback)
var targetPlayerId = "1234-1234-1234-1234";
var where = { "entityType" : "testEntity" };
var orderBy = { "data.name" : 1 };

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.getSharedEntitiesListForPlayerId(targetPlayerId, where, orderBy, 20);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entities": [
            {
                "entityId": "544db68a-48ad-4fc9-9f44-5fd36fc6445f",
                "entityType": "publicInfo",
                "version": 1,
                "data": {
                    "name": "john",
                    "age": 30
                },
                "acl": {
                    "other": 1
                },
                "createdAt": 1395943044322,
                "updatedAt": 1395943044322
            }
        ]
    }
}

Method gets list of shared entities for the specified player based on type and/or where clause.

Fields available for use in the 'where' clause are:

Along with all custom data (using data.). For more information on the query syntax see here.

Service Operation
"entity" "READ_SHARED_ENTITIES_LIST"
Method Parameters
Parameter Description
playerId The player ID to retrieve shared entities for
whereJson Mongo style query string
orderByJson Specifies the order in which the query returns matching documents. The sort parameter consists of a field followed by an ascending(1)/descending flag(-1). eg. { "name" : 1} sorts by name in ascending order
maxReturn The maximum number of entities to return

IncrementUserEntityData

const char* entityId = "1234-1234-1234-1234";
std::string entityDataJson; // { "test" : "123" } //add 123 to the value test

BrainCloudClient::getInstance()->getEntityService()->incrementUserEntityData(
    entityId, entityDataJson, this);
string entityId = "1234-1234-1234-1234";
string entityDataJson; // { "test" : "123" } //add 123 to the value test

BrainCloudClient.Instance.EntityService.IncrementUserEntityData(
    entityId,
    entityDataJson
    ApiSuccess, ApiError);
public void incrementUserEntityData(
    String entityId,
    String jsonEntityData,
    IServerCallback callback)
- (void)incrementUserEntityData:(NSString *)entityId
      jsonEntityData:(NSString *)jsonEntityData
     completionBlock:(BCCompletionBlock)completionBlock
errorCompletionBlock:(BCErrorCompletionBlock)ecb
            cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.incrementUserEntityData = function(entityId, data, callback)
var entityId = "1234-1234-1234-1234";
var entityData = { "asdf" : "asdf23w" };

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.incrementUserEntityData(entityId, entityData);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "acl": {
            "other": 0
        },
        "createdAt": 1467014334065,
        "data": {
            "test": 2466
        },
        "entityId": "ffa29930-4a33-420e-9beb-fdfdd0190750",
        "entityType": "Test",
        "gameId": "20001",
        "playerId": "6a63c968-c102-4a5a-8336-68b2150f369f",
        "updatedAt": 1467014334065,
        "version": 2
    }
}

Partial increment of entity data field items. Partial set of items incremented as specified.

Service Operation
"entity" "INCREMENT_USER_ENTITY_DATA"
Method Parameters
Parameter Description
entityId The id of the entity to update
jsonData The entity's data object

IncrementSharedUserEntityData

const char* entityId = "1234-1234-1234-1234";
const char* targetPlayerId = "1234-1234-1234-1234";
std::string entityDataJson; // { "test" : "123" } //add 123 to the value test

BrainCloudClient::getInstance()->getEntityService()->incrementSharedUserEntityData(
    entityId, targetPlayerId, entityDataJson, this);
string entityId = "1234-1234-1234-1234";
string targetPlayerId = "1234-1234-1234-1234";
string entityDataJson; // { "test" : "123" } //add 123 to the value test

BrainCloudClient.Instance.EntityService.IncrementSharedUserEntityData(
    entityId,
    targetPlayerId,
    entityDataJson
    ApiSuccess, ApiError);
public void incrementSharedUserEntityData(
    String entityId,
    String targetPlayerId,
    String jsonEntityData,
    IServerCallback callback)
- (void)incrementSharedUserEntityData:(NSString *)entityId
        targetPlayerId:(NSString*)targetPlayerId
      jsonEntityData:(NSString *)jsonEntityData
     completionBlock:(BCCompletionBlock)completionBlock
errorCompletionBlock:(BCErrorCompletionBlock)ecb
            cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.incrementSharedUserEntityData = function(entityId, targetPlayerId, data, callback)
var targetPlayerId = "1234-1234-1234-1234";
var entityId = "1234-1234-1234-1234";
var entityData = { "asdf" : "asdf23w" };

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.incrementSharedUserEntityData(targetPlayerId, entityId, entityData);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "acl": {
            "other": 0
        },
        "createdAt": 1467014334065,
        "data": {
            "test": 2466
        },
        "entityId": "ffa29930-4a33-420e-9beb-fdfdd0190750",
        "entityType": "Test",
        "gameId": "20001",
        "playerId": "6a63c968-c102-4a5a-8336-68b2150f369f",
        "updatedAt": 1467014334065,
        "version": 2
    }
}

Partial increment of entity data field items. Partial set of items incremented as specified.

Service Operation
"entity" "INCREMENT_SHARED_USER_ENTITY_DATA"
Method Parameters
Parameter Description
entityId The id of the entity to update
targetPlayerId Profile ID of the entity owner
jsonData The entity's data object

UpdateEntity

const char* entityId = "1234-1234-1234-1234";
const char* entityType = "address";
std::string entityDataJson; // { "street" : "1309 Carling" }
std::string aclJson; // { "other": 0 }
int64_t version; //last known version of entity

BrainCloudClient::getInstance->getEntityService()->updateEntity(
    entityId, entityType, entityDataJson, aclJson, version, this);
string entityId = "1234-1234-1234-1234";
string entityType = "address";
string entityDataJson; // { "street" : "1309 Carling" }
ACL acl = new ACL(ACL.Access.Read);
int version; //last known version of entity

BrainCloudClient.Instance.EntityService.UpdateEntity(
    entityId,
    entityType,
    entityDataJson,
    acl.ToJsonString(),
    version,
    ApiSuccess,
    ApiError);
public void updateEntity(
    String entityId,
    String entityType,
    String jsonEntityData,
    String jsonEntityAcl,
    int version,
    IServerCallback callback)
- (void)updateEntity:(NSString *)entityId
          entityType:(NSString *)entityType
      jsonEntityData:(NSString *)jsonEntityData
       jsonEntityAcl:(NSString *)jsonEntityAcl
             version:(int64_t)version
     completionBlock:(BCCompletionBlock)completionBlock
errorCompletionBlock:(BCErrorCompletionBlock)ecb
            cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.updateEntity = function(entityId, entityType, data, acl, version, callback)
var entityId = "1234-1234-1234-1234";
var entityType = "test";
var entityData = { "asdf" : "asdf23w" };
var acl = { "other" : 1 };
var version = 1;

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.updateEntity(entityId, entityType, entityData, acl, version);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entityId": "113db68a-48ad-4fc9-9f44-5fd36fc6445f",
        "entityType": "person",
        "version": 1,
        "data": {
            "name": "john",
            "age": 30
        },
        "acl": {
            "other": 0
        },
        "createdAt": 1395943044322,
        "updatedAt": 1395943044322
    }
}

Method updates an entity on the server. This operation results in the entity data being completely replaced by the passed in JSON string.

This method is affected by versioning. See the versioning documentation for more information.

Service Operation
"entity" "UPDATE"
Method Parameters
Parameter Description
entityId The id of the entity to update
entityType The entity type as defined by the user
jsonEntityData The entity's data object
jsonEntityAcl The entity's Access Control List as object. A null ACL implies default permissions which make the entity readable/writeable by only the player.
Error returns
Code Name Description
40332 UPDATE_FAILED An update operation failed. Used for entities, global entities, and updates on the player.

UpdateSingleton

const char* entityType = "address";
std::string entityDataJson; // { "street" : "1309 Carling" }
std::string aclJson; // { "other": 0 }
int64_t version; //last known version of entity

BrainCloudClient::getInstance->getEntityService()->updateSingleton(
    entityType, entityDataJson, aclJson, version, this);
string entityType = "address";
string entityDataJson; // { "street" : "1309 Carling" }
ACL acl = new ACL(ACL.Access.Read);
int version; //last known version of entity

BrainCloudClient.Instance.EntityService.UpdateSingleton(
    entityType,
    entityDataJson,
    acl.ToJsonString(),
    version,
    ApiSuccess,
    ApiError);
public void updateSingleton(
    String entityType,
    String jsonEntityData,
    String jsonAclData,
    int version,
    IServerCallback callback)
- (void)updateSingleton:(NSString *)entityType
         jsonEntityData:(NSString *)jsonEntityData
          jsonEntityAcl:(NSString *)jsonEntityAcl
                version:(int64_t)version
        completionBlock:(BCCompletionBlock)completionBlock
   errorCompletionBlock:(BCErrorCompletionBlock)ecb
               cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.updateSingleton = function(entityType, data, acl, version, callback)
var entityType = "test";
var entityData = { "asdf" : "asdf23w" };
var acl = { "other" : 1 };
var version = 1;

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.updateSingleton(entityType, entityData, acl, version);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entityType": "test",
        "version": 1  // Note - `version` will only be returned if not null or -1 in the update call 
    }
}

Method updates a singleton entity on the server. This operation results in the entity data being completely replaced by the passed in JSON string. If the entity doesn't exist it is created.

Singletons are defined by their entity type, so no two singletons of the same type can exist at once.

This method is affected by versioning. See the versioning documentation for more information.

Service Operation
"entity" "UPDATE_SINGLETON"
Method Parameters
Parameter Description
entityType The entity type as defined by the user
jsonEntityData The entity's data object
jsonEntityAcl The entity's Access Control List as object. A null ACL implies default permissions which make the entity readable/writeable by only the player.

UpdateSharedEntity

const char* entityId = "1234-1234-1234-1234";
const char* targetPlayerId = "1234-1234-1234-1234";
const char* entityType = "address";
std::string entityDataJson; // { "street" : "1309 Carling" }
int64_t version; //last known version of entity

BrainCloudClient::getInstance->getEntityService()->updateSharedEntity(
    entityId, targetPlayerId, entityType, entityDataJson, version, this);
string playerId = "1234-1234-1234-1234"; //owner of the entity
string entityId = "1234-1234-1234-1234";
string entityType = "address";
string entityDataJson; // { "street" : "1309 Carling" }
int version; //last known version of entity

BrainCloudClient.Instance.EntityService.UpdateSharedEntity(
    playerId,
    entityId,
    entityType,
    entityDataJson,
    version,
    ApiSuccess,
    ApiError);
public void updateSharedEntity(
    String targetPlayerId,
    String entityId,
    String entityType,
    String jsonEntityData,
    int version,
    IServerCallback callback)
- (void)updateSharedEntity:(NSString *)entityId
            targetPlayerId:(NSString *)targetPlayerId
                entityType:(NSString *)entityType
            jsonEntityData:(NSString *)jsonEntityData
                   version:(int64_t)version
           completionBlock:(BCCompletionBlock)completionBlock
      errorCompletionBlock:(BCErrorCompletionBlock)ecb
                  cbObject:(BCCallbackObject)cbObject;
brainCloudClient.entity.updateSharedEntity = function(entityId, targetPlayerId, entityType, data, version, callback)
var playerId = "1234-1234-1234-1234"; //owner of the entity
var entityId = "1234-1234-1234-1234";
var entityType = "test";
var entityData = { "asdf" : "asdf23w" };
var acl = { "other" : 1 };
var version = 2;

var entityProxy = bridge.getEntityServiceProxy();
var retVal = entityProxy.updateSharedEntity(entityId, playerId, entityType, entityData, version);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entityId": "113db68a-48ad-4fc9-9f44-5fd36fc6445f",
        "entityType": "person",
        "version": 1,
        "data": {
            "name": "john",
            "age": 30
        },
        "acl": {
            "other": 0
        },
        "createdAt": 1395943044322,
        "updatedAt": 1395943044322
    }
}

Method updates a shared entity owned by another player. This operation results in the entity data being completely replaced by the passed in JSON string.

This method is affected by versioning. See the versioning documentation for more information.

Service Operation
"entity" "UPDATE_SHARED"
Method Parameters
Parameter Description
entityId The id of the entity to update
targetPlayerId The id of the entity's owner
entityType The entity type as defined by the user
jsonEntityData The entity's data object
Error returns
Code Name Description
40332 UPDATE_FAILED An update operation failed. Used for entities, global entities, and updates on the player.

Event

brainCloud Events allow communication of custom messages between brainCloud users. By using the brainCloud Event API you are able to send and receive event objects. These events can encapsulate anything you want by using the custom JSON data payload.

When an Event is sent to a user, they can receive it in one of two ways:

  1. By calling GetEvents which returns a list of all events sent to the authenticated user.
  2. Through the registered event callback*. When executing any API call in brainCloud, the returned JSON from the server may contain new events for the user. By registering for notification of these events using the callback, you can be informed when these "piggybacked" events arrive. See the BrainCloudClient RegisterEventCallback method for more details.

* Note requires the brainCloud Business Plan or higher. Additional bulk API counts apply. To enable Event callbacks for all API calls, enable the "Enable checking for Incoming Events with each API message" compatibility flag.

DeleteIncomingEvent

const char* evId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getEventService()->deleteIncomingEvent(evId, this);
string evId = "1234-1234-1234-1234";

BrainCloudClient.Instance.EventService.DeleteIncomingEvent(
    evId,
    ApiSuccess, ApiError);
public void deleteIncomingEvent(String evId, IServerCallback callback)
- (void)deleteIncomingEvent:(NSString *)evId
            completionBlock:(BCCompletionBlock)cb
       errorCompletionBlock:(BCErrorCompletionBlock)ecb
                   cbObject:(BCCallbackObject)cbObject;
brainCloudClient.event.deleteIncomingEvent = function(evId, callback)
var evId = "1234-1234-1234-1234";

var eventProxy = bridge.getEventServiceProxy();
var retVal = eventProxy.deleteIncomingEvent(evId);
Show Example JSON Return
{
    "status" : 200,
    "data" : null
}

Delete an event out of the player's incoming event queue.

Service Operation
"event" "DELETE_INCOMING"
Method Parameters
Parameter Description
evId The event ID

GetEvents

BrainCloudClient::getInstance()->getEventService()->getEvents(this);
BrainCloudClient.Instance.EventService.GetEvents(ApiSuccess, ApiError);
public void getEvents(IServerCallback callback)
- (void)getEvents:(BCCompletionBlock)cb
 errorCompletionBlock:(BCErrorCompletionBlock)ecb
             cbObject:(BCCallbackObject)cbObject;
brainCloudClient.event.getEvents = function(callback)
var eventProxy = bridge.getEventServiceProxy();
var retVal = eventProxy.getEvents();
Show Example JSON Return
{
    "status" : 200,
    "data" : null
}

Gets the events currently queued for the player.

Service Operation
"event" "GET_EVENTS"

SendEvent

const char* toPlayerId = "1234-1234-1234-1234";
const char* eventType = "test";
std::string eventData; // { "testData" : "test" }

BrainCloudClient::getInstance()->getEventService()->sendEvent(
    toPlayerId, eventType, eventData, this);
string toPlayerId = "1234-1234-1234-1234";
string eventType = "test";
string eventData; // { "testData" : "test" }

BrainCloudClient.Instance.EventService.SendEvent(
                toPlayerId,
                eventType,
                eventData,
                ApiSuccess, ApiError);
public void sendEvent(String toPlayerId, String eventType, String jsonEventData, IServerCallback callback)
- (void)sendEvent:(NSString *)toPlayerId
               eventType:(NSString *)eventType
           jsonEventData:(NSString *)eventData
         completionBlock:(BCCompletionBlock)cb
    errorCompletionBlock:(BCErrorCompletionBlock)ecb
                cbObject:(BCCallbackObject)cbObject;
brainCloudClient.event.sendEvent = function(toPlayerId, eventType, eventData, callback)
var toPlayerId = "1234-1234-1234-1234";
var eventType = "test";
var eventData = { "asdf": 1234 };

var eventProxy = bridge.getEventServiceProxy();
var retVal = eventProxy.sendEvent(toPlayerId, eventType, eventData);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "evId": "1234-1234-1234-1234"
    }
}

Sends an event to the designated player id with the attached JSON data.

Any events that have been sent to a player will show up in their incoming event queue.

Service Operation
"event" "SEND"
Method Parameters
Parameter Description
toPlayerId The id of the player who is being sent the event
eventType The user-defined type of the event.
eventData The user-defined data for this event encoded in JSON.

UpdateIncomingEventData

const char* evId = "1234-1234-1234-1234";
std::string eventData; // { "testData" : "test" }

BrainCloudClient::getInstance()->getEventService()->updateIncomingEventData(
    evId, eventData, this);
string evId = "1234-1234-1234-1234";
string eventData; // { "testData" : "test" }

BrainCloudClient.Instance.EventService.UpdateIncomingEventData(
                evId,
                eventData,
                ApiSuccess, ApiError);
public void updateIncomingEventData(String evId, String jsonEventData, IServerCallback callback)
- (void)updateIncomingEventData:(NSString *))evId
                  jsonEventData:(NSString *)eventData
                completionBlock:(BCCompletionBlock)cb
           errorCompletionBlock:(BCErrorCompletionBlock)ecb
                       cbObject:(BCCallbackObject)cbObject;
brainCloudClient.event.updateIncomingEventData = function(evId, eventData, callback)
var evId = "1234-1234-1234-1234";
var eventData = { "asdf": 1234 };

var eventProxy = bridge.getEventServiceProxy();
var retVal = eventProxy.updateIncomingEventData(evId, eventData);
Show Example JSON Return
{
    "status" : 200,
    "data" : null
}
Service Operation
"event" "UPDATE_EVENT_DATA"

Updates an event in the player's incoming event queue.

Method Parameters
Parameter Description
evId The event ID
eventData The user-defined data for this event encoded in JSON.

File

The File API allows brainCloud users to upload files to their individual accounts. These files can be private to the user, or shareable (public) where anyone with the URL can access the file.

Downloading Files

Downloading files is usually as simple as getting the file URL via the ListUserFiles API and downloading it via whatever method you decide on the platform you are working on. The brainCloud client does not have built in support for downloading files.

Shared Files

If the file you are downloading is shared publically (shareable = true) by the owner then there are no special steps required to download. Simply get the file URL and download.

Private Files

If the file you want to download is private, and therefor only accessible by the owner there is another step to successfully downloading the file. To ensure that the person downloading the file is the owner you must append an active Session ID from the file owner to the file URL as a query parameter.

To get the session ID simply call the GetSessionId method of the BrainCloudClient. Here is an example URL with the Session ID appended:

https://sharedprod.braincloudservers.com/downloader/bc/g/123465/u/fe32f00f-9eda-4047-83b1-120b3398b14b/f/TestFile.dat?sessionId=l92dmkua0aqvb4egtid3fn14n7

Summary

Managing Uploads
Monitoring Uploads
File Management
JavaScript Methods

CancelUpload

string myUploadId = "1234-1234-1234-1234" //From UploadFile return data

BrainCloudClient.Instance.FileService.CancelUpload(myUploadId);
const char* myUploadId = "1234-1234-1234-1234" //From UploadFile return data

BrainCloudClient::getInstance()->getFileService()->cancelUpload(myUploadId);
- (void) cancelUpload:(NSString *)uploadId;
 public void cancelUpload(String uploadId)
N/A
N/A

Method cancels an upload. If a File Upload Callback has been registered with the BrainCloudClient class, the fileUploadFailed callback method will be called once the upload has been canceled.

Method Parameters
Parameter Description
uploadId The id of the upload

DeleteUserFile

string cloudPath = "test/files";
string cloudFileName = "testCloudFile.dat";

BrainCloudClient.Instance.FileService.DeleteUserFile(
    cloudPath,
    cloudFileName,
    ApiSuccess, ApiError);
const char* cloudPath = "test/files";
const char* cloudFileName = "testCloudFile.dat";

BrainCloudClient::getInstance()->getFileService()->deleteUserFile(
    cloudPath, cloudFileName, this);
- (void)deleteUserFile:(NSString *)cloudPath
         cloudFilename:(NSString *)cloudFilename
       completionBlock:(BCCompletionBlock)cb
  errorCompletionBlock:(BCErrorCompletionBlock)ecb
              cbObject:(BCCallbackObject)cbObject;
public void deleteUserFile(String cloudPath, String cloudFilename, IServerCallback callback)
brainCloudClient.file.deleteUserFile = function(cloudPath, cloudFilename, callback)
var cloudPath = "test/data";
var cloudFilename = "testFile";

var fileProxy = bridge.getFileServiceProxy();
var retVal = fileProxy.deleteUserFile(cloudPath, cloudFilename);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "fileDetails": {
            "updatedAt": 1452616408147,
            "fileSize": 100,
            "fileType": "User",
            "expiresAt": 1452702808146,
            "shareable": true,
            "uploadId": "cf9a075c-587e-4bd1-af0b-eab1a79b958f",
            "createdAt": 1452616408147,
            "profileId": "bf8a1433-62d2-448e-b396-f3dbffff44",
            "gameId": "99999",
            "path": "dir1/dir2",
            "filename": "filename",
            "replaceIfExists": true,
            "cloudPath": "bc/g/99999/u/bf8a1433-62d2-448e-b396-f3dbffff44/f/dir1/dir2/filename"
        }
    }
}

Deletes a single user file.

Service Operation
"file" "DELETE_USER_FILE"
Method Parameters
Parameter Description
cloudPath File path
cloudFilename Name of file
Error returns
Code Name Description
40431 CLOUD_STORAGE_SERVICE_ERROR Cloud storage service error
40432 FILE_DOES_NOT_EXIST File does not exist

DeleteUserFiles

string cloudPath = "test/files"

BrainCloudClient.Instance.FileService.DeleteUserFiles(
    cloudPath,
    true,
    ApiSuccess, ApiError);
const char* cloudPath = "test/files";
bool recursive = true;

BrainCloudClient::getInstance()->getFileService()->deleteUserFiles(
    cloudPath, recursive, this);
- (void)deleteUserFiles:(NSString *)cloudPath
                recurse:(bool)recurse
        completionBlock:(BCCompletionBlock)cb
   errorCompletionBlock:(BCErrorCompletionBlock)ecb
               cbObject:(BCCallbackObject)cbObject;
public void deleteUserFiles(String cloudPath, boolean recurse, IServerCallback callback)
brainCloudClient.file.deleteUserFiles = function(cloudPath, recurse, callback)
var cloudPath = "test/data";
var recurse = true;

var fileProxy = bridge.getFileServiceProxy();
var retVal = fileProxy.deleteUserFiles(cloudPath, recurse);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "fileList": [
            {
                "updatedAt": 1452603368201,
                "uploadedAt": null,
                "fileSize": 85470,
                "shareable": true,
                "createdAt": 1452603368201,
                "profileId": "bf8a1433-62d2-448e-b396-f3dbffff44",
                "gameId": "99999",
                "path": "test2",
                "filename": "testup.dat",
                "downloadUrl": "https://sharedprod.braincloudservers.com/s3/bc/g/99999/u/bf8f44/f/test2/testup.dat",
                "cloudLocation": "bc/g/99999/u/bf8f44/f/test2/testup.dat"
            }
        ]
    }
}

Deletes multiple user files.

Service Operation
"file" "DELETE_USER_FILES"
Method Parameters
Parameter Description
cloudPath File path
recurse Whether to recurse into sub-directories
Error returns
Code Name Description
40431 CLOUD_STORAGE_SERVICE_ERROR Cloud storage service error

GetCDNUrl

string cloudPath = "test/files";
string cloudFileName = "testCloudFile.dat";

BrainCloudClient.Instance.FileService.GetCDNUrl(
    cloudPath,
    cloudFileName,
    ApiSuccess, ApiError);
const char* cloudPath = "test/files";
const char* cloudFileName = "testCloudFile.dat";

BrainCloudClient::getInstance()->getFileService()->getCDNUrl(
    cloudPath, cloudFileName, this);
- (void)getCDNUrl:(NSString *)cloudPath
         cloudFilename:(NSString *)cloudFilename
       completionBlock:(BCCompletionBlock)cb
  errorCompletionBlock:(BCErrorCompletionBlock)ecb
              cbObject:(BCCallbackObject)cbObject;
String cloudPath = "test/files";
String cloudFileName = "testCloudFile.dat";

BrainCloudClient.getInstance().getFileService().getCDNUrl(
    cloudPath, cloudFileName, this);
brainCloudClient.file.getCDNUrl = function(cloudPath, cloudFilename, callback)
var cloudPath = "test/data";
var cloudFilename = "test";

var fileProxy = bridge.getFileServiceProxy();
var retVal = fileProxy.getCDNUrl(cloudPath, cloudFilename);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "appServerUrl": "https://internal.braincloudservers.com/...f434b1db538b/f/uploadsimplefile.txt",
        "cdnUrl": "https://d2b6zwnvr1nyug.cloudfront.net/bc/g/20001/u/107b3aa9-0d9f-4e90-af..."
    }
}

Returns the CDN url for a file object

Service Operation
"file" "GET_CDN_URL"
Method Parameters
Parameter Description
cloudPath File path
cloudFilename Name of file
Error returns
Code Name Description
40431 CLOUD_STORAGE_SERVICE_ERROR Cloud storage service error
40432 FILE_DOES_NOT_EXIST File does not exist

GetUploadBytesTransferred

string myUploadId = "1234-1234-1234-1234" //From UploadFile return data

int bytes = BrainCloudClient.Instance.FileService.GetUploadBytesTransferred(myUploadId);
const char* myUploadId = "1234-1234-1234-1234" //From UploadFile return data

int64_t bytes = BrainCloudClient::getInstance()->getFileService()->
    getUploadBytesTransferred(myUploadId);
- (void) getUploadBytesTransferred:(NSString *)uploadId;
public void deleteUserFiles(String cloudPath, Boolean recurse, IServerCallback callback)
N/A
N/A

Returns the number of bytes uploaded or -1 if upload not found.

Method Parameters
Parameter Description
uploadId The id of the upload

GetUploadProgress

string myUploadId = "1234-1234-1234-1234" //From UploadFile return data

double progress = BrainCloudClient.Instance.FileService.GetUploadProgress(myUploadId);
const char* myUploadId = "1234-1234-1234-1234" //From UploadFile return data

double progress = BrainCloudClient::getInstance()->getFileService()->getUploadProgress(myUploadId);
- (void) getUploadProgress:(NSString *)uploadId;
public double getUploadProgress(String uploadId)
N/A
N/A

Returns the progress of the given upload from 0.0 to 1.0 or -1 if upload not found.

Method Parameters
Parameter Description
uploadId The id of the upload

GetUploadTotalBytesToTransfer

string myUploadId = "1234-1234-1234-1234" //From UploadFile return data

int bytes = BrainCloudClient.Instance.FileService.GetUploadTotalBytesToTransfer(myUploadId);
const char* myUploadId = "1234-1234-1234-1234" //From UploadFile return data

int64_t bytes = BrainCloudClient::getInstance()->getFileService()->
    getUploadTotalBytesToTransfer(myUploadId);
- (void) getUploadTotalBytesToTransfer:(NSString *)uploadId;
public void cancelUpload(String uploadId)
N/A
N/A

Returns the total number of bytes that will be uploaded or -1 if upload not found.

Method Parameters
Parameter Description
uploadId The id of the upload

ListUserFiles

BrainCloudClient.Instance.FileService.ListUserFiles(ApiSuccess, ApiError);

//or
string cloudPath = "test/files/"
bool recursive = true;

BrainCloudClient.Instance.FileService.ListUserFiles(cloudPath, recursive, ApiSuccess, ApiError);
BrainCloudClient::getInstance()->getFileService()->listUserFiles(this);

//or
const char* cloudPath = "test/files/"
bool recursive = true;

BrainCloudClient::getInstance()->getFileService()->listUserFiles(cloudPath, recursive, this);
- (void)listUserFiles:(NSString *)cloudPath
              recurse:(bool)recurse
     completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
            cbObject:(BCCallbackObject)cbObject;
public void listUserFiles(String cloudPath, boolean recurse, IServerCallback callback)
brainCloudClient.file.listUserFiles = function(cloudPath, recurse, callback)
var cloudPath = "test/data";
var recurse = true;

var fileProxy = bridge.getFileServiceProxy();
var retVal = fileProxy.listUserFiles(cloudPath, recurse);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "fileList": [
            {
                "updatedAt": 1452603368201,
                "uploadedAt": null,
                "fileSize": 85470,
                "shareable": true,
                "createdAt": 1452603368201,
                "profileId": "bf8a1433-62d2-448e-b396-f3dbffff44",
                "gameId": "99999",
                "path": "test2",
                "filename": "testup.dat",
                "downloadUrl": "https://sharedprod.braincloudservers.com/s3/bc/g/99999/u/bf8f44/f/test2/testup.dat",
                "cloudLocation": "bc/g/99999/u/bf8f44/f/test2/testup.dat"
            }
        ]
    }
}

List all user files

Service Operation
"file" "LIST_USER_FILES"
Method Parameters
Parameter Description
cloudPath File path
recurse Whether to recurse into sub-directories

PrepareFileUpload (JS only)

N/A
N/A
N/A
N/A
var shareable = true;
var replaceIfExists = true;
var file = document.getElementById('fileToUpload').files[0];
var fileSize = file.size;

brainCloudClient.file.prepareFileUpload(
            "cloudPath", "cloudFilename", shareable, replaceIfExists, fileSize,
            function(result) {
                if (result.status == 200) {
                    var uploadId = result.data.fileDetails.uploadId;
                    brainCloudClient.file.uploadFile(xhr, file, uploadId);
                }
            }
        );
N/A
Show Example JSON Return
{
    "status":200,
    "data":{
        "fileDetails":{
            "updatedAt":1452616408147,
            "fileSize":100,
            "fileType":"User",
            "expiresAt":1452702808146,
            "shareable":true,
            "uploadId":"cf9a075c-587e-4bd1-af0b-eab1a79b958f",
            "createdAt":1452616408147,
            "profileId":"bf8a1433-62d2-448e-b396-f3dbffff44",
            "gameId":"99999",
            "path":"dir1/dir2",
            "filename":"filename",
            "replaceIfExists":true,
            "cloudPath":"bc/g/99999/u/bf8a1433-62d2-448e-b396-f3dbffff44/f/dir1/dir2/filename"
        }
    }
}

Prepares a user file upload. On success an uploadId will be returned which can be used to upload the file using the brainCloudClient.file.uploadFile method.

Service Operation
"file" "PREPARE_USER_UPLOAD"
Method Parameters
Parameter Description
cloudPath The desired cloud path of the file
cloudFilename The desired cloud fileName of the file
shareable True if the file is shareable
replaceIfExists Whether to replace file if it exists
fileSize The size of the file in bytes
Error returns
Code Name Description
40429 UPLOAD_FILE_TOO_LARGE File maximum file size exceeded
40430 FILE_ALREADY_EXISTS File exists, replaceIfExists not set

UploadFile

BrainCloudClient::getInstance()->registerFileUploadCallback(this);

const char* cloudPath = "test/files/"
const char* cloudName = "testCloudFile.dat"
bool overwrite = true;
bool share = true;
const char* localPath = "path/to/my/file.dat";

BrainCloudClient::getInstance()->getFileService()->uploadFile(
    cloudPath,
    cloudName,
    share,
    overwrite,
    localPath,
    this);
BrainCloudClient.Instance.RegisterFileUploadCallbacks(FileCallbackSuccess, FileCallbackFail);

string cloudPath = "test/files/"
string cloudName = "testCloudFile.dat"
bool overwrite = true;
bool share = true;
string localPath = "path/to/my/file.dat";

BrainCloudClient.Instance.FileService.UploadFile(
    cloudPath,
    cloudName,
    share,
    overwrite,
    localPath,
    ApiSuccess, ApiError);
public Boolean uploadFile(String cloudPath,
                   String cloudFilename,
                   boolean shareable,
                   boolean replaceIfExists,
                   String localPath,
                   IServerCallback callback)
- (bool)uploadFile:(NSString *)cloudPath
     cloudFilename:(NSString *)cloudFilename
         shareable:(bool)shareable
   replaceIfExists:(bool)replaceIfExists
         localPath:(NSString *)localPath
   completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
          cbObject:(BCCallbackObject)cbObject;
brainCloudClient.file.prepareFileUpload = function(cloudPath, cloudFilename, shareable, replaceIfExists, fileSize, callback)
var cloudPath = "test/files/"
var cloudName = "testCloudFile.dat"
var overwrite = true;
var share = true;
var localPath = "path/to/my/file.dat";

var fileProxy = bridge.getFileServiceProxy();
var retVal = fileProxy.prepareFileUpload(cloudPath, cloudName, overwrite, share, localPath);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "fileDetails": {
            "updatedAt": 1452616408147,
            "fileSize": 100,
            "fileType": "User",
            "expiresAt": 1452702808146,
            "shareable": true,
            "uploadId": "cf9a075c-587e-4bd1-af0b-eab1a79b958f",
            "createdAt": 1452616408147,
            "profileId": "bf8a1433-62d2-448e-b396-f3dbffff44",
            "gameId": "99999",
            "path": "dir1/dir2",
            "filename": "filename",
            "replaceIfExists": true,
            "cloudPath": "bc/g/99999/u/bf8a1433-62d2-448e-b396-f3dbffff44/f/dir1/dir2/filename"
        }
    }
}

Prepares a user file upload. On success the file will begin uploading to the brainCloud server.

To be informed of success/failure of the upload register the File Upload Callbacks with the BrainCloudClient class.

Service Operation
"file" "PREPARE_USER_UPLOAD"
Method Parameters
Parameter Description
cloudPath The desired cloud path of the file
cloudFilename The desired cloud fileName of the file
shareable True if the file is shareable
replaceIfExists Whether to replace file if it exists
localPath The path and fileName of the local file
Error returns
Code Name Description
40429 UPLOAD_FILE_TOO_LARGE File maximum file size exceeded
40430 FILE_ALREADY_EXISTS File exists, replaceIfExists not set

UploadFile (JS only)

N/A
N/A
N/A
N/A
var shareable = true;
var replaceIfExists = true;
var file = document.getElementById('fileToUpload').files[0];
var fileSize = file.size;

brainCloudClient.file.prepareFileUpload(
            "cloudPath", "cloudFilename", shareable, replaceIfExists, fileSize,
            function(result) {
                if (result.status == 200) {
                    var uploadId = result.data.fileDetails.uploadId;
                    brainCloudClient.file.uploadFile(xhr, file, uploadId);
                }
            }
        );
N/A
Show Example JSON Return
{
    "status":200,
    "data":{
        "fileDetails":{
            "updatedAt":1452616408147,
            "fileSize":100,
            "fileType":"User",
            "expiresAt":1452702808146,
            "shareable":true,
            "uploadId":"cf9a075c-587e-4bd1-af0b-eab1a79b958f",
            "createdAt":1452616408147,
            "profileId":"bf8a1433-62d2-448e-b396-f3dbffff44",
            "gameId":"99999",
            "path":"dir1/dir2",
            "filename":"filename",
            "replaceIfExists":true,
            "cloudPath":"bc/g/99999/u/bf8a1433-62d2-448e-b396-f3dbffff44/f/dir1/dir2/filename"
        }
    }
}

Method uploads the supplied file to the brainCloud server. Note that you must call prepareFileUpload to retrieve the uploadId before calling this method. It is assumed that any methods required to monitor the file upload including progress, and completion are attached to the XMLHttpRequest xhr object's events such as:

On a 200 http status, the JSON return is available from XMLHttpRequest.responseText

Service Operation
"file" "UPLOAD_FILE"
Method Parameters
Parameter Description
xhr The XMLHttpRequest object that the brainCloud client will use to upload the file
file The file object
uploadId The upload id obtained via prepareFileUpload()
Error returns

The XMLHttpRequest object will return a 200 http status if the upload is successful.

Friend

Friends in brainCloud are other users (i.e. players) that you want to share your user experience with. Friends may be existing connections from a social network (i.e. Facebook), or social connections that you make that are specific to the app and managed by brainCloud.

brainCloud can help to manage these friends - and use them for the basis of higher-level features such as social leaderboards.

The methods of this service fall into the following categories:

Friend Management
Player Lookup
Friend Data Access

Summary Friend Data (also referred to as simply Friend Data) is special game summary data that is made available to a player's friends. This is normally used to provide additional information for use in social leaderboards and/or neighbor displays. Common examples of friend data include experience level, player level title, etc. Summary Friend data is updated via the UpdateSummaryFriendData method.

AddFriends

std::vector<std::string> friendIds;
friendIds.push_back("1234-1234-1234-1234");

BrainCloudClient::getInstance()->getFriendService()->addFriends(friendIds, this);
string[] friendIds = { "1234-1234-1234-1234", "1234-1234-1234-1234" };

BrainCloudClient.Instance.FriendService.AddFriends(
    friendIds,
    ApiSuccess, ApiError);
public void addFriends(String[] profileIds, IServerCallback callback)
- (void)addFriends:(NSArray *)profileIds
         completionBlock:(BCCompletionBlock)cb
    errorCompletionBlock:(BCErrorCompletionBlock)ecb
                cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.addFriends = function(profileIds, callback)
var playerIds = [ "1234-1234-1234-1234", "1234-1234-1234-1234" ];

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.addFriends(playerIds);
Show Example JSON Return
{
    "status": 200,
    "data": null
}

Links the current player and the specified players as brainCloud friends.

Service Operation
"friend" "ADD_FRIENDS"
Method Parameters
Parameter Description
profileIds Collection of player IDs.

FindPlayerByUniversalId

BrainCloudClient::getInstance()->getFriendService()->findPlayerByUniversalId(
    "searchText", 10, this);
BrainCloudClient.Instance.FriendService.FindPlayerByUniversalId(
    "searchText",
    10,
    ApiSuccess, ApiError);
public void findPlayerByUniversalId(String searchText, int maxResults, IServerCallback callback)
- (void)findPlayerByUniversalId:(NSString *)searchText
                     maxResults:(int)maxResults
                completionBlock:(BCCompletionBlock)cb
           errorCompletionBlock:(BCErrorCompletionBlock)ecb
                       cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.findPlayerByUniversalId = function(searchText, maxResults, callback)
var searchText = "partialId";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.findPlayerByUniversalId(searchText, 20);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "matches": [
            {
                "profileId": "4f2edc69-b3c3-458b-8b4b-6bbd7259b55f",
                "profileName": "Test2",
                "playerSummaryData": null,
                "pictureUrl": "http://somesite.com/test/picture.jpg",
                "externalId": "MyUniversalId"
            },
            {
                "profileId": "0da5ad24-2341-42f8-acb5-57aa2dd4ae94",
                "profileName": "Test1",
                "playerSummaryData": null,
                "pictureUrl": "http://somesite.com/test/picture.jpg",
                "externalId": "MyUniversalId"
            }
        ],
        "matchedCount": 2
    }
}

Retrieves profile information for the partial Universal ID matches of the specified text.

Does not require the calling user to be a friend of the retrieved users.

Service Operation
"friend" "FIND_PLAYER_BY_UNIVERSAL_ID"
Method Parameters
Parameter Description
searchText The substring to search for. Minimum length of 3 characters.
maxResults Maximum number of results to return. If there are more the message

FindUsersByExactName

BrainCloudClient::getInstance()->getFriendService()->findUsersByExactName(
    "searchText", 10, this);
BrainCloudClient.Instance.FriendService.FindUsersByExactName(
    "searchText",
    10,
    ApiSuccess, ApiError);
public void findUsersByExactName(String searchText, int maxResults, IServerCallback callback)
- (void)findUsersByExactName:(NSString *)searchText
              maxResults:(int)maxResults
         completionBlock:(BCCompletionBlock)cb
    errorCompletionBlock:(BCErrorCompletionBlock)ecb
                cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.findUsersByExactName = function(searchText, maxResults, callback)
var searchText = "partialName";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.findUsersByExactName(searchText, 20);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "matches": [
            {
                "profileId": "4f2edc69-b3c3-458b-8b4b-6bbd7259b55f",
                "profileName": "Test2",
                "playerSummaryData": null,
                "pictureUrl": "http://somesite.com/test/picture.jpg"
            },
            {
                "profileId": "0da5ad24-2341-42f8-acb5-57aa2dd4ae94",
                "profileName": "Test1",
                "playerSummaryData": null,
                "pictureUrl": "http://somesite.com/test/picture.jpg"
            }
        ],
        "matchedCount": 2
    }
}

Retrieves profile information for the exact matches of the specified text.

If there are more results than the maximum requested, then maximum requested results are returned.

Does not require the calling user to be a friend of the retrieved users.

Service Operation
"friend" "FIND_USER_BY_EXACT_NAME"
Method Parameters
Parameter Description
searchText The substring to search for. Minimum length of 3 characters.
maxResults Maximum number of results to return.

FindUsersBySubstrName

BrainCloudClient::getInstance()->getFriendService()->findUsersBySubstrName(
    "searchText", 10, this);
BrainCloudClient.Instance.FriendService.FindUsersBySubstrName(
    "searchText",
    10,
    ApiSuccess, ApiError);
public void findUsersBySubstrName(String searchText, int maxResults, IServerCallback callback)
- (void)findUsersBySubstrName:(NSString *)searchText
              maxResults:(int)maxResults
         completionBlock:(BCCompletionBlock)cb
    errorCompletionBlock:(BCErrorCompletionBlock)ecb
                cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.findUsersBySubstrName = function(searchText, maxResults, callback)
var searchText = "partialName";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.findUsersBySubstrName(searchText, 20);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "matches": [
            {
                "profileId": "4f2edc69-b3c3-458b-8b4b-6bbd7259b55f",
                "profileName": "Test2",
                "playerSummaryData": null,
                "pictureUrl": "http://somesite.com/test/picture.jpg"
            },
            {
                "profileId": "0da5ad24-2341-42f8-acb5-57aa2dd4ae94",
                "profileName": "Test1",
                "playerSummaryData": null,
                "pictureUrl": "http://somesite.com/test/picture.jpg"
            }
        ],
        "matchedCount": 2
    }
}

Retrieves profile information for the partial matches of the specified text.

If there are more results than the maximum requested, then maximum requested results are returned.

Does not require the calling user to be a friend of the retrieved users.

Service Operation
"friend" "FIND_USER_BY_SUBSTR_NAME"
Method Parameters
Parameter Description
searchText The substring to search for. Minimum length of 3 characters.
maxResults Maximum number of results to return.

FindUsersByUserSummary

BrainCloudClient::getInstance()->getFriendService()->findUsersByUserSummary(
    "searchText", 10, this);
BrainCloudClient.Instance.FriendService.FindUsersByUserSummary(
    "searchText",
    10,
    ApiSuccess, ApiError);
public void findUsersByUserSummary(String searchText, int maxResults, IServerCallback callback)
- (void)findUsersByUserSummary:(NSString *)searchText
              maxResults:(int)maxResults
         completionBlock:(BCCompletionBlock)cb
    errorCompletionBlock:(BCErrorCompletionBlock)ecb
                cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.findUsersByUserSummary = function(searchText, maxResults, callback)
var searchText = "partialName";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.findUsersByUserSummary(searchText, 20);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "matches": [
            {
                "profileId": "4f2edc69-b3c3-458b-8b4b-6bbd7259b55f",
                "profileName": "Test2",
                "playerSummaryData": null,
                "pictureUrl": "http://somesite.com/test/picture.jpg"
            },
            {
                "profileId": "0da5ad24-2341-42f8-acb5-57aa2dd4ae94",
                "profileName": "Test1",
                "playerSummaryData": null,
                "pictureUrl": "http://somesite.com/test/picture.jpg"
            }
        ],
        "matchedCount": 2
    }
}

Retrieves profile information based on the search criteria of the user summary data.

If there are more results than the maximum requested, then maximum requested results are returned.

Does not require the calling user to be a friend of the retrieved users.

Service Operation
"friend" "FIND_USERS_BY_USER_SUMMARY"
Method Parameters
Parameter Description
where Mongo style query string
maxResults Maximum number of results to return.

GetExternalIdForProfileId

const char * profileId = "1234-1234-1234-1234";
const char * authType = "Facebook";

BrainCloudClient::getInstance()->getFriendService()->getExternalIdForProfileId(
    profileId, authType, this);
string profileId = "1234-1234-1234-1234";
string authType = "Facebook";

BrainCloudClient.Instance.FriendService.GetExternalIdForProfileId(
    friendId,
    authType,
    ApiSuccess,
    ApiError);
public void getExternalIdForProfileId(String profileId, String authenticationType, IServerCallback callback)
- (void) getExternalIdForProfileId:(NSString *)profileId
                authenticationType:(NSString *)authenticationType
                   completionBlock:(BCCompletionBlock)cb
              errorCompletionBlock:(BCErrorCompletionBlock)ecb
                          cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.getExternalIdForProfileId = function(profileId, authenticationType, callback)
var profileId = "1234-1234-1234-1234";
var authenticationType = "Facebook";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.getExternalIdForProfileId(profileId);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "externalId": "19e1c0cf-9a2d-4d5c-9a71-1b0f6b309b4b"
    }
}

Retrieves the external ID for the specified user profile ID on the specified social platform.

Does not require the calling user to be a friend of the other user.

Service Operation
"friend" "GET_EXTERNAL_ID_FOR_PROFILE_ID"
Method Parameters
Parameter Description
profileId Profile (player) ID.
authenticationType Associated authentication type. Full list of types can be found here.

GetProfileInfoForCredential

const char * userId = "someExternalId";
AuthenticationType authType = AuthenticationType::Facebook;

BrainCloudClient::getInstance()->getFriendService()->getProfileInfoForCredential(
    userId, authType, this);
string userId = "someExternalId";
AuthenticationType authType = AuthenticationType.Facebook;

BrainCloudClient.Instance.FriendService.GetProfileInfoForCredential(
    userId,
    authType,
    ApiSuccess,
    ApiError);
public void getProfileInfoForCredential(String externalId, AuthenticationType authenticationType, IServerCallback callback)
- (void)getProfileInfoForCredential:(NSString *)externalId
                        authenicationType:(NSString *)authenticationType
                          completionBlock:(BCCompletionBlock)cb
                     errorCompletionBlock:(BCErrorCompletionBlock)ecb
                                 cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.getProfileInfoForCredential = function(externalId, authenticationType, callback)
var externalId = "someId";
var authenticationType = "Facebook";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.getProfileInfoForCredential(externalId, authenticationType);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "playerName": "",
        "email": null,
        "playerId": "bb05182d-ff0c-4740-ae65-482751e74949",
        "playerSummaryData": {
            "LEVEL": 7
        }
    }
}

Retrieves profile information for the specified user.

Does not require the calling user to be a friend of the other user.

Service Operation
"friend" "GET_PROFILE_INFO_FOR_CREDENTIAL"
Method Parameters
Parameter Description
externalId External identifier.
authenticationType Associated authentication type. Full list of types can be found here.

GetProfileInfoForExternalAuthId

const char * friendId = "someExternalId";
const char * externalAuthType = "Facebook";

BrainCloudClient::getInstance()->getFriendService()->getProfileInfoForExternalAuthId(
    friendId, externalAuthType, this);
string friendId = "someExternalId";
string externalAuthType = "someAuth";

BrainCloudClient.Instance.FriendService.GetProfileInfoForExternalAuthId(
    friendId,
    authType,
    ApiSuccess,
    ApiError);
public void getProfileInfoForExternalAuthId(String externalId, String externalAuthType, IServerCallback callback)
- (void)getProfileInfoForExternalAuthId:(NSString *)externalId
                        externalAuthType:(NSString *)externalAuthType
                          completionBlock:(BCCompletionBlock)cb
                     errorCompletionBlock:(BCErrorCompletionBlock)ecb
                                 cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.getProfileInfoForExternalAuthId = function(externalId, externalAuthType, callback)
var externalId = "someId";
var externalAuthType = "someAuth";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.getProfileInfoForExternalAuthId(externalId, externalAuthType);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "playerName": "",
        "email": null,
        "playerId": "bb05182d-ff0c-4740-ae65-482751e74949",
        "playerSummaryData": {
            "LEVEL": 7
        }
    }
}

Retrieves profile information for the specified external auth user.

Does not require the calling user to be a friend of the other user.

Service Operation
"friend" "GET_PROFILE_INFO_FOR_EXTERNAL_AUTH_ID"
Method Parameters
Parameter Description
externalId External identifier
externalAuthType The external authentication type used for this friend's external ID

GetSummaryDataForProfileId

const char* profileId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getFriendService()->getSummaryDataForProfileId(
    profileId, this);
string profileId = "1234-1234-1234-1234";

BrainCloudClient.Instance.FriendService.GetSummaryDataForProfileId(
    profileId, callback, errorCallback, null);
String profileId = "1234-1234-1234-1234";

BrainCloudClient.getInstance()->getFriendService()->getSummaryDataForProfileId(
    profileId, this);
- (void)getSummaryDataForProfileId:(NSString *)profileId
                   completionBlock:(BCCompletionBlock)cb
              errorCompletionBlock:(BCErrorCompletionBlock)ecb
                          cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.getSummaryDataForProfileId = function(profileId, callback)
var profileId = "1234-1234-1234-1234";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.getSummaryDataForProfileId(profileId);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "pictureUrl": "https://scontent.xx.fbcdn.net/hprofile-frc1/v/t1.0-1/p50x50/1066&oe=57812708",
        "email": null,
        "profileId": "2d77sf92-2583-4ad2-ba2c-3db942a34dee",
        "playerSummaryData": {
            "LEVEL": 0
        },
        "profileName": "Test User"
    }
}

Retrieves the summary information for the specified user profile ID.

Does not require the calling user to be a friend of the other user.

Service Operation
"friend" "GET_SUMMARY_DATA_FOR_PROFILE_ID"
Method Parameters
Parameter Description
profileId Profile (player) ID.

GetUsersOnlineStatus

std::vector<std::string> userdIds;
userdIds.push_back("1234-1234-1234-1234");

BrainCloudClient::getInstance()->getFriendService()->getUsersOnlineStatus(userdIds, this);
string[] userdIds = { "1234-1234-1234-1234", "1234-1234-1234-1234" };

BrainCloudClient.Instance.FriendService.GetUsersOnlineStatus(
    userdIds,
    ApiSuccess, ApiError);
public void getUsersOnlineStatus(String[] profileIds, IServerCallback callback)
- (void)getUsersOnlineStatus:(NSArray *)profileIds
             completionBlock:(BCCompletionBlock)cb
        errorCompletionBlock:(BCErrorCompletionBlock)ecb
                    cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.getUsersOnlineStatus = function(profileIds, callback)
var profileIds = [ "1234-1234-1234-1234", "1234-1234-1234-1234" ];

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.getUsersOnlineStatus(profileIds);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "onlineStatus": [
            {
                "isOnline": false,
                "profileId": "d841da61-a49c-43f4-9937-a97339ccf0ec",
                "userValid": true
            }
        ]
    }
}

Get the online status for a list of users based on profile ID.

Does not require the calling user to be a friend of the other user.

Service Operation
"friend" "GET_USERS_ONLINE_STATUS"
Method Parameters
Parameter Description
profileIds Collection of profile IDs.

ListFriends

BrainCloudClient::getInstance()->getFriendService()->listFriends(
    FriendPlatform::Facebook, false, this);
BrainCloudClient.Instance.FriendService.ListFriends(
    FriendPlatform.Facebook,
    false,
    ApiSuccess, ApiError);
public void listFriends(FriendPlatform friendPlatform, Boolean includeSummaryData, IServerCallback callback)
- (void)listFriends:(FriendPlatformObjc *)friendPlatform
      includeSummaryData:(bool)includeSummaryData
         completionBlock:(BCCompletionBlock)cb
    errorCompletionBlock:(BCErrorCompletionBlock)ecb
                cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.listFriends = function(friendPlatform, includeSummaryData, callback)
var platform = "Facebook";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.listFriends(platform, true);
Show Example JSON Return
// Example 1: for friendPlatform = All
{
    "status": 200,
    "data": {
        "friends": [
            {
                "externalData": {
                    "Facebook": {
                        "pictureUrl": "https://scontent.xx.fbcdn.net/hprofile-xfp1/v/t1.0-1/p50x50/XXX.jpg?oh=YYY&oe=ZZZ",
                        "name": "scientist at large",
                        "externalId": "100003668521730"
                    },
                    "brainCloud": {}
                },
                "playerId": "1aa3428c-5877-4624-a909-f2b1af931f00",
                "name": "Mr. Peabody",
                "summaryFriendData": {
                    "LEVEL": -4
                },
                "pictureUrl": "www.exampleurl.com"
            },
            {
                "externalData": {
                    "Facebook": {
                        "pictureUrl": "https://scontent.xx.fbcdn.net/hprofile-xfa1/v/t1.0-1/c0.11.50.50/p50x50/3AAA.jpg?oh=BBBa&oe=CCC",
                        "name": "Aquaman",
                        "externalId": "100003509724516"
                    }
                },
                "playerId": "1598c5b6-1b09-431b-96bc-9c2c928cad3b",
                "name": null,
                "summaryFriendData": {
                    "LEVEL": 1
                },
                "pictureUrl": "www.exampleurl.com"
            }
        ],
        "server_time": 1458224807855
    }
}

// Example 2: for friendPlatform = Facebook
{
    "status": 200,
    "data": {
        "friends": [
            {
                "externalData": {
                    "Facebook": {
                        "pictureUrl": "https://scontent.xx.fbcdn.net/hprofile-xfp1/v/t1.0-1/p50x50/XXX.jpg?oh=YYY&oe=ZZZ",
                        "name": "scientist at large",
                        "externalId": "100003668521730"
                    }
                },
                "playerId": "1aa3428c-5877-4624-a909-f2b1af931f00",
                "name": "Mr. Peabody",
                "summaryFriendData": {
                    "LEVEL": -4
                }
            },
            {
                "externalData": {
                    "Facebook": {
                        "pictureUrl": "https://scontent.xx.fbcdn.net/hprofile-xfa1/v/t1.0-1/c0.11.50.50/p50x50/3AAA.jpg?oh=BBBa&oe=CCC",
                        "name": "Aquaman",
                        "externalId": "100003509724516"
                    }
                },
                "playerId": "1598c5b6-1b09-431b-96bc-9c2c928cad3b",
                "name": null,
                "summaryFriendData": {
                    "LEVEL": 1
                }
            }
        ],
        "server_time": 1458224807855
    }
}

Retrieves a list of player and friend platform information for all friends of the current player.

Service Operation
"friend" "LIST_FRIENDS"
Method Parameters
Parameter Description
friendPlatform Friend platform to query.
includeSummaryData True if including summary data; false otherwise.

ReadFriendEntity

const char * entityId = "1234-1234-1234-1234";
const char * friendId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getFriendService()->readFriendEntity(
    entityId, friendId, this);
string entityId = "1234-1234-1234-1234";
string friendId = "1234-1234-1234-1234";

BrainCloudClient.Instance.FriendService.ReadFriendEntity(
    entityId,
    friendId,
    ApiSuccess,
    ApiError);
public void readFriendEntity(String friendId, String entityId, IServerCallback callback)
- (void)readFriendEntity:(NSString *)entityId
                friendId:(NSString *)friendId
         completionBlock:(BCCompletionBlock)cb
    errorCompletionBlock:(BCErrorCompletionBlock)ecb
                cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.readFriendEntity = function(friendId, entityId, callback)
var entityId = "1234-1234-1234-1234";
var friendId = "1234-1234-1234-1234";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.readFriendEntity(entityId, friendId);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "entityId": "a3abc2ad-13ee-47a8-86a5-9c0a83f90314",
        "entityType": "PlayerData",
        "version": 1,
        "data": {
            "ACCOUNT_CREATION_TIME": 1353011574029,
            "ALL_TIME_SCORE": 1090560,
            "FIRST_PLAY_TIME": 1372781536842
        },
        "acl": {
            "other": 1
        },
        "createdAt": 1372901559406,
        "updatedAt": 1372901559406
    }
}

Returns a particular entity of a particular friend.

Service Operation
"friend" "READ_FRIEND_ENTITY"
Method Parameters
Parameter Description
entityId Id of entity to retrieve.
friendId Profile Id of friend who owns entity.

ReadFriendPlayerState

const char * friendId = "1234-1234-1234-1234";

BrainCloudClient::getInstance()->getFriendService()->readFriendPlayerState(
    friendId, this);
string friendId = "1234-1234-1234-1234";

BrainCloudClient.Instance.FriendService.ReadFriendPlayerState(
    friendId,
    ApiSuccess,
    ApiError);
public void readFriendPlayerState(String friendId, IServerCallback callback)
- (void)readFriendPlayerState:(NSString *)friendId
              completionBlock:(BCCompletionBlock)cb
         errorCompletionBlock:(BCErrorCompletionBlock)ecb
                     cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.readFriendPlayerState = function(friendId, callback)
var friendId = "1234-1234-1234-1234";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.readFriendPlayerState(friendId);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "vcPurchased": 0,
        "xpCapped": false,
        "experiencePoints": 9796,
        "playerName": "",
        "vcClaimed": 0,
        "parentProfileId": null,
        "countryCode": null,
        "loginCount": 106,
        "server_time": 1449863680011,
        "experienceLevel": 11,
        "entities": [
            {
                "entityId": "a3abc2ad-13ee-47a8-86a5-9c0a83f90314",
                "entityType": "PlayerData",
                "version": 99,
                "data": {
                    "ALL_TIME_SCORE": 1003750
                },
                "acl": {
                    "other": 1
                },
                "createdAt": 1425909205616,
                "updatedAt": 1430338431696
            }
        ],
        "currency": {
            "coin": {
                "purchased": 9975000,
                "balance": 9968735,
                "consumed": 43500,
                "awarded": 37235
            }
        },
        "statistics": {
            "SCORE_STREAK_COUNT": 2
        },
        "abTestingId": 70,
        "id": "bb05182d-ff0c-4740-ae65-482751e74949",
        "profileId": "bb05182d-ff0c-4740-ae65-482751e74949"
    }
}

Read a friend's player state.

Service Operation
"friend" "READ_FRIEND_PLAYER_STATE"
Method Parameters
Parameter Description
friendId Profile Id of friend who owns entity.

ReadFriendsEntities

const char * entityType = "friendTest";

BrainCloudClient::getInstance()->getFriendService()->readFriendsEntities(
    entityType, this);
string entityType = "friendTest";

BrainCloudClient.Instance.FriendService.ReadFriendsEntities(
    entityType,
    ApiSuccess,
    ApiError);
public void readFriendsEntities(String entityType, IServerCallback callback)
- (void)readFriendsEntities:(NSString *)entityType
            completionBlock:(BCCompletionBlock)cb
       errorCompletionBlock:(BCErrorCompletionBlock)ecb
                   cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.readFriendsEntities = function(entityType, callback)
var entityType = "test";

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.readFriendsEntities(entityType);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "results": [
            {
                "userId": "bb05182d-ff0c-4740-ae65-4342452e74949",
                "entities": [
                    {
                        "entityId": "bb05182d-ff0c-4740-ae65-4827534949",
                        "entityType": "PlayerData",
                        "version": 99,
                        "data": {
                            "ACCOUNT_CREATION_TIME": 1353011574029,
                            "ALL_TIME_SCORE": 1003750,
                            "FIRST_PLAY_TIME": 1430338388347
                        },
                        "acl": {
                            "other": 1
                        },
                        "createdAt": 1425909205616,
                        "updatedAt": 1430338431696
                    }
                ]
            }
        ]
    }
}

Returns entities of all friends based on type and/or subtype.

Service Operation
"friend" "READ_FRIENDS_ENTITIES"
Method Parameters
Parameter Description
entityType Type of entities to retrieve

RemoveFriends

std::vector<std::string> friendIds;
friendIds.push_back("1234-1234-1234-1234");

BrainCloudClient::getInstance()->getFriendService()->removeFriends(friendIds, this);
string[] friendIds = { "1234-1234-1234-1234", "1234-1234-1234-1234" };

BrainCloudClient.Instance.FriendService.RemoveFriends(
    friendIds,
    ApiSuccess, ApiError);

tr.Run();
public void removeFriends(String[] profileIds, IServerCallback callback)
- (void)removeFriends:(NSArray *)profileIds
         completionBlock:(BCCompletionBlock)cb
    errorCompletionBlock:(BCErrorCompletionBlock)ecb
                cbObject:(BCCallbackObject)cbObject;
brainCloudClient.friend.removeFriends = function(profileIds, callback)
var friendIds = [ "1234-1234-1234-1234", "1234-1234-1234-1234" ];

var friendProxy = bridge.getFriendServiceProxy();
var retVal = friendProxy.removeFriends(friendIds);
Show Example JSON Return
{
    "status": 200,
    "data": null
}

Unlinks the current player and the specified players as brainCloud friends.

Service Operation
"friend" "REMOVE_FRIENDS"
Method Parameters
Parameter Description
profileIds Collection of player IDs.

Gamification

brainCloud's Gamification features provide server-side support common metagame elements, including:

These features build upon the Statistics APIs and a concept of Player Rewards.

Player Rewards

brainCloud provides an ability to reward players for completing meta-goals: leveling up, completing a milestone and/or completing quests. Rewards can consist of:

XP Levels

brainCloud can manage experience points (XP) and levels, and reward the player for levelling up.

A player's XP starts at 0, and is incremented using methods of the Player Statistics service. A list of player XP levels can be read from the client using ReadXPLevelsMetaData().

Achievements

Achievements can be triggered manually, or as the result of player rewards. Achievements can be data-filled with the ids for platform achievements (on iOS, Steam, etc.) so that they may automatically be triggered in sync with brainCloud achievements.

Achievements can be awarded directly using the AwardAchievements() API. There are also API calls for retrieving the full list of achievements, and the list of achievements that have already been awarded for the player.

Milestones

Milestones are used to define conditions under which rewards are to be delivered. Milestones must first be unlocked before they can be completed and then awarded.

Milestones

Quests

Quests are essentially compound Milestones. The completion status of the Quest is derived from the completion status of the Milestones (Tasks) that it is composed of.

Quests

Summary

General
Achievements
Milestones
Quests

AwardAchievements

std::vector<std::string> achievements;
achievements.push_back("testAchievement01");

BrainCloudClient::getInstance()->getGamificationService()->awardAchievements(achievements, this);
string[] achievements = { "achievementId01", "achievementId02" };

BrainCloudClient.Instance.GamificationService.AwardAchievements(
    achievements,
    ApiSuccess, ApiError);

tr.Run();
public void awardAchievements(String in_achievementIds, IServerCallback callback)
- (void)awardAchievements:(NSString *)achievements
completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
cbObject:(BCCallbackObject)cbObject;
brainCloudClient.gamification.awardAchievements = function(achievements, callback, includeMetaData)
var achievements = [ "achievementId01", "achievementId02" ];

var gamificationProxy = bridge.getGamificationServiceProxy();
var retVal = gamificationProxy.awardAchievements(achievements, false);
Show Example JSON Return
{
    "status": 200,
    "data": null
}

Method will award the achievements specified. On success, this will call AwardThirdPartyAchievement to hook into the client-side Achievement service (ie GameCentre, Facebook etc).

Service Operation
"gamification" "AWARD_ACHIEVEMENTS"
Method Parameters
Parameter Description
achievementIds A list of achievement ids to award
includeMetaData Whether to return meta data as well

ReadAchievedAchievements

BrainCloudClient::getInstance()->getGamificationService()->readAchievedAchievements(this);
BrainCloudClient.Instance.GamificationService.ReadAchievedAchievements(
    true,
    ApiSuccess, ApiError);
public void readAchievedAchievements(
boolean in_includeMetaData,
IServerCallback callback)
- (void)readAchievedAchievements:(bool)includeMetaData
completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
cbObject:(BCCallbackObject)cbObject;
brainCloudClient.gamification.readAchievedAchievements = function(callback, includeMetaData)
var gamificationProxy = bridge.getGamificationServiceProxy();
var retVal = gamificationProxy.readAchievedAchievements(false);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "achievements": []
    }
}

Method retrieves the list of achieved achievements.

Service Operation
"gamification" "READ_ACHIEVED_ACHIEVEMENTS"
Method Parameters
Parameter Description
includeMetaData Whether to return meta data as well

ReadAchievements

BrainCloudClient::getInstance()->getGamificationService()->readAchievements(this);
BrainCloudClient.Instance.GamificationService.ReadAchievements(
    true,
    ApiSuccess, ApiError);
public void readAchievements(
boolean in_includeMetaData,
IServerCallback callback)
- (void)readAchievements:(bool)includeMetaData
completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
cbObject:(BCCallbackObject)cbObject;
brainCloudClient.gamification.readAchievements = function(callback, includeMetaData)
var gamificationProxy = bridge.getGamificationServiceProxy();
var retVal = gamificationProxy.readAchievements(false);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "achievements": [{
            "fbEnabled": false,
            "imageUrl": "https://sharedprod.braincloudservers.com/s3/portal/g/123456/metadata/achievements/testAchievement01.png",
            "status": "NOT_AWARDED",
            "gameId": "20001",
            "steamEnabled": false,
            "extraData": null,
            "achievementId": "testAchievement01",
            "invisibleUntilEarned": false,
            "steamAchievementId": null,
            "id": "testAchievement01",
            "appleEnabled": false,
            "title": "Test Achievement 1",
            "fbGamePoints": null,
            "description": "Test description.",
            "appleAchievementId": null
        }]
    }
}

Read all of the achievements defined for the game.

Service Operation
"gamification" "READ_ACHIEVEMENTS"
Method Parameters
Parameter Description
includeMetaData Whether to return meta data as well

ReadAllGamification

BrainCloudClient::getInstance()->getGamificationService()->readAllGamification(false, this);
BrainCloudClient.Instance.GamificationService.ReadAllGamification(
    false,
    ApiSuccess, ApiError);
public void readAllGamification(
boolean in_includeMetaData,
IServerCallback callback)
- (void)readAllGamification:(bool)includeMetaData
completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
cbObject:(BCCallbackObject)cbObject;
brainCloudClient.gamification.readAllGamification = function(callback, includeMetaData)
var gamificationProxy = bridge.getGamificationServiceProxy();
var retVal = gamificationProxy.readAllGamification(false);
Show Example JSON Return
{
    "status": 200,
    "data": {
        "milestones": [
            {
                "id": "milestone01",
                "category": "general",
                "title": "Level 2 milestone",
                "status": "SATISFIED",
                "description": "Awarded when you get to level 2",
                "gameId": "10068",
                "rewards": {
                    "currency": {
                        "gold": 1000
                    }
                },
                "extraData": null,
                "questId": null,
                "milestoneId": "milestone02"
            }
        ],
        "achievements": [
            {
                "fbEnabled": true,
                "imageUrl": null,
                "status": "NOT_AWARDED",
                "gameId": "10068",
                "steamEnabled": false,
                "extraData": null,
                "achievementId": "ach01",
                "invisibleUntilEarned": false,
                "steamAchievementId": "",
                "id": "ach01",
                "appleEnabled": false,
                "title": "Finish Tutorial",
                "fbGamePoints": 10,
                "description": "Achievement awarded when you finish the tutorial",
                "appleAchievementId": ""
            }
        ],
        "quests": [],
        "xp": {
            "xpCapped": false,
            "experiencePoints": 0,
            "xpLevel": {
                "gameId": "10068",
                "level": 0,
                "statusTitle": "Lesser",
                "experience": 0,
                "fbAction": ""
            },
            "experienceLevel": 0
        }
    }
}

Method retrieves all gamification data for the player.

Service Operation
"gamification" "READ"
Method Parameters
Parameter Description
includeMetaData Whether to return meta data as well

ReadCompletedMilestones

BrainCloudClient::getInstance()->getGamificationService()->readCompletedMilestones(false, this);
BrainCloudClient.Instance.GamificationService.ReadCompletedMilestones(
    false,
    ApiSuccess, ApiError);
public void readCompletedMilestones(
boolean in_includeMetaData,
IServerCallback callback)
- (void)readCompletedMilestones:(bool)includeMetaData
completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
cbObject:(BCCallbackObject)cbObject;
brainCloudClient.gamification.readCompletedMilestones  = function(callback, includeMetaData)
var gamificationProxy = bridge.getGamificationServiceProxy();
var retVal = gamificationProxy.readCompletedMilestones(false);
Show Example JSON Return
{
    "status" : 200,
    "data" :
    {
        "milestones": []
    }
}

Method retrieves the list of completed milestones

Service Operation
"gamification" "READ_COMPLETED_MILESTONES"
Method Parameters
Parameter Description
includeMetaData Whether to return meta data as well

ReadCompletedQuests

BrainCloudClient::getInstance()->getGamificationService()->readCompletedQuests(false, this);
BrainCloudClient.Instance.GamificationService.ReadCompletedQuests(
    false,
    ApiSuccess, ApiError);
public void readCompletedQuests(
boolean in_includeMetaData,
IServerCallback callback)
- (void)readCompletedQuests:(bool)includeMetaData
completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
cbObject:(BCCallbackObject)cbObject;
brainCloudClient.gamification.readCompletedQuests  = function(callback, includeMetaData)
var gamificationProxy = bridge.getGamificationServiceProxy();
var retVal = gamificationProxy.readCompletedQuests(false);
Show Example JSON Return
{
    "status" : 200,
    "data" :
    {
        "quests": []
    }
}

Method returns all completed quests.

Service Operation
"gamification" "READ_COMPLETED_QUESTS"
Method Parameters
Parameter Description
includeMetaData Whether to return meta data as well

ReadInProgressMilestones

BrainCloudClient::getInstance()->getGamificationService()->readInProgressMilestones(false, this);
BrainCloudClient.Instance.GamificationService.ReadInProgressMilestones(
    false,
    ApiSuccess, ApiError);
public void readInProgressMilestones(
boolean in_includeMetaData,
IServerCallback callback)
- (void)readInProgressMilestones:(bool)includeMetaData
completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
cbObject:(BCCallbackObject)cbObject;
brainCloudClient.gamification.readInProgressMilestones  = function(callback, includeMetaData)
var gamificationProxy = bridge.getGamificationServiceProxy();
var retVal = gamificationProxy.readInProgressMilestones(false);
Show Example JSON Return
{
    "status" : 200,
    "data" :
    {
        "milestones": []
    }
}

Method retrieves the list of in progress milestones.

Service Operation
"gamification" "READ_IN_PROGRESS_MILESTONES"
Method Parameters
Parameter Description
includeMetaData Whether to return meta data as well

ReadInProgressQuests

BrainCloudClient::getInstance()->getGamificationService()->readInProgressQuests(false, this);
BrainCloudClient.Instance.GamificationService.ReadInProgressQuests(
    false,
    ApiSuccess, ApiError);
public void readInProgressQuests(
boolean in_includeMetaData,
IServerCallback callback)
- (void)readInProgressQuests:(bool)includeMetaData
completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
cbObject:(BCCallbackObject)cbObject;
brainCloudClient.gamification.readInProgressQuests  = function(callback, includeMetaData)
var gamificationProxy = bridge.getGamificationServiceProxy();
var retVal = gamificationProxy.readInProgressQuests(false);
Show Example JSON Return
{
    "status" : 200,
    "data" :
    {
        "quests": []
    }
}

Method returns quests that are in progress.

Service Operation
"gamification" "READ_IN_PROGRESS_QUESTS"
Method Parameters
Parameter Description
includeMetaData Whether to return meta data as well

ReadMilestones

BrainCloudClient::getInstance()->getGamificationService()->readMilestones(false, this);
BrainCloudClient.Instance.GamificationService.ReadMilestones(
    false,
    ApiSuccess, ApiError);
public void readMilestones(
boolean in_includeMetaData,
IServerCallback callback)
- (void)readMilestones:(bool)includeMetaData
completionBlock:(BCCompletionBlock)cb
errorCompletionBlock:(BCErrorCompletionBlock)ecb
cbObject:(BCCallbackObject)cbObject;
brainCloudClient.gamification.readInProgressQuests  = function(callback, includeMetaData)
var gamificationProxy = bridge.getGamificationServiceProxy();
var retVal = gamificationProxy.readInProgressQuests(false);
Show Example JSON Return
{
    "status": 200,