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

Client Errors

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.