Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
An easy-to-integrate module that delivers high-performance messaging services
From travel-loving retirees for cruise lines to hiking enthusiasts for camping equipment brands, there are groups and individuals everywhere seeking to find others with similar interests. Provide a place for your customers to join communities centered towards your brand and what it represents to boost customer loyalty and retention, build a positive association, as well as allow them to feel a deeper connection to your brand.
The Chat SDK for Android is delivered via maven repository.
Add the Jitpack repository in your project level build.grade
at the end of repositories:
Add the dependency in your module level build.grade
:
To get started using the SDK, data binding is required as a mandatory dependency. You need to download the library from the Support Repository in the Android SDK manager. For more information, see Update the IDE and SDK Tools.
To configure your app to use data binding, enable the dataBinding
build option in your build.gradle
file in the app module, as shown in the following example:
Currently, Android does not support Live-Objects as such, we use a protocol that follows ReactiveX for Kotlin and Java related data streams.
You can find out more information here; https://github.com/ReactiveX/RxKotlin
Moderation is an important feature for building a safe community that encourages user participation and engagement.
Amity’s customer centric nature ensures that security needs are kept at the forefront of the work we do. Our purpose has been to continuously develop features that are safe and ready to use. We power our moderators with tools to control and impose permissions that make their applications a safer place, for all users. We put the utmost importance on giving power to our clients to implement protocols that keep their applications healthy, safe and compliant.
This section outlines how you can set-up your project for success and begin using our Chat SDK for Android.
Before using the Chat SDK, you will need to create a new SDK instance with your API key. Please find your account API key via the Admin Panel. If you have trouble finding this, you can send our support team an email at developer@amity.co
In order to use any Chat SDK feature, you must first register the current device with an userId
. A registered device will be tied to the registered userId
until the device is either proactively unregistered, or until the device has been inactive for over 90 days. A registered device will receive all the events messages belonging to the tied user.
An optional displayName
can be provided, which will be used in standard push notifications (related to user's actions, such as when the new message is sent).
The
displayName
is set only on the first time the device is registered, please follow your platforms necessary directions if you would like to rename this to something else.
When the user logs out, you should explicitly unregister the user from the SDK as well. This prevents the current device from receiving unnecessary and/or restricted data.
Each user can be registered, at the same time, to an unlimited number of devices. Amity's Chat SDK will automatically synchronize the user data across all registered devices. We will also automatically unregister any device that has not been connected to the server for more than 90 days.
When a device is unregistered due to inactivity, the SDK data on the device will be reset. You will need to re-register this device in order to connect to server again.
If you have any logic or UI around the connection status, you can observe the connectionStatus
property on the EkoClient
instance.
Since the Chat SDK automatically manages the network connection and queue up any requests in cases of bad connection, there should be little need to attach additional logic to this status. However the user may want to know the exact network status to determine if their actions will be performed in real-time, therefore this status is exposed.
Our Sample app adopts an open source framework that highlights how Amity Social Cloud SDK's can be implemented into application builds pragmatically.
With real life use-cases, we guide you through ways you can get started with building stellar applications for yourself and your clients and their users
Amity SDK's do not store or manage any user data. This means that you do not have to import or migrate existing user profiles into the system, user management should be handled by your application code. Instead, every user is simply represented by a unique userID
, which can be any string that uniquely identifies the user and is immutable throughout its lifetime.
A database primary key would make an ideal
userID
. Conversely, something like username or emails is not recommended as those values may change overtime.
If you wish to assign additional permissions for a user, for example moderation privileges or different sending limits, you can provide an array of roles to assign to this user. Roles are defined in the admin panel and can be tied to an unlimited number of users. Once again, Amity does not store or manage any user data, which means you do not have to import or migrate existing users into the system. It also means that Amity cannot provide user management functionalities like lists of users, or limit actions of certain users (e.g. user permissions). Instead, these functionalities should be handled by the rest of your application's capabilities and your server.
Though the SDK does not store and should not be responsible for the handling User profile data for your application; We do provide tools to make some surface-level queries and searches for existing user accounts. With the help of our EkoUserRepository
class, you would be able to list all the users, search for list of users whose display name matches your search query and get EkoUser
object from user id.
Each EkoUser
consists of a userId
and displayName
. The userId
is immutable once the account is created, however the displayName
can be updated at all times.
To get EkoUserRepository
instance
EkoUserRepository
provides a convenient method getAllUsers()
to fetch all users. You can observe for changes in collection, similar to message or channel. The method accepts EkoUserSortOption
as an optional parameter. The list can be sorted by displayName, firstCreated or lastCreated.
EkoUserRepository
provides searchUserByDisplayName()
method which allows you to query for users using their display name. It provides you with a LiveCollection of EkoUser
whose display name matches with your search query. EkoUserSortOption
is an optional parameter.
The code above will provide you with the list of users which matches with display name "John".
has 3 enums type 1. EkoUserSortOption.DISPLAYNAME
Sort by displayName 2. EkoUserSortOption.FIRST_CREATED
Sort by firstCreated 3. EkoUserSortOption.LAST_CREATED
Sort by lastCreated
Our channels enable developers to implement different types of chat messaging capabilities into their applications easily
Users can create and join channels where they will be able to participate and chat with other users. A channel can support up to 300,000 members and can contain an unlimited number of messages. Any message exchanged in the channels will be pushed to all other members of the channel in real-time.
Amity's Chat SDK supports the creations of 4 types of chat channels. Each type is designed to match a particular use-case for chat channels. Here's a table showing what features each channel offers:
The community channel is our default channel type and can be discovered by all users and admins. It acts as a public chat channel that showcases all of the features that our SDK's have to offer.
Typical use cases:
Team collaboration
Online gaming
Celebrity fan club
Live streaming
Any type of public chat
Live channels offers the ability for users and admins to create channels with exclusive memberships. The live channel is identical to our Community channel in features with the caveat that users will not be able to discover the channel when querying for all channels unless they are already a member of it. However users and admins can still invite other users to join the channel.
Typical use cases:
Healthcare
Project Discussion
Any type of private chat
Community and Live channel types can use our SDK moderation tools:
Message and user flagging
Muting/Unmuting users
Banning/Unbanning users from channel
Profanity filters
Whitelisted URLs
User rate-limiting
All broadcast channels are visible on the Amity Social Cloud Console.
The Broadcast channel is heavily adopted by corporate users who constantly promote or advertise their products, or make the announcement to drive awareness. Unlink other channel types, broadcast channels only allow admin users to send messages from Console, and everyone else in the channel will be under read-only mode.
Since this is a one-way communication channel, a tailored moderation tools are provided as well, for instance, users won't be able to flag message / user in the channel.
Typical use cases:
Marketing & Advertising
School / Government Announcements
Conversation channels are NOT visible on the Amity Social Cloud Console.
The Conversation channel is our solution to 1-on-1 messaging. Unlike the other channel types, a Conversation channel can be created simply by knowing the userId of the user we want to converse with. Users can start conversations with any other user and only they will be able to see their conversation.
There are no moderation tools for Conversation channels, users will be able to converse freely with no oversight!
Typical use cases:
Hospitality
Financial Consultancy
Customer Support
When a user joins a channel, they are able to observe and chat with other users in that channel. They are also automatically considered a member of that channel. The Chat SDK provides the ability to view which users are currently in the channel as well as invite other users to join the channel.
Each channel is identified by a unique channelId
, which is any string that uniquely identifies the channel and is immutable through its lifetime. When creating channels, you can specify your own channelId
, or leave it to Amity to automatically generate one for you.
There are 4 channel types 1. Community: a channel that is discoverable by all users. 2. Live: a channel that is discoverable only if user is already added as a member. 3. Broadcast: a channel that limits message creation to only Admin user. Message can only be created from Admin panel. 4. Conversation: a one-to-one chat that once created will not be available on Admin panel.
There are three ways of obtaining an EkoChannel
object: via create, join, or get methods. EkoChannel
management methods are all contained in the EkoChannelRepository
class. To get an instance of EkoChannelRepository
:
The SDK provides 2 typical ways of channel creation.
Channel creation with specific channelId.
Channel creation with auto-generation of channelId.
The channel creation API guarantees that the requested channel is a new channel. If the channel already exists, the error will be an EkoException
with code 400900
The createChannel()
method initiates channel creation method chain and let you choose which channel type to be created.
To let SDK handle channelId generation, uses withDisplayName()
method to skip channelId specification.
Channel of type Conversation
can also be created with createChannel()
method chain. However, the channelId is always being generated by SDK.
To create a conversation channel with a user, pass the user's userId to withUserId()
method.
Conversation channel is unique based on its membership. When creating conversation the system will check if channel with the same membership already exists, if such channel already exists the system will return existing channel instead of creating a new one.
The joinChannel()
method will add the active user as a member of the channel.
This API can be called as many time as needed. If the channel has already been joined, a "success" result will be returned, ie., going into doOnSuccess{}
block.
In the case where you only want to fetch a channel's data without joining, you can use the getChannel()
method:
The EkoChannelRepository
provides the getChannelCollection()
method which initiates channel query method chain. The query returns Flowable<PagedList<EkoChannel>>
representing all matching channels available.
the filter()
method lets you filter channels based on the current user membership status
the includingTags()
and excludingTags()
methods let you filter channels based on the tags set (or not set) in each channel
Metadata is a general purpose data store that is automatically synchronized to all users of a channel. It is designed to store contextual information about a specific channel. The metadata is a JSON object which can store any number of JSON key value pairs up to 100 kb. Example use cases include:
Conversation title or cover photo
Global conversation settings
Metadata is implemented with last writer wins semantics on the entire store. This means that multiple mutations by independent users to the metadata object will result in a single stored value. The metadata object set by last user override any previous values. No locking, merging, or other coordination is performed across participants.
To set metadata, simply call the following method:
Every channel contains an optional displayName
field. This field is mainly used to identify the channel in push notifications, but it is also exposed to the application via EkoChannel
object.
You can set a channel's displayName
with the following methods:
All participation related methods in a channel falls under a separate EkoChannelParticipation
model. You can access EkoChannelParticipation
from EkoChannelRepository.membership()
method as well as from EkoChannel.membership()
method.
The EkoChannelParticipation
provides a list of members in the given channel
You can add and remove members, as well as removing yourself as a member of a channel (leaving the channel) via EkoChannelParticipation
model should you have appropriate privileges.
Creator of the channel can add and remove the role of user via EkoChannelModeration
.
The EkoChannelParticipation
provides a list of members by role in the given channel.
You can check your permission in channel by sending EkoPermission enums to EkoClient.hasPermission(:ekoPermission)
.
The EkoChannelRepository
provides getTotalUnreadCount()
method. It's giving the flowable of the number of messages that the current user has yet to read. This count is the sum of all the unreadCount
channels properties where the user is member of.
To let the server know when the current user is reading one channel, hence resetting that channel unreadCount
to zero, the participation membership exposes the EkoChannelParticipation.startReading()
and EkoChannelParticipation.stopReading()
methods.
You can call both methods as much as you want, the SDK takes care of multi-device management: therefore a user can read multiple channels, from one or multiple devices at once. In case of an abrupt disconnection (whether because the app was killed, or the internet went down etc) the SDK backend will automatically call the EkoChannelParticipation.stopReading()
on the user behalf.
When a user is muted, they can not send messages in a channel.
Moderators can mute and unmute users. When a user is muted, they cannot send messages in a channel. However muted users will still be allowed to observe messages in a channel. The status of being muted is indefinite but is only applied at the channel level.
When a user is muted, all messages sent by that user to that channel will be rejected. This method is useful for preventing certain users from sending inappropriate messages, but still allowing them to participate in the conversation in a read-only manner. The timeout property allows you to make the timeout temporary, or permanent by until unset by passing in -1
.
The above logic will mute user1
in the selected channel for 10 minutes.
If you want to permanently mute a user, pass in
Duration.millis(-1)
as thetimeout
. The user will stay muted until you explicitly unmute that user.
Note: This feature does not work with Broadcast
and Conversation
channel. Calling muteUsers()
or unMuteUsers()
on these channels will result in an error.
Interactions are more fun when you can express yourself! Let users react using emojis, stickers, or thumbs up to messages.
There are 3 Reaction related methods on EkoMessage
:
1. getReactionCount()
returns Int
, the total reaction count on the message.
2. getMyReactions()
returns List<String>
, a collection of reactions that have been added by the active user.
3. getReactions()
returns EkoReactionMap
, an extension of Map<String, Int>
of reaction name and its count.
You can choose to add/remove a reaction to/from a message by calling react()
method on EkoMessage
To query for a list of all reactions on a message:
This method will return a Flowable<PagedList<EkoReaction>>
of all reactions in the specified message.
This page highlights the steps you will need to follow to begin integrating chat messaging into your products
The message payload is always the same regardless of which Development Kit the user is using. Users also have a choice on what type of message they want to send.
Amity supports the sending and receiving of 5 types of messages. They are Text, Image, Audio, File, and Custom.
Amity will automatically optimize the image and when queried, will return the image in small, medium and large sizes. If the image is marked as isFull
on upload, the original size of the image can also be returned.
When an image is uploaded, it is automatically resized into multiple sizing options. The size of the image is determined by its longest dimension (in pixels) with the aspect ratios being unchanged.
The maximum file size of an image cannot exceed 1 GB.
When a user is observing messages, the message will always appear in this format.
Messages are JSON content containers that can weigh up to 100KB and will be synchronized among all channel users in real-time. If a message requires larger binary data (such as when sending files), we recommend to upload the data to another cloud storage service, such as AWS S3, and store the URL to the content in the message data.
In addition the JSON message type, the SDK also provides support for common text and image message types. These additional types are built on top of the standard JSON message layer.
In case of image messages, the SDK freely provides a cloud storage service that will process and store all images uploaded: you don't need to setup and manage a separate cloud storage service for this common case.
All messaging methods are contained in a EkoMessageRepository
class. Before calling any messaging methods, you must ensure to first instantiate a repository instance using the EkoClient
instance you created on setup.
All message sending methods are designed to be robust enough to work under any network conditions. When you send any message, that message will automatically be put into a queue incase of any unforeseen unstable network conditions. Once the SDK reconnects to the server, it will automatically resend all the queued messages.
Additionally, sent messages are always returned in message queries, even before they have been delivered to the server. This provides the user with a fluid messaging flow: when a user sends a message, that sent message will appear in the message stream right away (instead of waiting until it has been confirmed by the server). To check or display the current status of message delivery for your application, use the syncState
property in the message model; for web you should useEkoMessage.getState()
method in the EkoMessage
object.
Initiate the messaging with the following scripts, depending on your platform of choice
To send an image message, you must pass in a valid image URL. The SDK will automatically send it to the server. You can also pass in an optional caption as part of the message.
To send an image in original size, set optional isFullImage()
to true. Note: File size is limited to 1 GB
To send a file message, you must pass in a valid file URL. The SDK will automatically send it to the server. You can also pass in an optional caption as part of the message.
Note: File size is limited to 1 GB
With a custom message, you can send a JsonObect
of your choice as part of the message.
To comment on a message, specify the messageId with parentId()
method
To query for a list of all messages in a channel:
This method will return all messages in the specified channel as Flowable<PagedList<EkoMessage>>
While the SDK will always return messages in chronological order, developers can ask for the messages to be returned starting from the oldest first, or the newest first.
On a typical messaging application, the messages are fetched from the latest (newest) first, and then more older messages are explored. (When stack from end is set to true, the list fills its content starting from the bottom of the view)
There are other situations where fetching the oldest messages is preferred, for example for archiving purposes or in community forums. (When stack from end is set to false, the list fills its content starting from the top of the view)
Note: Please make sure that stackFromEnd
using for obtain MessageCollection is the same as stackFromEnd
of RecyclerView's LayoutManager. Otherwise it may cause jumping issue.
Like channels, we also have various ways to obtain messages that only match specific criteria:
the includingTags
and excludingTags
parameters let you filter messages based on the tags set (or not set) in each message
the parentId
parameter lets you filter messages by their relationship:
when no parentId
is passed, any message will match.
when null parentId
is passed, query for all messages without a parent.
when non-null parentId
is passed: query for all messages with the parentId
as parent.
In the case where you only want to fetch an individual message from a channel, you can use the getMessage()
method:
Calling getUrl()
without specifying image size returns a url of a medium-size image.
Please use the appropriate image size depending on your use-case in order to save bandwidth.
SMALL
is used for image thumbnails, with a maximum image size of 160 pixels per dimension. For example, this should be used for small previews in an image gallery that displays a large amount of images in a grid.
MEDIUM
is used for standard image display, with a maximum image size of 600 pixels per dimension.
LARGE
is used for full screen image display, with a maximum image size of 1500 pixels per dimension.
FULL
is used to get the original image. This size is only valid if the image is uploaded with the method isFullImage()
set to true
. If a FULL
sized image is not available, a LARGE
sized image will be returned instead.
The image is protected by access token. In order to view an image, the http request for that image needs to be authenticated.
i. Create an instance of OkHttpClient
with the implementation provided by the SDK and pass it to Picasso's builder.
To get file url and file name from EkoMessage
:
Create an instance of OkHttpClient
with the implementation provided by the SDK.
To get customedJsonObject
from EkoMessage
You can only perform edit and delete operations on messages you've sent. Once the operation is complete, the message's editedAt
will be set to the current time. This allows you to provide UI to the user to inform the user of specific messages that has been edited, if needed.
Currently, the Chat SDK has only 2 editable data types, TEXT
and CUSTOM
To delete a message, simply call delete()
on EkoMessage
There are 3 Reaction related methods on EkoMessage
:
1. getReactionCount()
returns Int
, the total reaction count on the message.
2. getMyReactions()
returns List<String>
, a collection of reactions that has been added by the active user.
3. getReactions()
returns EkoReactionMap
, an extension of Map<String, Int>
of reaction name and its count.
You can choose to add/remove a reaction to/from a message using calling react()
method on EkoMessage
To query for a list of all reactions on a message:
This method will return a Flowable<PagedList<EkoReaction>>
of all reactions in the specified message.
To unmute an user, call :
To get an image url from :
To integrate with and :
Ensure that you have the following gradle dependencies where glideVersion
is the latest version:
Integrate with Eko's authentication
i. If you don't have custom defined, just add the following class:
ii. If you already have add using method:
To render image with
To integrate with and :
Ensure that you have the following gradle dependencies where picassoVersion
is 2.7 or above. For picassoVersion
below, you may need a extension.
Integrate with Eko's authentication
ii. If you already have your own implementation of OkHttpClient
, add using method:
To render image with
The file is protected by access token. In order to retrieve a file, the http request for that file needs to be authenticated. To integrate with :
If you already have your own implementation of OkHttpClient
, add using method:
Name
Data Type
Description
Attributes
userId
string
The id of this user
roles
Array.<string>
A list of user's roles
displayName
string
The display name of the user
flagCount
integer
The number of users that have flagged this user
metadata
Object
The metadata of the user
hashFlag
Object
A hash for checking internally if this user was flagged by the user
createdAt
date
The date/time the user was created at
updatedAt
date
The date/time the user was updated at
Channel Type
Discoverable by
Message sending privileges
Moderation access
Community
All users and admins
Users and admins
All Moderation tools
Live
Only members and admins
Users and admins
All Moderation tools
Broadcast
All users and admins
Admins
Admin Moderation tools
Conversation
Only members
Users
No Moderation tools
Channel Type
Discoverable by
Message sending privileges
Moderation access
Community
All users and admins
Users and admins
All Moderation tools
Live
Only members and admins
Users and admins
All Moderation tools
Broadcast
All users and admins
Admins
Admin Moderation tools
Conversation
Only members
Users
No Moderation tools
Name | Data Type | Description | Attributes |
|
| The id of this message | Content |
|
| The | Content |
|
| The number of messages with | Content |
|
| The name of the channel this message was created in | Content |
|
| The name of the user this message was created by | Content |
|
| The message type | enum*: |
|
| The message tags | Content |
|
| The message data (any text will be stored in |
|
|
| The message has been marked as deleted | Content |
|
| The sequence number of a message in channel | Content |
|
| The date/time the message was created at | Content |
|
| The date/time the message was updated at | Content |
|
| The date/time the message was edited at | Content |
|
| The number of users that have flagged this message | Content |
|
| A hash for checking internally if this message was flagged by the user | Content |
|
| The reaction data (stored as a reactionName and counter key/value pair) | Example: { |
|
| The total number of reactions on this message | Content |
|
| A list of user's reactions on this message | Content |
When a user is banned in a channel, they are removed from a channel and no longer able to participate or observe messages in that channel.
Moderators can ban and unban users. When a user is banned in a channel, they are forcebly removed from channel and may no longer participate or observe messages in that channel. All their previous messages in the channel will also be automatically deleted.
A user that has been banned from a channel can not rejoin the channel until they have been unbanned.
As well as the banning and unbanning of users, admins also have the ability to global ban a user. When a user is globally banned, they can no longer access Amity's network and will be forcebly removed from all their existing channels. All the globally banned user's messages will also be deleted.
The globally banned user can not access Amity's network again until they have been globally unbanned.
Banning users is a more heavy handed moderation method. When a user is banned, all its messages are retroactively deleted, it will be removed from the channel, and it will not be allowed to join the channel again until he is explicitly unbanned.
There is a separate unban call to unban a user:
Note: This feature does not work with Broadcast
and Conversation
channels. Calling banUsers()
or unBanUsers()
on these channels will result in an error.
Rate limiting a channel controls the speed of messages that is published to all concurrent clients in the channel
This method is useful when there is a large amount of messages going through the channel, which can make the message stream hard to follow. Setting a rate limit enables the SDK to queue up messages once the amount of message in a specified window
exceeds the defined limit
, allowing a slower stream of messages to be published to the user at the expense of adding more latency (because newer messages will be sent to the queue first and not delivered until all previous queued messages are delivered).
There is an internal limit of 1000 messages that can be queued by the rate limit service, if more than 1000 messages are queued up, the system may skip publishing the older messages in order to make room for newer messages. We believe this is the preferred behavior for users, as users will most likely want to see newer messages in a real-time conversation instead of waiting for a significant amount of time for old messages to be published to them first.
Note that the SDK permanently stores all messages it receives in the system before the rate limit comes into effect: in the case of a large spike of incoming messages, even if a message did not get published to a user in real-time, that user can still scroll up to see message history and see that past message.
The above method enables a rate limit of 5 messages every 60 seconds. Once a user sends more than 5 messages in 60 seconds, messages will be queued on the server and not published to other channel members until 60 seconds have passed.
In order to disable the rate limit, simply call EkoChannelModeration.removeRateLimit()
:
Note: This feature does not work with Broadcast
and Conversation
channel. Calling reateLimit()
or removeRateLimit()
on these channels will result in an error.
flag and unflag a message
While having moderators surveying your chats is great, it doesn't scale well. A way to overcome this is to let your users do the work for your moderators. By letting users flag other users or specific messages, the work of moderators is significantly reduced and democratized, thus allowing administrators to only respond to issues when deemed critical or absolutely necessary.
In order to flag a message, create an instance of EkoMessageFlagger
by calling EkoMessage.report();
Beware that each EkoMessageFlagger
is tied to only one specific message.
To flag a message, call the following method:
To unflag a message, call the following method:
The User can also check if they have previously flagged a message before by calling the following asynchronous method:
If this method has been called before in the current session, the user can also check the cached result on the message payload itself.
Flag and Unflag a channel user
While having moderators surveying your chats is great, this doesn't scale well. A way to overcome this is to let your users do the work for your moderators: by letting users report other users or specific messages, the work of moderators goes from scanning each message in each channel to investigate each user report (to both users and messages) and react only when deemed necessary.
In order to report a user, create an instance of EkoUserFlagger
by calling EkoUser.report();
Beware that each EkoUserFlagger
is tied to only one specific user.
To flag a user, call the following method:
To unflag a user, call the following method:
Ensure that your users don’t miss important content from each other.
With this solution live events are sent from Amity's servers to your servers: once an event lands on your servers, you have the full power and control on what to do with each notification, including editing/removing/stopping the notification before it reaches your users devices.
In this scenario there's no Android SDK involvement, as the whole notification is managed on your end.
With this solution, the notifications are triggered and delivered to your users directly by Amity's servers. There's nothing that the Android client has to do in order to display the notification to your users: Amity's servers will prepare a notification that can be directly displayed to the user.
As the Amity servers are responsible for choosing the content of the push notifications, you can expect your users to receive the following notifications for different kinds of events:
Event: New channel has been created and the user has been added among its members. Push Notification Title: %s
(%s
= New Channel display name) Push Notification Body: You're now member of %s!
(%s
= New Channel display name)
Event: A new member joins a channel of the user who is already an existing member of it
Push Notification Title: %s
(%s
= user display name) Push Notification Body: %1$s has joined %2$s
(%1$s
= user display name, %2$s
= channel display name)
Event: A new message is sent in a channel of the user who is already an existing member of it. Push Notification Title: %1$s (%2$s)
(%1$s
= user display name, %2$s
= channel display name) Push Notification Body: %s
(%s
= message text body if text message, Image Message
if image message, Special message
otherwise)
A new push notification will be sent to a specific user when:
A new message is sent in a channel of the user who is already an existing member of it
A new channel is created and the user is among the listed members of the channel on creation
A new member joins a channel of the user who is already an existing member of it
FCM dependency:
Before you can start receiving push notifications, you need to obtain a FCM unique token string that identifies each FCM client app instance:
You can initialize the services with the obtained token. Please note that the FCM token can be changed through application life cycle. Please make sure that the FCM token supplied to the messaging SDK is up to date. To notify the messaging SDK of the latest token, the following line of code can be called whenever necessary:
Since Google play services are banned in China, The messaging SDK provides Baidu push services as a substitute for FCM. The messaging SDK requires an api key and a secret key from Baidu:
Baidu dependency:
Note: Baidu push services require number of additional permissions. You can find a list of permissions here.
Baidu API key is needed for Baidu push services initialization:
Note: The messaging SDK always consider FCM as a primary push provider and Baidu as a secondary push provider. If the messaging SDK detects Google play services on the device, Baidu push services won't be initialized.
The registration will automatically pick up the active userId
, and Amity's back-end will start sending push notifications to the particular user. In the where where the active userId
has been changed, registration will be required again.
The de-registration allows you to pass an optional userId
:
if a valid userId
is passed, Amity's backend will stop sending push notifications to this device only if the currently active push notification associated with this device is also associated with that user. No action is taken otherwise.
if no userId
is passed, Amity's backend will stop sending push notifications to this device.
The SDK has three levels of notifications: to be sent, a notification has to pass throughout all three of them in order to be successfully delivered.
The levels are:
Network Level: (via Amity Social Cloud Console) turning off notifications at this level effectively disables push notifications for all of your customers.
User Level: (via client) A user can choose to entirely enable/disable the notifications that they receive (this is an absolute option: enable all or disable all). Please note that this setting is per user, not per device: regardless of which device sets this toggle, the new preference will take effect on all the devices where the user is logged in.
Channel Level: (via client) A user can choose to enable/disable notifications for a specific channel (where the user is a member). Again, this preference is per user, not per device.
In order to get and set the user level push notifications preference, we use the object EkoUserNotification
, obtained from EkoClient
:
For channel preferences we use the EkoChannelNotification
instead, obtained via an instance of EkoChannelRepository
or EkoChannel
:
This page contains an overview of all relevant changes made to the Amity Chat SDK modules and the latest version releases
Eko Messaging SDK 4.7.1 is released.
None
None
None
Optimize PagedList configuration
Fix incorrect pagination of categories
None
OKHTTP - 3.10.0
Retrofit - 2.4.0
Kotlin-std-lib - 1.3.72
Eko Messaging SDK 4.7.0 is released.
None
None
None
None
OKHTTP - 3.10.0
Retrofit - 2.4.0
Kotlin-std-lib - 1.3.72
Eko Messaging SDK 4.6.0 is released.
Change query option setIsLive(isLive: Boolean)
to setStatus(statuses: Array)
in EkoStreamQuery.Builder
. The user is now able to query live-stream videos based on its statues.
Query memberships by role. .role(role: String)
ImprovegetMyReactions()
performance on EkoMessage
, EkoPost
, EkoComment
None
OKHTTP - 3.10.0
Retrofit - 2.4.0
Kotlin-std-lib - 1.3.72
Eko Messaging SDK 4.5.1 is released.
None
None
None
Active user missing from community list when community has more than 10 members
None
OKHTTP - 3.10.0
Retrofit - 2.4.0
Kotlin-std-lib - 1.3.72
Eko Messaging SDK 4.5.0 is released.
Add query option setIsLive(boolean)
in EkoStreamQuery.Builder
. The user is now able to query currently live or ended live-stream videos.
Add new method getRecordings()
in EkoStream
model . The user is now able to get recorded videos.
None
None
None
None
OKHTTP - 3.10.0
Retrofit - 2.4.0
Kotlin-std-lib - 1.3.72
Eko Messaging SDK 4.4.2 is released.
Add automatic file name encoding for EkoFileRepository
upload API
Fixed incorrect behaviour of private community query.
Eko Messaging SDK 4.4.0 is released.
Add role
and permission
feature. Refer to Channel
and Community
documentation.
Add hasPermission(ekoPermission)
API to EkoClient
Refer to Permission
documentation.
Add AUDIO
message type.
Add getUploadInfo(uploadId)
API to EkoFileRepository
Due to revised role
and permission
feature, user'sglobal role
can only be set from admin panel/ admin API, hence the removal of setRoles()
from EkoClient
. User would still be able to add / remove role at Channel
and Community
level should they have necessary permissions.
Aligning file related message data return type with Feed
feature,
Replacing getUrl() : String
with getImage() : EkoImage
inEkoMessage.Data.IMAGE
Replacing getUrl() : String
with getFile() : EkoFile
inEkoMessage.Data.FILE
Eko Messaging SDK 4.2.0 is released.
Introduce new Channel types; Community
and Live
. Refer to Channels
documentation.
Introduce new EkoClient.registerDevice(userId)
API where displayname
is optional. Refer to Setup
documentation.
Deprecating Channel type Standard
and Private
Deprecating EkoClient.registerDevice(userId, displayname)
API
Eko Messaging SDK 3.2.6
is released.
Change return type of getMessage(String messageId)
API from EkoLiveData
to Flowable
Missing user data from getMessage(String messageId)
API
Eko Messaging SDK 3.2.3
is released.
Return EkoChannel
with createConversation()
Eko Messaging SDK 3.2.2
is released.
Add metadata
createChannel(String channelId, EkoChannel.CreationType type, EkoChannel.CreateOption option)
API
Add metadata createConversation(String userId, JsonObject metadata)
API
Prevent crash on EkoPagedListAdapter
Eko Messaging SDK 3.2.1
is released.
Add getAllUsers(EkoUserSortOption option)
API
Add searchUserByDisplayName(String displayname, EkoUserSortOption option)
API
Optimized socket rescheduling request queue.
Improved diffUtil logic of EkoChannelAdapter
and EkoChannelMembershipAdapter
.
Eko Messaging SDK 3.1.1
is released.
Add getMessage(String messageId)
API
Eko Messaging SDK 2.8.0
is released.
Add getMessage(String messageId)
API
Eko Messaging SDK 3.0.0
is released.
New channel types (Private, Broadcast, Conversation); Support creation and query of new channel types.
Creating a channel requires a EkoChannel.CreationType
as a parameter.
Channel query has been converted to builder pattern to support query of new channel types.
EkoChannelRepository.getOrCreatedById()
is deprecated.
EkoChannelRepository.getChannelCollection()
returning LiveData> is deprecated.
Eko Messaging SDK 2.7.1
is released.
Fixed message query failed for the channel creator that has null
displayname.
Eko Messaging SDK 2.7.0
is released.
Added Optimistic logic for add / remove reactions. Reaction count reflects instantly upon API call and automatically reverts in case of error.
Update DiffUtil
logic in EkoMessageAdapter
.
Eko Messaging SDK 2.6.2
is released.
Fixed myReaction
is inaccurate when the same user is on multi devices.
Eko Messaging SDK 2.6.0
is released.
Add support of metadata for EkoUser
Eko Messaging SDK 2.5.1
is released.
Fixed myReaction
value stops EkoMessage
observation.
Eko Messaging SDK 2.5.0
is released.
Add Message reaction feature:
A reaction can be added or removed from a message with EkoMessageReactor
.
A reaction collection of a message can be queried with EkoMessageRepository
.
Add Reaction related data to EkoMessage
.
Eko Messaging SDK 2.3.0
is released.
A message can only be deleted by an editor corresponding to its type.
Add editor for each message type
EkoTextMessageEditor
can edit and delete a message of type text
.
EkoImageMessageEditor
can delete a message of type image
.
EkoFileMessageEditor
can delete a message of type file
.
EkoCustomMessageEditor
can edit and delete a message of type custom
.
Eko Messaging SDK 2.1.1
is released.
All message types are now based on Builder pattern.
The method build()
is now required to be called before the method send()
.
When creating an Image message with EkoMessageCreator
, a valid file Uri is required to be passed as a parameter.
Add File message type: a message of this type can be created with a file Uri. The file is automatically uploaded to the server and can be retrieved with a url that is accessible in FileData
model.
Add Custom message type: a message of this type can be created with a JsonObject
. This object is included in the data
property of the message. Developers can parse their customed data by creating a model that reflects the structure of the customed JsonObject
.
Eko Messaging SDK 2.0.0
is released.
Migrate to AndroidX
EkoMessageRepository
replaces the function getMessageCollection(channelId)
with getMessageCollection(channelId, stackFromEnd)
, along with many other new options such as getMessageCollection(channelId, includingTags, stackFromEnd)
, getMessageCollection(channelId, includingTags, excludingTags, stackFromEnd)
.
Message tagging support:
Messages can now be sent along with customized tags.
Messages can now be filtered by tags (both including and excluding).
Tags can also be set on any message.
Every message has a new tags
property.
Message sorting support:
Messages can now be fetched from the oldest first, or the newest first.
Message parenting support:
Messages can now be connected on creation by passing a new optional parentId
value.
Note how a message child can also become a parent itself, without any limit.
The parentId
must be passed on the child message creation and cannot be changed afterwards.
Every message has a new optional parentId
and childrenNumber
property.
Eko Messaging SDK 1.12.0
is released.
Push notification services in China.
Eko Messaging SDK 1.10.1
is released.
Fixed EkoMessage
collection doesn't contain messages sent while you were offline.
Fixed EkoClient.getUserId()
and EkoClient.getDisplayName()
return data of in-active account.
Eko Messaging SDK 1.10.0
is released.
Add Push Notification toggles: users can now choose to mute selected channels or stop receiving notifications completely from any device. The new settings, documentented in the Notifications section, are per user, not per single device.
Eko Messaging SDK 1.9.0
is released.
Add Push Notification feature: developers can call register and unregister for push notification directly from the EkoClient
Read more about the feature in the new Notifications section.
Eko Messaging SDK 1.8.0
is released.
Add new EkoError.USER_IS_GLOBAL_BANNED
when a user is banned globally is automatically unregistered and the EkoChat sdk will be on a clean state.
Eko Messaging SDK 1.7.0
is released.
EkoChannelRepository.getChannelCollectionByTags(filter, includingTags)
returns List of channels with ANY provided tags.
EkoChannelRepository.getChannelCollectionByTags(filter, includingTags, excludingTags)
returns List of channels with ANY provided tags AND without ANY provided tags.
Added two new channel types EkoChannel.Type.BROADCAST
and EkoChannel.Type.CONVERSATION
(channels with conversation type won't be seen in Admin Panel because of privacy concerns)
Eko Messaging SDK 1.6.0
is released.
EkoChannelMembershipRepository.getChannelMembershipCollection(channelId)
returns List of memberships of the channel.
Eko Messaging SDK 1.5.0
is released.
EkoMessage.isFlaggedByMe()
and EkoUser.isFlaggedByMe()
tell whether you've already flagged this EkoMessage
and EkoUser
or not.
Eko Messaging SDK 1.4.0
is released.
You can now be able to flag/unflag a message EkoMessageRepository.report(messageId).flag()
or EkoMessage.report().flag()
and EkoMessageRepository.report(messageId).unflag()
or EkoMessage.report().unflag()
You can now be able to flag/unflag a user EkoUserRepository.report(userId).flag()
or EkoUser.report().flag()
and EkoUserRepository.report(messageId).unflag()
or EkoUser.report().unflag()
Eko Messaging SDK 1.3.0
is released.
EkoMessage.getEditedAt()
returns DateTime instead of string.
EkoChannel.membership().startReading()
will not return anything.
EkoChannel.membership().stopReading()
will not return anything.
EkoLiveData
will no longer return a proxy object.
if you are in a live reading mode and lost internet connection, The SDK will automatically re-enables the live reading mode after re-gaining internet connection.
EkoChannel.getLastActivity()
returns updated DateTime after receiving all message events.
EkoChannel.getUnreadCount()
returns zero after joining a channel.
3 new error codes which are INVALID_REGULAR_EXPRESSION(400001)
, TOO_MANY_MEMBER_ERROR(400310)
and RPC_RATE_LIMIT_ERROR(400311)
Fixed EkoChannel
collection with the filter EkoChannelFilter.NOT_MEMBER
not contains channel you are banned from.
Eko Messaging SDK 1.1.2
is released.
Fixed EkoChannel
collection with the filter EkoChannelFilter.NOT_MEMBER
contains channel you joined.
Fixed EkoChannel
data not update in real-time.
Eko Messaging SDK 1.1.0
is released.
The parameterless EkoChannelRepository.getChannelCollection()
method now required a single parameter of EkoChannelFilter
.
Delete message
Unread message count
You can create a EkoChannel
collection that contains
EkoChannelFilter.MEMBER
: channels that you have joined.
EkoChannelFilter.NOT_MEMBER
: channels in the system which you haven't joined.
EkoChannelFilter.ALL
: all channels.
Live Reading: Eko Messaging SDK now supports live reading mode. When you are in live reading mode, all new message are marked as read automatically.
EkoChannel.membership().startReading()
: enables live reading mode. Should be called in onResume()
method.
EkoChannel.membership().stopReading()
: disables live reading mode. Should be called in onPause()
method.
EkoMessageRepository.getCount()
is deprecated.
EkoMessageRepository.getCount(channelId)
is deprecated.
Eko Messaging SDK 1.0.2
is released with improved network bandwidth efficiency.
Fixed EkoMessage.getUser()
returns null
instead of EkoUser
the sender of the message.
Eko Messaging SDK 1.0.1
is released with internal changes.
Eko Messaging SDK 1.0.0
is released.
Introduce eko-video-publisher
for video broadcasting. Refer to documentation.
Add manual paging functionality to EkoCommentQuery
Refer to documentation.
Add new option .roles(roles: List<String>)
inEkoChannelMembershipQuery.Builder
. Refer to documentation.
Add new option .sortBy(option: EkoCommentSortOption)
in EkoCommentQuery.Builder
. Refer to documentation.
Add new API getLatestComment()
in EkoCommentRepository
. Refer to documentation.
Add custom dataType
support for EkoPost
. Refer to documentation.
Applied a workaround for (IndexOutOfBoundException
in AsyncPagedListDiffer
) to EkoChannelAdapter
, EkoMessageAdapter
, EkoMessageReactionAdapter
, and EkoChannelMembershipAdapter
.
Moving repository from Bintray to Jitpack,
EkoClient.registerDeviceForPushNotification()
method is now parameterless,
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.
You can convert an EkoException
into EkoError
enum with the following:
When an error is returned as a result of an action from your side (e.g. trying to join a channel), the action can considered complete, and the SDK will not execute any additional logic.
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.
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
Error
Code
UNKNOWN
800000
INVALID_PARAMETER
800110
MALFORMED_DATA
800130
FILE_SIZE_EXCEEDED
800140
CONNECTION_ERROR
800210