Customer authentication

Set Client State Change listener

Set your own ClientStateChangeListener to get optional callbacks.

Method name:
Client.setOnClientStateChangeListener(listener);

Declaration:

public static void setOnClientStateChangeListener(OnClientStateChangeListener listener)

Parameters:

Parameter Type Mandatory Default Description
listener OnClientStateChangeListener yes - interface to handle client state change

Return Value:
No value is returned.

Example:

Client.setOnClientStateChangeListener(listener);

Remove Client State Change listener

Remove your own ClientStateChangeListener.

Method name:
Client.removeClientStateChangeListener();

Declaration:

public static void removeClientStateChangeListener()

Parameters:
No parameters required.

Return Value:
No value is returned.

Example:

Client.removeClientStateChangeListener();

Register customer account

This method registers a new customer with an email, password, and optional data.

This method requires the context object with a customer’s email, password, and optional data. Omitted fields are not modified.

Depending on the backend configuration, the account may require activation. For details, see customer registration.

Do not allow signing in again (or signing up) when a customer is already signed in. Sign the customer out first.

Do not create multiple instances nor call this method multiple times before execution.

This method is a global operation and doesn’t require customer authentication.

Note: The API key must have the SAUTH_REGISTER_CLIENT_CREATE permission from the Client group.

Method name:
Client.registerAccount(registerClient)

Declaration:

public static IApiCall registerAccount(@NonNull RegisterClient registerClient)

Parameters:

Parameter Type Mandatory Default
registerClient RegisterClient yes -

Return Value:
IApiCall object to execute the request.

Example:

private IApiCall signUpCall;
private void signUp(RegisterClient registerClient) {
        if (signUpCall != null) signUpCall.cancel();
        signUpCall = Client.registerAccount(registerClient);
        signUpCall.onSubscribe(() -> toggleLoading(true))
                  .doFinally(() -> toggleLoading(false))
                  .execute(this::onSignUpSuccessful, this::onSignUpFailure);
    }

Confirm customer account

This method confirms a customer account with the confirmation token.

This method is a global operation and doesn’t require customer authentication.

Note: Returns the HTTP 400 status code if the account is already confirmed or 404 if the account does not exist.
Note: The API key must have the SAUTH_CONFIRMATION_CLIENT_CREATE permission from the Client group.

Method name:
Client.confirmAccount(token)

Declaration:

public static IApiCall confirmAccount(String token)

Parameters:

Parameter Type Mandatory Default Description
token String yes - Customer’s token

Return Value:
IApiCall object to execute the request.

Example:

private IApiCall call;
if (call != null) call.cancel();
            call = Client.confirmAccount(token);
            call.execute(this::onSuccess, this::onError);

Activate customer account

This method requests sending an email with a URL that confirms the registration and activates the account.

This method is a global operation and doesn’t require customer authentication.

Note: The API key must have the SAUTH_CONFIRMATION_CLIENT_CREATE permission from the Client group.

Method name:
Client.activateAccount(email)

Declaration:

public static IApiCall activateAccount(String email)

Parameters:

Parameter Type Mandatory Default Description
email String yes - Customer’s email

Return Value:
IApiCall object to execute the request.

Example:

private IApiCall call;
if (call != null) call.cancel();
            call = Client.activateAccount(email);
            call.execute(this::onSuccess, this::onError);

Request customer account activation by pin

This method requests a customer’s account registration process with the PIN code.

This method is a global operation and doesn’t require customer authentication.

Note: The API key must have the SAUTH_PIN_CODE_RESEND_CLIENT_CREATE permission from the Client group.

Method name:
Client.requestAccountActivationByPin(email)

Declaration:

public static IApiCall requestAccountActivationByPin(String email)

Parameters:

Parameter Type Mandatory Default Description
email String yes - Email to which the pinCode will be sent

Return Value:
IApiCall object to execute the request.

Example:

IApiCall apiCall;
apiCall = Client.requestAccountActivationByPin(email);
apiCall.execute(this::onSuccess, this::onFailure);

Confirm customer account activation by pin

This method confirms a customer’s account registration process with the PIN code.

This method is a global operation and doesn’t require customer authentication.

Note: The API key must have the SAUTH_PIN_CODE_RESEND_CLIENT_CREATE permission from the Client group.

Method name:
Client.confirmAccountActivationByPin(pinCode, email)

Declaration:

public static IApiCall confirmAccountActivationByPin(String pinCode, String email)

Parameters:

Parameter Type Mandatory Default Description
pinCode String yes - Code sent to the customer’s email
email String yes - Email used in the registration process

Return Value:
IApiCall object to execute the request.

Example:

IApiCall apiCall;
apiCall = Client.confirmAccountActivationByPin(pinCode, email);
apiCall.execute(this::onSuccess, this::onFailure);

Sign in a customer

This method signs a customer in to obtain a JSON Web Token (JWT) which can be used in subsequent requests.

The SDK will refresh the token before each call if it is about to expire (but not expired).

Do NOT allow signing in again (or signing up) when a customer is already signed in. First, sign the customer out.

Do NOT create multiple instances nor call this method multiple times before execution.

Method name:
Client.signIn(email, password)

Declaration:

public static IApiCall signIn(@NonNull String email, @NonNull String password)

Parameters:

Parameter Type Mandatory Default Description
email String yes - Customer’s email
password String yes - Customer’s password

Return Value:
IApiCall object to execute the request.

Example:

private IApiCall signInCall;
private void signIn(String login, String password) {
        if (signInCall != null) signInCall.cancel();
        signInCall = Client.signIn(login, password);
        signInCall.onSubscribe(() -> toggleLoading(true))
                  .execute(() -> onSignInSuccessful(login), () -> onSignInFailure());
    }

Sign in a customer conditionally

This method signs a customer in to obtain a JSON Web Token (JWT) which can be used in subsequent requests.

The SDK will refresh the token before each call if it is about to expire (but not expired).

Do NOT allow signing in again (or signing up) when a customer is already signed in. First, sign the customer out.

Do NOT create multiple instances nor call this method multiple times before execution.

Method name:
Client.signInConditionally(email, password)

Declaration:

public static IDataApiCall<AuthConditions> signInConditionally(@NonNull String email, @NonNull String password)

Parameters:

Parameter Type Mandatory Default Description
email String yes - Client’s email
password String yes - Client’s password

Return Value:
IDataApiCall<AuthConditions> object to execute the request.

Example:

private IDataApiCall<AuthConditions> call;
if (call != null) call.cancel();
            call = Client.signInConditionally(email, password));
            call.execute(this::onSuccess, this::onFailure);

Authenticate customer by IdentityProvider

This method authenticates a customer with OAuth, Facebook, Google, Apple, or Synerise.

If an account for the customer does not exist and the identity provider is different than Synerise, this request creates an account.

Method name:
Client.authenticate(token, clientIdentityProvider, agreements, attributes, authId)

Declaration:

public static IApiCall authenticate(String token, ClientIdentityProvider provider, Agreements agreements, Attributes attributes, String authId)

Parameters:

Parameter Type Mandatory Default Description
token String yes - Token retrieved from provider
provider ClientIdentityProvider yes - Provider of your token
agreements Agreements no - Optional agreements
attributes Attributes no - Optional attributes
authId String no - Optional identifier of authorization
Note: authId parameter is used for decreasing the number of UUID refreshes, so it must be unique for every customer.

Return Value:
IApiCall object to execute the request.

Example:

private IApiCall call;
if (call != null) call.cancel();
            call = Client.authenticate(token, provider, null, null, null);
            call.execute(this::onSuccess, this::onFailure);

Authenticate customer conditionally by IdentityProvider

This method authenticates a customer with OAuth, Facebook, Google, Apple, or Synerise.

Method name:
Client.authenticateConditionally(token, clientIdentityProvider, agreements, attributes, authId)

Declaration:

public static IDataApiCall<AuthConditions> authenticateConditionally(@NonNull String token, @NonNull ClientIdentityProvider provider, @Nullable Agreements agreements, @Nullable Attributes attributes, @Nullable String authId)

Parameters:

Parameter Type Mandatory Default Description
token String yes - Token retrieved from provider
provider ClientIdentityProvider yes - Provider of your token
agreements Agreements no - Optional agreements
attributes Attributes no - Optional attributes
authId String no - Optional identifier of authorization
Note: authId parameter is used for decreasing the number of UUID refreshes, so it must be unique for every customer.

Return Value:
IDataApiCall<AuthConditions> object to execute the request.

Example:

private IDataApiCall<AuthConditions> call;
if (call != null) call.cancel();
            call = Client.authenticateConditionally(token, clientIdentityProvider, agreements, attributes, authId));
            call.execute(this::onSuccess, this::onFailure);

Authenticate customer with token payload

Signs in a customer in with the provided token payload.

Method name:
Client.authenticateWithTokenPayload()

Declaration:

public static IApiCall authenticateWithTokenPayload(TokenPayload tokenPayload, @NonNull String authId)

Parameters:

Parameter Type Mandatory Default Description
tokenPayload TokenPayload yes - Object which contains a token’s payload
authId String yes - Required customer’s identifier of authorization
Note: authId parameter is used for decreasion the number of UUID refreshes so it must be unique for every customer.

Return Value:
IApiCall object to execute the request.

Example:

private IApiCall call;
if (call != null) call.cancel();
            call = Client.authenticateWithTokenPayload(tokenPayload, authId);
            call.execute(this::onSuccess, this::onFailure);

Authenticate customer via Simple Authentication

This method authenticates a customer with Simple Authentication.

Note: The API key must have the SAUTH_SIMPLE_AUTH_CREATE from the Auth group.

Method name:
Client.simpleAuthentication(clientData, authId)

Declaration:

public static IApiCall simpleAuthentication(ClientData clientData, String authId)

Parameters:

Parameter Type Mandatory Default Description
clientData ClientData yes - Object which contains customer data
authId String yes - Required identifier of authorization
Note: authId parameter is used for decreasing the number of UUID refreshes, so it must be unique for every customer.

Return Value:
IApiCall object to execute the request.

Check if a customer is signed in (via RaaS, OAuth, Facebook, Apple)

This method checks if a customer is signed in (via RaaS, OAuth, Facebook, Apple).

Method name:
Client.isSignedIn()

Declaration:

public static boolean isSignedIn()

Parameters:
No parameters.

Return Value:
Boolean defining whether a customer is signed in or not.

Example:

boolean isSignedIn = Client.isSignedIn()

Check if a customer is signed in (via Simple Authentication)

This method checks if a customer is signed in (via Simple Authentication).

Method name:
Client.isSignedIn()

Declaration:

public static boolean isSignedInViaSimpleAuthentication()

Parameters:
No parameters.

Return Value:
true if the customer is signed in (via Simple Authentication), otherwise returns false.

Example:

boolean isSignedInViaSimpleAuthentication = Client.isSignedInViaSimpleAuthentication()

Sign out customer

This method signs out a customer out.

Note: This method works with every authentication type (via Synerise, External Provider, OAuth or Simple Authentication).

Method name:
Client.signOut()

Declaration:

public static void signOut()

Parameters:
No parameters.

Return Value:
Nothing is returned.

Example:

Client.signOut();

Sign out customer with mode or from all devices

This method signs out a customer out with a chosen mode and Determines if the method should sign out all devices.

Available modes:

  • .signOut mode signs out the customer.
  • .signOutWithSessionDestroy mode signs out the customer and additionally, clears the anonymous session and regenerates the customer UUID.

The fromAllDevices parameter determines whether the method should notify the backend to sign out all devices.

IMPORTANT: It is an asynchronous method.

Note: This method works with every authentication type (via Synerise, External Provider, OAuth or Simple Authentication).

Class:
Client

Declaration:

public static IApiCall signOut(ClientSignOutMode mode, Boolean signOutFromAllDevices)

Parameters:

Parameter Type Mandatory Default Description
mode ClientSignOutMode yes - Client sign out mode
signOutFromAllDevices Boolean yes - Determines if the method should sign out all devices

Return Value:
Nothing is returned.

Example:

private IApiCall signOutCall;
private void signOut() {
  if (signOutCall != null) signOutCall.cancel();
  signOutCall = Client.signOut(ClientSignOutMode.SIGN_OUT_WITH_SESSION_CLEARING, true);
  signOutCall.onSubscribe(() -> toggleLoading(true))
             .execute(() -> onSignOutSuccessful(login), () -> onSignOutFailure());
}

Deprecated methods

Authenticate customer by OAuth with registration

This method authenticates a customer with OAuth.

If an account for the customer does not exist, this request creates an account.

Note: Returns the HTTP 401 status code if the provided access token and/or API Key is invalid.
Note: This method was deprecated.

Method name:
Client.authenticateByOAuth(accessToken, agreements, attributes, authId)

Declaration:

public static IApiCall authenticateByOAuth(@NonNull String accessToken, @Nullable Agreements agreements, @Nullable Attributes attributes, @Nullable String authId)

Parameters:

Parameter Type Mandatory Default Description
accessToken String yes - OAuth Access Token
agreements Agreements no — Optional agreements
attributes Attributes no — Optional attributes
authId String no — Optional identifier of authorization
Note: authId parameter is used for decreasing the number of UUID refreshes, so it must be unique for every customer.

Return Value:
IApiCall object to execute the request.

Example:

private IApiCall call;
if (call != null) call.cancel();
            call = Client.authenticateByOAuth(token, null, null, null);
            call.execute(this::onSuccess, this::onFailure);

Authenticate customer by OAuth without registration

This method authenticates a customer with OAuth.

Note: Returns the HTTP 401 status code if the provided access token and/or API Key is invalid.
Note: This method was deprecated.

Method name:
Client.authenticateByOAuthIfRegistered(accessToken, authId)

Declaration:

public static IApiCall authenticateByOAuthIfRegistered(@NonNull String accessToken, @Nullable String authId)

Parameters:

Parameter Type Mandatory Default Description
accessToken String yes - OAuth Access Token
authId String no — Optional identifier of authorization
Note: authId parameter is used for decreasing the number of UUID refreshes, so it must be unique for every customer.

Return Value:
IApiCall object to execute the request.

Example:

private IApiCall call;
if (call != null) call.cancel();
            call = Client.authenticateByOAuthIfRegistered(token, null);
            call.execute(this::onSuccess, this::onFailure);

Authenticate customer by Facebook with registration

This method authenticates a customer with Facebook.

If an account for the customer does not exist, this request creates an account.

Note: Returns the HTTP 401 status code if the provided Facebook token and/or API Key is invalid.
Note: This method was deprecated.

Method name:
Client.authenticateByFacebook(facebookToken, agreements, attributes, authId)

Declaration:

public static IApiCall authenticateByFacebook(@NonNull String facebookToken, @Nullable Agreements agreements, @Nullable Attributes attributes, @Nullable String authId)

Parameters:

Parameter Type Mandatory Default Description
facebookToken String yes - Facebook Access Token
agreements Agreements no — Marketing agreements
attributes Attributes no — Additional attributes
authId String no — Optional identifier of authorization
Note: authId parameter is used for decreasing the number of UUID refreshes, so it must be unique for every customer.

Return Value:
IApiCall object to execute the request.

Example:

private IApiCall signInFacebookCall;
private void signInFacebook(String facebookToken) {
        if (signInFacebookCall != null) signInFacebookCall.cancel();
        signInFacebookCall = Client.authenticateByFacebook(facebookToken, null, null, null);
        signInFacebookCall.onSubscribe(() -> toggleFacebookLoading(true))
                          .execute(this::onSignInFacebookSuccess, this::onSignInFacebookError);
    }

Authenticate customer by Facebook without registration

This method authenticates a customer with Facebook.

Note: Returns the HTTP 401 status code if the provided Facebook token and/or API Key is invalid.
Note: This method was deprecated.

Method name:
Client.authenticateByFacebookRegistered(facebookToken, authId)

Declaration:

public static IApiCall authenticateByFacebookRegistered(@NonNull String facebookToken, @Nullable String authId)

Parameters:

Parameter Type Mandatory Default Description
facebookToken String yes - Facebook Access Token
authId String no — Optional identifier of authorization
Note: authId parameter is used for decreasing the number of UUID refreshes, so it must be unique for every customer.

Return Value:
IApiCall object to execute the request.

Example:

private IApiCall signInFacebookRegisteredCall;
private void signInFacebookRegistered(String facebookToken) {
        if (signInFacebookRegisteredCall != null) signInFacebookRegisteredCall.cancel();
        signInFacebookRegisteredCall = Client.authenticateByFacebookRegistered(facebookToken, null);
        signInFacebookRegisteredCall.onSubscribe(() -> toggleFacebookLoading(true))
                          .execute(this::onSignInFacebookSuccess, this::onSignInFacebookError);
    }

Sign out customer with mode

This method signs out a customer out with a chosen mode:

  • .signOut mode notifies the backend that the customer is signed out.
  • .signOutWithSessionDestroy mode notifies the backend that the customer is signed out and additionally, clears the anonymous session and regenerates the customer UUID.
Note: This method works with every authentication type (via Synerise, External Provider, OAuth or Simple Authentication).
Note: This method was deprecated in SDK version 5.1.0.

Class:
Client

Declaration:

public static void signOut(ClientSignOutMode mode)

Parameters:

Parameter Type Mandatory Default Description
mode ClientSignOutMode yes - Client sign out mode

Return Value:
Nothing is returned.

Example:

Client.signOut(mode);

😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker