Miscellaneous

The EkoClient class also provides a variety of account and error handling methods.

Active account

Displayname

The displayName is an optional property that helps users identify a user. It is used mainly for push notifications in order to identify the sender of a message, but you may also use this property for displaying user data in the UI.

However, please keep in mind that the SDK does not handle user management. if your UI requires you to display more complex user data (e.g. age, title, avatar, etc.), we recommend you to build this functionality into your application directly.

Display names are usually set on EkoClient.registerDevice() method, however, you may also set it after device registration with the EkoClient.updateUser() method.

EkoClient.updateUser()
.displayName("John")
.build()
.update
.subscribe()

Avatar

There are 2 ways to keep avatar on Upstra system.

  1. To persist a physical file, the image file has to be uploaded via EkoFileRepostiroy.uploadImage(),then pass the obtained to

    EkoClient.updateUser().avatar()

  2. To persist only a url of an image, the url can be passed to

    EkoClient.updateUser().avatarCustomUrl()

val avatar : EkoImage = ...
EkoClient.updateUser()
.avatar(avatar)
.build()
.update()
.subscribe()
val url : String = ...
EkoClient.updateUser()
.avatarCustomUrl(url)
.build()
.update()
.subscribe()

User Metadata

User payload contains an optional property called metadata that allows you to store specific data on each user.

val metadata = JsonObject()
metadata.addProperty("avatar", "IMAGE_URL")
EkoClient.updateUser()
.metadata(metadata)
.build()
.update()
.subscribe()

Error Handling

Error Codes

All the errors returned by the SDK come in form of an EkoException. The possible error codes are listed in a public EkoError enum: each case is named after its error and they are designed to be self explanatory.

The SDK will automatically handle all recoverable errors such as connection state errors without notifying you. For example, if you try to perform an action while the client is offline, the SDK will automatically retry until the action is successful. As a result, any errors return by the SDK are due to unrecoverable business errors.

The error codes are always six digits, with the first three identifying the type of error, and the latter three digits identifying the specific error. Errors that are originated from the server start with 400 (therefore the server error codes will be 400xxx) and 500 (500xxx), while client errors start with 800 (800xxx).

Server Errors

Error

Code

BAD_REQUEST_ERROR

400000

INVALID_REGULAR_EXPRESSION

400001

UNAUTHORIZED_ERROR

400100

FORBIDDEN_ERROR

400300

PERMISSION_DENIED

400301

USER_IS_MUTED

400302

CHANNEL_IS_MUTED

400303

USER_IS_BANNED

400304

NUMBER_OF_MEMBER_EXCEED

400305

EXEMPT_FROM_BAN

400306

MAX_REPETITION_EXCEED

400307

BAN_WORD_FOUND

400308

LINK_NOT_ALLOWED

400309

TOO_MANY_MEMBER_ERROR

400310

RPC_RATE_LIMIT_ERROR

400311

USER_IS_GLOBAL_BANNED

400312

ITEM_NOT_FOUND

400400

CONFLICT

400900

BUSINESS_ERROR

500000

Client Errors

Error

Code

UNKNOWN

800000

INVALID_PARAMETER

800110

MALFORMED_DATA

800130

FILE_SIZE_EXCEEDED

800140

CONNECTION_ERROR

800210

You can convert an EkoException into EkoError enum as following:

Throwable t;
if (EkoError.from(t).is(EkoError.CHANNEL_IS_MUTED)) {
// Couldn't send a message to this channel because this channel is muted.
}

When an error is returned as a result of an action from your side (e.g. trying to join a channel), the action is considered completed and the SDK will not execute any additional logic.

Asynchronous Errors

The EkoClient class includes the EkoClient.errors() method that can be called and observed to asynchronous errors. This observable object notifies you of errors that can potentially break the functionality of the SDK. The SDK logic is usually robust enough to automatically handle most errors, as such, only unrecoverable errors are exposed through this observable (for example, if the login session was invalidated).

We recommend you to always handle these errors in a production app by gracefully disabling messaging functionality in the event of an error.