Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The Video SDK for iOS is delivered as a binary .xcframework file
Install: Homebrew using: /bin/bash -c “$(curl -fsSL
https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
or see more instruction at https://brew.sh
Install: git-lfs using: brew install git-lfs
Starting from version 4.3, the use of the .xcframework will reduce the required number of installation steps and also support the use of same binary, even when the Xcode version changes. We also include an additional framework as a dependency: Realm.
In order to properly install the SDK, you must make sure to import and link both frameworks. XCFrameworks for both realm & our Video SDK are bundled together for your convenience, this can be downloaded using the link below:
Drag EkoChat.xcframework
and Realm.xcframework
to your project's Embedded Binaries
. Make sure that Copy items if needed
is selected and click Finish. Also switch the Embed section as Embed & Sign
.
Carthage is a decentralised dependency manager that builds your dependencies and provides you with binary frameworks. To integrate the Amity Video SDK, add the following line of code to your Cartfile
.
To integrate the Amity Video SDK into your Xcode project using CocoaPods, specify the following line of code in your Podfile
:
Please check if you have git-lfs installed and clear cocoapod cache before running install again
To clear cache please go to ~/Library/Caches/Cocoapods/ and remove Amity SDK folder - you should be able to run a clean install afterward
If this doesn't work, please do visit the cocoapod Github repo for further resolutions.
Here are the steps to migrate from the previous version of our SDK to the new .xcframework
Remove and unlink EkoChat.framework
and Realm.framework
from your project.
Remove custom Run Script Phase
that is required for the version prior to v4.3. strip-frameworks.sh
is no longer required, since .xcframework
automatically handles the fat binary issue.
Copy and link EkoChat.xcframework
and Realm.xcframework
to your project. And set Embed & Sign
.
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, call
repository.getStreamById(_:)
This function returns a Live Object 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.
EkoStreamStatus
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 progress 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 .status
.
To query streams collection, first you need to create a EkoStreamCollectionQuery
.
Then call .getStreamsCollection(from:)
with the query object that you've created.
.getStreamsCollection(from: query)
This function returns the live collection of stream objects.
If your app needs stream collections in many parts of the app. We recommend to maintain only one collection for each query, in an application scope. And use it as a single source of truth.
To play a live stream, currently only RTMP protocol is supported, call
stream.watcherUrl
EkoLiveStreamURLInfo
contains a full RTMP url, which most of RTMP players support. For some players that does not support the full url, this object contains enough data for custom RTMP url formatting.
EkoStream
has isLive
property.
When there is an update of live object, use isLive
property to check.
When there is an update of live stream collections:
The streams that are not live, will disappear from the collection.
The streams that are just live, will appear in the collection.
RTMP is a low-latency video streaming protocol, that iOS does not support in its native video player. Therefore when working with RTMP, here are some open-source players that we recommend:
Live streams are recorded, and saved as files after the session ends. It would take some time for preparing recorded videos to be ready. You can observe the collection of stream that has recorded videos available, by calling
streamRepository.getRecordedStreams()
Each live stream session can contain multiple recorded videos. You can retrieve the array of EkoLiveVideoRecordingData
that store all recording data, by calling
stream.recordingData
To get the actual url, you need to specify the file format by calling on a recorded item.
recordingItem.url(for: EkoLiveVideoRecordingFileFormat)
The following code shows an example of getting all the mp4 url of a stream instance.
In contrast with RTMP live videos, you don't need 3rd party video players for the recorded videos. iOS native players already support playing mp4 file from the URL given by API.
Amity Video SDK includes UpstraVideoPlayerKit.framework
, a basic RTMP player to support live video functionality.
This framework requires MobileVLCKit.framework
as a dependency. You can download it from the link below.
See also and .
To broadcast a live stream video, we have provided a convenient broadcaster tool called EkoStreamBroadcaster
. You will need to import EkoLiveVideoBroadcastKit.framework
into your app.
EkoStreamBroadcaster
requires the following permissions to work properly.
Camera access
Microphone access
Before using EkoStreamBroadcaster
, please make sure these permissions are already granted.
Here are the steps to ask for the permissions.
Add NSCameraUsageDescription
to your app's info.plist
.
Add NSMicrophoneUsageDescription
to your app's info.plist
.
Call AVCaptureDevice.requestAccess(for: .video, completion: ...)
Call AVAudioSession.sharedInstance().requestRecordPermission(_:)
You can create broadcaster instance by providing EkoClient
.
Before going live, you will need to setup the broadcaster session by creating EkoStreamBroadcasterConfiguration
. This configuration will be applied for the next live session.
The broadcaster object provides "preview view". After finish setting up the broadcaster, you then can take the preview view to attach into your screen.
You can setup video resolution anytime "before" going live. This setting will affects both the rendering of preview view, and the resolution of live stream session.
To begin broadcasting the live stream, call
To stop broadcasting the live stream, call
By default, the broadcaster will use the back camera. However you can switch camera position anytime by calling
To observe a broadcaster state, we provide a delegate object that you can set to listen broadcaster's events..
EkoStreamBroadcasterState
represent all the possible states.
.idle
indicates a state of stream in an idle state.
.connecting
indicates a state of stream that it's connecting to the stream server.
.connected
indicates a state of stream that it's connected to the stream server.
.disconnected
indicates a status of stream that it's disconnected.
The code below show an example of printing out the state of broadcaster, when it changes.
Error objects can be returned to you via LiveObjects, callbacks, or clientErrorDelegate
. All the errors returned by the SDK come in form of an NSError with domain Eko
. The possible error codes are listed in a public EkoErrorCode
enum: each case is named after its error and they're pretty self explanatory.
UnauthorizedError: 400100
ItemNotFound: 400400
BadRequestError: 400000
Conflict: 400900
ForbiddenError: 400300
PermissionDenied: 400301
UserIsMuted: 400302
ChannelIsMuted: 400303
UserIsBanned: 400304
NumberOfMemberExceed: 400305
ExemptFromBan: 400306
MaxRepetitionExceed: 400307
BanWordFound: 400308
LinkNotAllowed: 400309
GlobalBanError: 400312
BusinessError: 500000
Unknown: 800000
InvalidParameter: 800110
MalformedData: 800130
ErrorQueryInProgress: 800170
ConnectionError: 800210
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.
The EkoClient
includes a clientErrorDelegate
property that can be set to an error handler delegate class on your application. This error delegate gives you a chance to be notified of errors that can potientially 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 delegate (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.
This functionality is not currently supported for IOS 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
Introduce a completion parameter to registerDeviceWithUserId(:_)
in EkoClient
None
Fixed issue where categories property of community is updated incorrectly when fetching list of community categories.
None
Fix crash when setting up custom avatar for in EkoClient
class.
None
Add EkoLiveVideoBroadcastKit.xcframework
. The tool helps broadcasting live video from mobile.
Add live video broadcasting functionalities in the sample app.
Add recorded video url API
Add a beta version of Amity Video Player, a basic RTMP player for sample app live video.
This section outlines how you can set-up your project for success and begin using our Video SDK for iOS application
Before using the Video 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 Video 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 Video 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 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.
The connectionStatus
flag supports KVO notifications, use NSObject
's observe methods to be notified whenever this status changes
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.
Make users share their life snippets through their short videos
This functionality is not currently supported for IOS, but will be coming soon! We will update the relevant sections accordingly in good time.
In iOS, LiveObjects are represented by the EkoObject
and EkoCollection
classes. EkoObject
represents live updates on one model, while EkoCollection
represents live updates on a collection of models.
Observing live changes to any EkoObject
can be done via a simple observe block:
In this example the block observes the data of the currently authenticated user and prints out the displayName
. The observe block can be called multiple times throughout the lifetime of the application (as long as its associated EkoNotificationToken
is retained in memory):
If the requested object data is stored locally on the device, the block will be called immediately with the local version of the data (this can be verified this through the EkoObject
property dataStatus
).
In parallel, a network request for the latest version of the data is fired, once the network returns the data, the observe block will be called again with the updated data.
Any future changes to the data (whenever the user changes its displayName
on another device, for example) can trigger additional callbacks.
Any UI update logic can be performed within the observe blocks, which will always be called in the main thread: this way, you can ensure that your UI displays the most up-to-date version of the state at all times.
In case you'd like to operate exclusively with fresh data, without using the potientially out-of-date local data, you can make sure to do so by reading the
EkoObject
dataStatus
property, which reflects the status of the callback data, and check that its value is set to fresh.You can also use the
EkoObject
loadingStatus
property to determine the current state of network operations being performed by the LiveObject. This is useful for any UI element that needs to communicate the loading state.
The EkoNotificationToken
is a token that is used to control the lifecycle of a LiveObject. The observeWithBlock
callback will be triggered only if the notificationToken
is retained in memory: once it is released, the observe block will no longer be called, and its memory will be automatically released. Hold a strong reference to any EkoNotificationToken
whose block you would like still to be called.
Beside the
observeWithBlock
method, aobserveOnceWithBlock
method is also available, which will trigger its callback only once, regardless of thedataStatus
of the callback and the associated token retainment (the token still needs to be retained to fire once).To stop receiving
observeWithBlock
updates, release the associatedEkoNotificationToken
or callinvalidate
method on the token itself.
An EkoCollection
instance is given for any queries that return a list of objects. EkoCollection
has the same change observation interface as EkoObject
, but contains a few other helper methods around data access that allows better integration with collection views like UITableView
.
Unlike most databases, EkoCollection
does not return all data in an array. Instead, data are fetched one-by-one using the objectAtIndex:
method. This allows the framework to store most of the actual result on disk, and load them in memory only when absoutely necessary. Additionally, the objectAtIndex:
API fits perfectly into UITableView
's tableView:cellForRowAtIndexPath:
. Together with the count
property, a typical tableView
integration looks like this:
EkoCollection
offers both a nextPage
and previousPage
methods which will trigger a local cache lookup, a network call, and multiple LiveObject updates once new data is returned. After the method call is successful, the number of records returned by EkoCollection
will be increased by the additional number of new records. For the typical use case of infinite scroll, you can call nextPage
directly in the scroll view delegate method:
Lastly, if there is a need to shrink the list of models exposed back to original first page, when passing the EkoCollection
object to a new view for example, you can do so by calling resetPage
into the collection itself.