Each channel is identified by an 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 Upstra 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
:
val channelRepository = EkoClient.newChannelRepository();
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.
// create channel by specifying channelIdchannelRepository.createChannel().communityType().withChannelId("Weekly-promo").displayName("Weekly promo") // optional.metadata(jsonObject) // optional.tags("promotions") // optional.build().create().subscribe()​// let SDK handle channelId generationchannelRepository.createChannel().communityType().withDisplayName("Weekly promo").metadata(jsonObject) // optional.tags("promotions") // optional.build().create().subscribe()
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.
// let SDK handle channelId generationchannelRepository.createChannel().conversationType().withUserId(userId).displayName("BFF") // optional.metadata(jsonObject) // optional.tags("friends") // optional.build().create().subscribe()
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.
channelRepository.joinChannel(channelId).subscribe()
In the case where you only want to fetch a channel's data without joining, you can use the getChannel()
method:
channelRepository.getChanel(channelId).subscribe( { ekoChannel -> ... } )
The EkoChannelRepository
provides the getChannelCollection()
method which initiates channel query method chain. The query returns Flowable<PagedList<EkoChannel>>
representing all matching channels available.
// Query for Community typechannelRepository.getChannelCollection().communityType().build().query().subscribe( { adapter.submitList(it)} )​// Query for Live typechannelRepository.getChannelCollection().liveType().build().query().subscribe( { adapter.submitList(it)} )​// Query for Broadcast typechannelRepository.getChannelCollection().broadcastType().build().query().subscribe( { adapter.submitList(it)} )​// Query for Conversation typechannelRepository.getChannelCollection().conversationType().build().query().subscribe( { adapter.submitList(it)} )​// Query for Multiple typesval types : List<EkoChannel.Type> = // create a list of your desired types​channelRepository.getChannelCollection().types(types).build().query().subscribe( { adapter.submitList(it)} )
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
val includingTags = EkoTags()includingTags.add("games")​// Query for Community channels where the user is member, tagged as "games"channelRepository.getChannelCollection().communityType().filter(EkoChannelFilter.MEMBER).includingTags(includingTags).build().query().subscribe( { adapter.submitList(it)} )
val includingTags = EkoTags()includingTags.add("games");​val excludingTags = EkoTags()excludingTags.add("staff-only")​// Query for Community channels where the user is not member, tagged as "games", and not tagged as "staff-only"channelRepository.getChannelCollection().communityType().filter(EkoChannelFilter.NOT_MEMBER).includingTags(includingTags).excludingTags(excludingTags).build().query().subscribe( { adapter.submitList(it)} )
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:
val metadata = channel.getMetadata()metadata.addProperty("tutorial_url", "https://docs.ekomedia.technology/")​channelRepository.getChannelCollection().updateChannel(channelId).metadata(metadata).build().update().subscribe()
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:
channelRepository.setDisplayName(channelId, "General Eko chat discussion");
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.
// Access from EkoChannelRepositoryval membership = channelRepository.membership(channelId)​// EkoChannel object already knows its channelIdval membership = channel.membership();
The EkoChannelParticipation
provides a list of members in the given channnel
membership.getCollection().build().query().subscribe( { adapter.submitList()} )
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.
// Add 'user1' and 'user2' to this channelmembership.addUsers(listOf("user1", "user2")).subscribe()​// Remove 'user3' from this channelmembership.removeUsers(listOf("user3")).subscribe()​// Leave the channelmembership.leave().subscribe()
Creator of channel can add and remove role of user via EkoChannelModeration
.
//Add roleEkoClient.newChannelRepository().moderate(:channelId).addRole(role = :roleName, userIds = listOf(:userId)).subscribe()​//Remove roleEkoClient.newChannelRepository().moderate(:channelId).removeRole(role = :roleName, userIds = listOf(:userId)).subscribe()
The EkoChannelParticipation
provides a list of members by role in the given channnel.
EkoClient.newChannelRepository().membership(:channelId).getCollection().roles(listOf(:roleName)).build().query().subscribe()
Note: This method .role(role:String)
is deprecated. You can still use old function if you don't want send role in list type
You can check your permission in channel by send EkoPermission enums to EkoClient.hasPermission(:ekoPermission)
method.
EkoClient.hasPermission(:ekoPermission).atChannel(:channelId).check().subscribe()
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.
// total unread countchannelRepository.getTotalUnreadCount().doOnNext( totalUnreadCount -> {​}).subscribe();​// channel unread countval unreadCount = channel.getUnreadCount()
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.
// Start reading a channelmembership.startReading()​// Stop reading a channelmembership.stopReading()