Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This module allows for richer, interactive experiences by enabling video stories and live streaming on your application
More than ever, videos are increasingly dominating mobile screens. From fun short-form clips to promote new products to live-streamed talk shows to educate your customers, videos have the potential to transform the way customers experience your brand.
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.
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
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:
Host your events virtually and see community interaction as it happens
Live streams and playback videos information are stored in EkoStream
. This stream objects reside in EkoStreamRepository
. To start working with stream, first the app need to intialize the repository.
*Note : There is a limitation for the maximum concurrent live events. Please feel free to reach out to us at developer@amity.co with your use-case and we will determine if the current limit can be raised.
Each stream object has a unique identifier. To retrieve a single stream object.
This function returns a flowable of EkoStream
. The stream object contains essential data, for example, title and description.
Stream consists of many states. It can change from one state to another, depending on events and actions.
Ekostream.Status
represents a stream status. The following enum cases describe all the possible status of a stream.
.IDLE
indicates "a stream that has generated but no actions have been taken."
.LIVE
indicates "a stream is currently being broadcasted."
.ENDED
indicates "a stream has ended broadcasting and in the progess of transforming to a recorded stream."
.RECORDED
indicates "a stream has ended broadcasting and has been transformed to a recorded stream."
You can check the status of a stream by calling stream.getStatus()
.
EkoStreamRepository provides a convenient method getStreamCollection
and also call setStatus(statuses: Array<Ekostream.Status>)
to query live streams. We provide enums of stream status as Ekostream.Status
You can observe changes in a collection as per the defined statuses.
To play a live stream, currently FLV, RTMP and HLS protocol are supported by calling getWatcherData.getUrl()
inside the stream object. The parameter accepts streamId and enum of EkoWatcherData.Format.
This function provides request/response API. The callback of this function returns string of the url.This object contains a full FLV, RTMP or HLS url.
To play a recorded stream, currently FLV, MP4 and M3U8 protocol are supported by calling getRecordings()[index]
inside the stream object. The parameter accepts streamId and enum of EkoWatcherData.Format.
This function provides request/response API. The callback of this function returns string of the url.This object contains a full FLV, MP4 or M3U8 url.
For FLV we highly recommend to use DefaultDataSourceFactory
For RTMP we highly recommend to use the RtmpDataSourceFactory
​​​​
We recommend to use from Google. ExoPlayer supports features not currently supported by Android’s MediaPlayer API, including DASH and SmoothStreaming adaptive playbacks. Unlike the MediaPlayer API, ExoPlayer is easy to customize and extend.
To broadcast a live stream video, we provide a convenient broadcaster tool called EkoStreamBroadcaster
. We now only support 16:9 video ratio with the following resolution representing by the enum EkoStreamBroadcastResolution
:
.SD_480P
indicates a video with resolution 480x854 and video bitrate 1216 kpbs
.HD_720P
indicates a video with resolution 720x1280 and video bitrate 2496 kpbs
.FHD_1080P
indicates a video with resolution 1080x1920 and video bitrate 4992 kpbs
You simply need to include this dependency to your project in build.gradle
in the application level.
Inside your Application class, in the application initialisation process, you need to register the video publisher sdk to the core sdk by calling.
We highly recommend to use Android's ConstraintLayout to construct our EkoCameraView
Since we only support 16:9 video ratio, ConstratntLayout will ensure that the view will be drawn in the correct width and height.
EkoStreamBroadcaster
requires the following permissions to work properly.
As per the required parameter by the aforementioned object to provide EkoCameraView
, you will need to define the view in your Activity or Fragment layout by :
Camera access
Microphone access
Before using EkoStreamBroadcaster
, please make sure these permissions are granted.
See here the steps to ask for the permissions.
In order to create the object, we also provide a EkoStreamBroadCaster.Builder
class to create and configure this object easily. It requires EkoCameraView
as a parameter and EkoStreamBroadcasterConfig
as a configurable value which will be explained in the following section.
For configuration, we provide a EkoStreamBroadcasterConfiguration.Builder
to construct the configuration conveniently. As we have mentioned above, We support SD_480P
, HD_720P
and, FHD_1080P
resolutions. Orientations are relying on Android Configuration class, you may either choose Configuration.ORIENTATION_PORTRAIT or Configuration.ORIENTATION_LANDSCAPE
.
As per the required parameter by the aforementioned object to provide EkoCameraView
, you need to define the view in your Activity or Fragment layout by :
We highly recommend to use Android's ConstraintLayout to construct our EkoCameraView
Since we only support 16:9 video ratio, ConstratntLayout ensures that the view will be drawn in the correct width and height.
To begin previewing the camera input call
To begin broadcasting live stream call
To stop broadcasting live stream call
By default, the broadcaster will use the back camera. However you can switch camera position anytime by calling.
To observe the status of a broadcast, we provide a function (flow) to observe any status changes and return as EkoStreamBroadcasterState
. The possible statuses are :
.IDLE
indicates a status of stream in an idle state.
.CONNECTING
indicates a status of stream that it's connecting to a rtmp server.
.CONNECTED
indicates a status of stream that it's connected to a rtmp server.
.DISNNECTED(e:Exception)
indicates a status of stream that it's disconnected to a rtmp server. We also provide an error information through an exception.
Make users share their life snippets through their short videos
This functionality is not currently supported for Android but will be coming soon! We will update the relevant sections accordingly in good time
Ensure that your users don’t miss important content from each other
This functionality is not currently supported for Android but will be coming soon! We will update the relevant sections accordingly in good time
This page contains an overview of all relevant changes made to the Amity Video SDK modules and the latest version releases
Eko Messaging SDK 4.7.2 is released.
New APIs
Add a function to observe broadcasting status in EkoStreamBroadcaster. For further information please see here.
Breaking APIs
None
Deprecations
None
Fixes
None
Behavioural changes
None
Compatibility
OKHTTP - 3.10.0
Retrofit - 2.4.0
Kotlin-std-lib - 1.3.72
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.
Introduce eko-video-publisher
for video broadcasting. Refer to Video documentation.
Add manual paging functionality to EkoCommentQuery
Refer to Comment documentation.
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.
Add new option .roles(roles: List<String>)
inEkoChannelMembershipQuery.Builder
. Refer to Channel
documentation.
Add new option .sortBy(option: EkoCommentSortOption)
in EkoCommentQuery.Builder
. Refer to Comment
documentation.
Add new API getLatestComment()
in EkoCommentRepository
. Refer to Comment
documentation.
Add custom dataType
support for EkoPost
. Refer to Feed
documentation.
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
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