Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Amity Social Cloud offers Chat and Social SDKs to streamline app development. Dive into our UI Kits and documentation to spark your creativity.
Amity is a technology infrastructure provider that builds ready-to-use social features that can be easily added to any app or website, including: Chat, Profile, Forum, Feed, Video Streaming, Stories, and more.
With Amity’s white-label APIs and SDKs, companies can build thriving communities and grow user engagement, without the hassle of deploying and maintaining any server infrastructure.
Let users create engaging content and engage with others through comments and reactions. Users can follow other users or topics and become members of various groups to get a personalized timeline of content. Activity feeds are also a great feature to directly engage with users. You can communicate with your users directly by posting important messages as announcements.
Connect users through formation of communities
Boost user engagement by user-generated posts/comments in communities
Personalize the feed based on user’s membership to different groups and communities
Enable comments on posts within your application, seamlessly
Support multiple messaging formats when posting content
Manage & moderate communities and users in admin panel
Filter out content that includes profanity using our auto-block tools
React to user-generated content with our reaction tools
Assign roles and permissions on a role-based system.
Explore our Technical FAQ for quick answers to common questions about Amity products. Get troubleshooting tips, best practices, and insights to optimize your technical experience.
For further assistance or if you have any questions, or require clarification on any technical matters, please do not hesitate to reach out to our dedicated support team at support.asc@amity.co
Release notes, key changes and deprecation notices
We are excited to inform you about the recent updates we have made to our product to enhance your experience. These changes are scheduled for deployment as follows: 🔜 9th August: SG Region 🔜 10th August: EU & US Region. The best part is that these modifications will take effect immediately without requiring any action from your end to update the version.
Now, let's take a look at what will be changed:
Post creators will still have the ability to view their own soft-deleted posts.
Admins/Super Admins will still retain the privilege to view user's soft-deleted posts.
Non-Admin users, however, will no longer be able to access soft-deleted posts of other users.
Moderators & Global Moderators, will also no longer be able to access soft-deleted posts of other users.
Should you have any concerns or questions regarding these changes, please do not hesitate to reach out to us. We value your feedback and are here to assist you!
We'd like to announce that we will be deprecating v3/files
API in favor of v4/images
API for our image moderation feature. Effective 1 January 2024, v3/files
will no longer support image moderation. If you are using v3/files
to upload images, we recommend that you switch to using v4/images
instead.
To ensure a smoother transition process, we have already updated the iOS and Android SDKs in version 6.6.0, as well as Flutter SDK beta 0.21.0 to point to the new endpoint for uploadImage()
. Therefore, if you wish to continue using the image moderation feature, you will need to upgrade to Android or iOS SDK 6.6.0 or higher; or Flutter beta 0.21.0 before 1 January 2024. After this date, v3/files
and any SDKs below the aforementioned versions will no longer support image moderation. There is no impact to TypeScript SDK users as the SDK is already using v4/images
.
What this means if you wish to continue having images moderated:
Android & iOS: You will need to upgrade to Android or iOS SDK 6.6.0 or higher (or UIKit 3.1.0 or higher), before 1 January 2024. After this date, v3/files
and any SDK version below 6.6.0 (or UIKit 3.0.0 and below) will no longer support image moderation
Flutter: You will need to upgrade to Flutter SDK beta 0.21.0 or higher, before 1 January 2024. After this date, v3/files
and any SDK version below beta 0.21.0 will no longer support image moderation
TypeScript: There is no impact to TypeScript SDK users as the TS SDK is already using v4/images
If you have any concerns or questions about this deprecation notice, please do not hesitate to contact our support team.
20 October 2022
Today we are announcing the deprecation of RxJava2 and PagedList for Amity Android SDK, as we will be migrating from RxJava2 to RxJava3 and from PagedList to PagingData, effective January 1, 2023.
If you are using RxJava2 and PagedList, the last version that supports them (which will be released in December 2022) will continue to be maintained until 31 October 2023.
From 1 November 2023, Rxjava2 and PagedList will no longer be supported.
Although we will not stop supporting RxJava2 and PagedList until October 2023, we recommend that you start planning your upgrade around Q4 2022, from RxJava2 to RxJava3 and from PagedList to PagingData.
Separately, we will also be upgrading our SDK to support RxJava3 and PagingData in the coming weeks. Once the upgrade is complete, we will remove RxJava2 and PagedList from future versions of the SDK.
Updated: 19 September 2022
Today we are announcing the deprecation of Objective-C for Amity iOS SDK as we will be migrating from Objective-C to pure Swift, effective 1 January 2023.
What this means:
If you're using Objective-C to build your app, the last version that supports Objective-C (that will be published in December 2022) will continue to be maintained until 30 September 2023.
Starting 1 October 2023, Objective-C will no longer be supported.
Although we will only be ending the support of Objective-C in October 2023, we recommend that you start planning the upgrade around Q4 2022.
Xcode 14 Upgrade & Minimum Deployment Target Upgrade from iOS 12 to iOS 13
Separately in the coming weeks, we will also be upgrading our SDK to support Xcode 14, and will be raising the minimum deployment target from iOS 12 to iOS 13. Once the minimum target upgrade occurs, we will be dropping iOS 12 & Xcode 13 support from future versions of the SDK.
What’s in store with iOS 13+ upgrade:
There are many new enhancements coming along with this upgrade, such as async/await APIs that help you to work easier with asynchronous programming. Migrating to Swift also comes as a cost-effective method in developing and maintaining your projects.
Updated: 21 June 2022
Amity Social Cloud will be deprecating all managed versions of the UI Kits (IOS, Android and Web J.S.) on 31 August 2022 as requests to be able to further customize their look and feel have increased. Our UI Kits were built to enable even faster integration of our social and chat features. In January this year, we open sourced all our UI Kits to provide our customers with more flexibility and greater customization options. Since then, we have seen a shift towards the open source version as it gives complete control over the visual style while keeping the integration time as short as possible.
To ensure that you continue to receive the latest updates and improvements, we encourage you to migrate over to the open source version. We’ve written instruction guides to help you migrate to the open source version, get the latest updates, and contribute to the project all available below.
Once the managed version is deprecated, we will transition our support to the open source UI Kit for any bug requests and releases of new features. You will still be able to use the managed UI Kit, however it will no longer be receiving further updates. All documentation relating to the managed UI Kit version will be moved to the deprecation notice section. Any ongoing improvements will be made to the open source version under the Lesser General Public License (GNU).
Updated: 09 December 2021
From 09 Dec 2021 onwards, Amity iOS SDK will no longer maintain versions which were built with Xcode version prior to 13. and SDK v5.8 will be the first version that is built with Xcode 13 and the iOS 15 SDK.
What drove the change?
When is the deadline I need to make the change?
From now to April 2022, you will be able to submit an app to App Store with Amity iOS SDK version prior to v5.8. but it’s highly recommended to plan the upgrade.
From April 2022 onwards, you will NOT be able to submit an app to App Store with Amity iOS SDK version prior to v5.8
What’s the impact to my users who are currently using the app with Amity iOS SDK version prior to v5.8?
There is no impact from the functionality wise for the users who are using your App under old Amity iOS SDK. However beginning form April 2022, developers can only submit an app to App Store with the following requirement.
Built with Xcode 13
Built with iOS 15 SDK
Built with Amity iOS SDK v5.8
Updated: 27 April 2021
We will only maintain these older versions for critical issues and bug fixes. Whenever a hot-fix is made available, it will be rerouted back to historical ASC SDK & UIKit, respectively, regardless of the current latest versioning.
Amity Social Cloud's SDK 5.0 and UIKit 2.0 will be introduced as a modularized category of changes and advancement. New features will only be added to these versions and those to come, above i.e. v5.1, v5.2 and so on and so forth.
EkoSDK 4.8 and UIKit 1.12 will be supported for critical issues for a period of 6 months. After which the window period will expire and EkoSDK 4.8 and UIKit 1.12 will be officially discontinued and no longer supported moving forward.
You can find more information about these changes in the respective changes for each platform, which you can access using the links below.
Updated: 26 April 2021
After the launch of our Amity Social features that allow customers around the world to build their own social network and grow their own community of users within the safety net of their own brands, our customers and the community they have built has grown much quicker than we originally anticipated - from building a community of travelers to engaging sports-fans around the world.
In order to handle the massive spike in workloads from the growing number of customers while making sure our system always perform at the highest standard from both data latency and scalability aspects, we have decided to revert Follow and Unfollow features into Limited Availability release.
The feature will be temporarily unavailable to all new customers while we work on upgrading our infrastructure and underlying deployment architecture. Starting from 26 April 2021, new SDK downloads will no longer contain follow/unfollow function and newly-generated API key will not be able to use the features. User profile, groups and feed features will remain unaffected. Existing customers who are already using the feature should also remain unaffected.
Our priority is to ensure we scale our system architecture to meet the increasing demand from our existing customers who are using the system to actively grow their community. Our engineering team is working to bring these features back to General Availability release by June 2021. Thank you for your understanding and we apologize for any inconvenience this may have caused to our onboarding customers.
Updated: 08 December 2020
From 1st Feb 2021 onwards, Amity iOS SDK will no longer maintain versions which were built with Xcode version prior to 12, and v4.2 will be the first version with Xcode 12 support. Please kindly plan ahead and upgrade your iOS SDK version if you are using the versions prior to v4.2
What drove the change?
When is the deadline I need to make the change?
From now to 31st Jan, no impact but it’s highly recommended to plan the upgrade.
From 1st Feb onwards, Amity will no longer provide customer support regarding iOS SDK versions prior to v4.2
From 1st Feb to 31st Mar, you will still be able to submit an updated version to App Store with Amity iOS SDK version prior to v4.2
From April onwards, you will NOT be able to submit an updated version to App Store with Amity iOS SDK version prior to v4.2
What’s the impact to my users who are currently using the app with Amity iOS SDK version prior to v4.2?
There is no impact from the functionality wise for the users who are using your App under old Amity iOS SDK, but they will NOT be able to get any further updated version from App Store unless you submit a new version which is :
Built with Xcode 12
Built with iOS 14 SDK
Built with Amity iOS SDK v4.2
I want to upgrade Amity SDK but how do I know the changes between my current SDK version and the latest version?
According to Apple’s announcement , "Starting April 2022, all iOS and iPadOS apps submitted to the App Store must be built with Xcode 13 and the iOS 15 SDK."
and UIKit 1.12 will be the last version to contain the prefix Eko. New features WILL NOT be added to these older versions any longer.
According to Apple’s announcement , "Starting April 2021, all iOS and iPadOS apps submitted to the App Store must be built with Xcode 12 and the iOS 14 SDK."
Please refer to this section for details.
This section outlines how you can set-up your ASC project and contains all the tutorial links you'll need to get going .
SDK Installation
For instructions on installing the Amity Social Cloud SDK, refer to the installation guide for your platform.
We are constantly working to improve our existing SDKs. For this reason, the minimum compatibility for our previous versions may vary. Below is the compatibility list for our latest SDKversions. For a complete overview of the compatibility of a specific SDK version, please refer to the corresponding Changelogs.
Xcode Version: 14.3
Realm Version: 10.28.3
Minimum Target: iOS 13.0
OKHTTP3 - 4.9.0
Retrofit - 2.50
Android Paging Data Library - 3.0.1
Room - 2.4.0-alpha04
RxJava2 - 2.3.10
Gson - 2.8.10
Kotlin-std-lib - 1.5.10
HiveMQ mqtt client - 1.2.2
androidx.annotation:annotation: 1.2.0
androidx.core:core-ktx: 1.3.2
androidx.paging:paging-runtime: 3.0.1
androidx.paging:paging-rxjava2: 3.0.1
androidx.lifecycle:lifecycle-livedata: 2.2.0
androidx.lifecycle:lifecycle-reactivestreams:2.1.0-rc01
androidx.multidex:multidex:2.0.1
androidx.room:room-runtime:2.3.0
androidx.room:room-rxjava2:2.3.0
com.f2prateek.rx.preferences2:rx-preferences:2.0.1
com.github.davidmoten:rxjava2-extras:0.1.24
com.google.code.gson:gson: 2.8.7
com.google.guava:guava:30.1.1-android
com.jakewharton.rxrelay2:rxrelay:2.0.0
com.jakewharton.rx2:replaying-share:2.0.1
com.jakewharton.timber:timber:4.7.1
com.squareup.okhttp3:okhttp: 4.9.0
com.squareup.okhttp3:logging-interceptor:3.10.0
com.squareup.retrofit2:retrofit: 2.5.0
com.squareup.retrofit2:adapter-rxjava2: 2.5.0
com.squareup.retrofit2:converter-gson: 2.5.0
io.arrow-kt:arrow-core:0.11.0
io.arrow-kt:arrow-syntax:0.11.0
io.reactivex.rxjava2:rxandroid: 2.1.1
io.reactivex.rxjava2:rxjava: 2.2.19
io.socket:socket.io-client:1.0.0
joda-time:joda-time:2.10.6
org.apache.commons:commons-lang3:3.7
org.jetbrains.kotlin:kotlin-stdlib: 1.5.10
org.jetbrains.kotlin:kotlin-android-extensions-runtime: 1.5.10
org.jetbrains.kotlinx:kotlinx-coroutines-android:1.4.3
Chrome: 38+
Firefox: 42+
Microsoft Edge: 13+
Safari: 9+
Opera: 25+
Amity JS SDK probably won't work great in Internet Explorer 11. We generally support the recent versions of major browsers listed above.
Since Amity Js SDK uses local cache for performance and user experience reason, server side rendering is not supported. To use Amity Js SDK with NextJS, it must be imported using Dynamic Import with SSR disabled.
Chrome: 38+
Firefox: 42+
Microsoft Edge: 13+
Safari: 9+
Opera: 25+
Amity Ts SDK probably won't work great in Internet Explorer 11. We generally support the recent versions of major browsers listed above.
Since Amity Ts SDK uses local cache for performance and user experience reason, server side rendering is not supported. To use Amity Ts SDK with NextJS, it must be imported using Dynamic Import with SSR disabled.
The minimum deployment target is:
iOS: iOS 9.0
Android: Android 4.4 (API Level 19)
Use our TypeScript SDK natively to support your applications built using the React Native framework.
The instructions for setting up your project will vary slightly, depending on your development environment. Refer this link to set up your project if you have not already done so.
Before you can use the ASC SDK you just installed, we'll first need to create a new SDK instance with your API key. Please find your account API key in the Amity Social Cloud Console or visit our Amity Social Cloud Console page.
After logging into Console:
Click Settings to expand the menu.
Select Security.
In the Security page, you can find the API key in the Keys section.
If you have trouble finding this, you can post in our community forum at community.amity.co so our support team can assist you.
By default, AmityClient
will connect to AmityRegion.SG.
You can specify endpoints manually via AmityEndpoint
struct. API endpoints for each data center are different so you need to adjust the endpoint accordingly.
Note: From Js SDK v5.10.0, we introduced Real time events which requires a new endpoint (mqttEndpoint)
along with the existing apiEndpoint
. So instead of passing multiple parameters for both, we can pass a single apiRegion
parameter. The corresponding endpoints will then be created within the SDK using the passed region. This will be the recommended approach to create a new ASClient for different regions.
We currently support multi-data center capabilities for the following regions:
The SDK does not employ database encryption by default. The database file is solely restricted to the application by the operating system, which is generally sufficient for most use cases. Database encryption serves as an additional layer of security in the event of compromised root access. It's important to note that enabling database encryption may lead to a performance reduction of up to 15% during database read/write operations.
Please note that we only support database encryption for Android SDK 5.35.0 and v6, beginning from version 6.16.0 onwards.
Database Encryption Modes:
The SDK offers three encryption modes:
NONE: No encryption is applied.
AUTH: Access token storage is encrypted.
ALL: All database files are encrypted.
AUTH mode is recommended to introduce extra security with minimal performance compromise. Ultimately, the chosen encryption mode should align with your application's specific requirements.
Encryption key:
Enabling database encryption necessitates an encryption key. It is imperative to consistently pass the same key to the SDK. Should a new key be supplied, the existing database file will be erased and subsequently regenerated, encrypted with the new key.
The level of security offered by encryption hinges on the method of key generation and storage employed by the application. It is strongly recommended to adhere to industry standards for both key storage and generation.
In order to use any ASC SDK feature, you must first log in the current device with a userId
. A logged in device will be tied to the userId
until the device is either proactively logged out, or until the device has been inactive for over 90 days. A logged in 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).
An authToken
is also highly recommended to always be provided, which will be used for a secure authentication. For more info on how to configure secure settings and obtain authToken
, refer to our Security page.
A sessionHandler
is required for SDK to communicate with the app. For more info please refer to Session Handler. Do note that the sessionHandler
is not yet available for Flutter SDK.
It is important to maintain the security of your network and user information. In production environment, we strongly recommend using an authToken for authentication. While the option to not use an authToken may be available, it should only be applied during the development phase and with caution.
The
displayName
is set only on the first time the device is logged in. Please follow your platform's necessary directions if you would like to rename this to something else.
When the user logs out, you should explicitly log out the user from the SDK as well. This prevents the current device from receiving unnecessary and/or restricted data.
Logout is a synchronous operation. Once the logout method is called, the SDK disconnects from the server and wipes out user session.
Logging out is a synchronous operation. Once the logout()
function is called, the SDK disconnects from the server and wipes out user session.
After the SDK is logged in with a user, SDK will maintain the connection as long as it can. However the SDK connection can be terminated due to many reasons, for example:
The device lost Internet connection.
Users close the app into the background, then the operating system pauses the app, and terminates all network connections.
By default the SDK automatically reconnects itself whenever the app has a chance to get back online.
There are some use-cases that developers need more control over the SDK connection. The SDK provides disconnect()
. This method allows developers to explicitly disconnect the SDK while maintaining the current user session so that the app can later resume the connection with the same user.
The functionality isn't currently supported by this SDK.
When developers call disconnect()
:
The SDK will terminate server connections without logging out the current user.
The SDK will not automatically reconnect until the next login.
To resume the connection, the developers should call login(...)
with the current user.
Each user can be logged in, at the same time, to an unlimited number of devices. Amity's Chat SDK will automatically synchronize the user data across all logged in devices. We will also automatically log out any device that has not been connected to the server for more than 90 days.
When a device is logged out due to inactivity, the SDK data on the device will be reset. You will need to re-login this device in order to connect to server again.
Now that you've finished getting your ASC project set up, here are some step-by-step articles if you need a hand building your app!
Check out our Amity Social Cloud UI Kits and Template Apps.
UI Kits Our UI Kits include user interfaces to enable fast integration of standard Amity Chat and Amity Social features into new or existing applications.
Template Apps Our Template Apps are ready-made template applications to kickstart your own Amity Social Cloud project.
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.
The Amity Social Cloud SDK for Android is delivered via Jitpack repository.
Android 5.0 (API level 21) and above*
Target sdk version 29 and above*
Compile SDK Version 29 and above*
JVM target should be 1.8
The API level allows a developer to declare the minimum version with which the app is compatible, using the minSdkVersion
attribute. If your app can't function without these APIs, declare API level 21 and above as the app's minimum supported version. And using targetSdkVersion
29 and above.
Add the Jitpack repository in your project level build.gradle
at the end of repositories:
If your minSDKVersion is below 24, ie., 23 or 21, there are additional configurations required.
In your project build.gradle
,
In your app module's build.gradle
, add the following packaging options.
By using our SDK, you can use the Android ProGuard tool to obfuscate, shrink, and optimize your code. Obfuscated code can be more difficult for other people to reverse engineer. ProGuard renames classes, fields, and methods with semantically obscure names and removes unused code. However, you need to add these configurations to your ProGuard rules when using our SDK.
For users who are using the SDK version below 5.33.11
and 6.9.0
. If you'd like to pass an Amity Serializable Object such as AmityPost
, AmityMessage
, etc. You will need to add an additional ProGuard rules below:
For debugging purposes, we provide the ability to show or hide logs from our SDK. In the 'build.gradle' application, you can set the boolean value resValue
"IS HIDDEN AMITY LOG" to true
to hide the logs and to false
to make them visible.
In the 'build.gradle' application, you can also customize the log display depending on the build variant, as in this example.
The Amity Social Cloud SDK for iOS is delivered as a binary .xcframework file
Drag AmitySDK.xcframework
, Realm.xcframework
& RealmSwift.xcframework
to your project.
Make sure that Copy items if needed
is selected and click Finish.
Also switch the Embed section as Embed & Sign
The correct setup should look like this.
AmitySDK
supports installation via dependency managers.
SwiftPM
Cocoapods
Carthage
To integrate AmitySDK into your project via SwiftPM, please follow the instruction below.
Enter the repository URL to search the package, and choose to install AmitySDK
.
If you selected "Up to Next Major Version
" option for the Dependency Rule, you need to manually add the version.
To integrate the Amity Social Cloud SDK into your Xcode project using CocoaPods, specify the following lines of code in your Podfile
:
AmitySDK already includes our UIKit. Don’t install the UIKit separately if you have already installed the SDK.
To use live video broadcast:
Import AmityLiveVideoBroadcastKit.xcframework
to your project.
To use live video player:
Import AmityVideoPlayerKit.xcframework
to your project
Switch each framework to Embed & Sign
, except MobileVLCKit
to Do Not Embed
.
To install Swift Packages for Amity Video, please follow the instructions below.
Import AmityVideoPlayerKit.xcframework
to your project
Switch each framework to Embed & Sign
, all xcframeworks.
To install Swift Packages for Amity Video, please follow the instructions below.
To use live video broadcast functionalities. Enter the repository URL to search the package, and choose to install AmityVideoBroadcast
.
Try it in your code
To use live video player functionalities. Enter the repository URL to search the package, and choose to install AmityVideoPlayer
.
Try it in your code
If you selected "Up to Next Major Version
" option for the Dependency Rule, you need to manually add the version.
Starting with v6.0.0, AmitySDK for iOS is written in Pure Swift. Although its in pure Swift, you can still use it in Objective-C projects by making Mixed-Language Project.
We recommend you to integrate AmitySDK
for iOS swift directly into your Objective-C project and use Swift language to call the SDK interfaces.
The Amity Social Cloud SDK for JavaScript is delivered as an npm module.
Add the SDK to your repository via npm: npm install @amityco/js-sdk --save
.
Chrome: 38+
Firefox: 42+
Microsoft Edge: 13+
Safari: 9+
Opera: 25+
Amity Web SDK probably won't work great in Internet Explorer 11. We generally support the recent versions of major browsers listed above.
AmitySDK already includes our UIKit. Don’t install the UIKit separately if you have already installed the SDK.
Add the dependency in your module level build.gradle.
Find latest SDK version at .
You need to turn Rosetta mode on when using AmitySDK
with arm64 simulator. To force the application to use Apple Rosetta environment with an Apple silicon Mac, refer to for the instructions.
is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate the Amity Social Cloud SDK, add the following line of code to your Cartfile
.
This installs the latest version of SDK. To get more info about our latest release, please look into section. We support cocoapod installation of our sdk above version 5.1.0. The minimum deployment target platform for iOS is 12.0.
If there are any issues during installation steps, clean cocoapods cache and try again. To clear cache please go to ~/Library/Caches/Cocoapods
and remove `AmitySDK` related folders/files.
If this doesn't work, please do visit the Cocoapods repo for further resolutions.
Amity Video requires the AmitySDK
as dependencies. First, ensure you have installed the AmitySDK
as per the instructions .
Download , and import to your project.
Download , and import to your project.
To make a mixed language project, create Swift files with necessary interfaces/methods which in turn interacts with AmitySDK
. These interfaces should be exposed with @objc
or @objcMembers
attributes. Reference:
When you add new Swift file into your Objective-C project, Xcode automatically generates a bridging header file. This bridging header exposes your Swift code to Objective C code. For more information you can refer to this guide by Apple:
Installing the SDK requires you to use a javascript package manager such as npm
or yarn
. If your current build system does not use package managers, please contact us at .
If you already installed our SDK with the name eko-sdk
, be sure to check our .
Since Amity Web SDK uses local cache for performance and user experience reason, server side rendering is not supported. To use Amity Web SDK with NextJS, Amity Web SDK must be imported using .
Region
Endpoint
Europe
AmityRegion.EU
Singapore
AmityRegion.SG
United States
AmityRegion.US
The Amity Social Cloud SDK for Flutter is available on PubDev
Add the SDK to your repository by adding amity_sdk
depedency
With Flutter:
This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get
) :
Alternatively, your editor might support flutter pub get
. Check the docs for your editor to learn more.
The minimum deployment target is:
iOS: iOS 9.0
Android: Android 4.4 (API Level 19)
The Amity Social Cloud SDK for TypeScript is delivered as an npm module.
Add the SDK to your repository with this code:
npm:
yarn:
The very first thing to do once you have installed the SDK, is to creating an instance of the client and logging in.
Once the client has been instantiated and you are logged in. You can now use API's to create a channel, message, community and posts!
Chrome: 38+
Firefox: 42+
Microsoft Edge: 13+
Safari: 9+
Opera: 25+
Amity Web SDK probably won't work great in Internet Explorer 11. We generally support the recent versions of major browsers listed above.
Since Amity Web SDK uses local cache for performance and user experience reasons, server side rendering is not supported. To use Amity Web SDK with NextJS, Amity Web SDK must be imported using Dynamic Import with SSR disabled.
Use our TypeScript SDK natively to support your applications built using the React Native framework.
In order to support older JavaScript runtime, you need to include a global polyfill for your bundled package.
First, install core-js
in your project.
Then, import fromEntries
in the root of your project.
You can check out our React Native sample application here.
Use our Amity Social Cloud SDK with the Ionic Framework
We now support the Ionic framework in building your application using our web SDK. You can use our Chat natively to support your mobile or web applications built using the Ionic framework.
Since Ionic is an HTML5 framework, it needs a native wrapper to access native SDK functionalities and run as a native app. We recommend using Capacitor.
Capacitor will wrap your application in a native container so you can easily integrate our web SDK to run on iOS, Android, and web platforms.
We will walk you through the process of installing ionic and all the necessary dependencies for development.
Ionic comes with a convenient command line utility to start, build, and package Ionic apps. To install it, simply run:
In the root of your application, install Capacitor:
Now, we need to copy the native platform template into your application:
To open the application in your IDE, run:
For Android, it will open Android Studio. For iOS, it will open Xcode.
Now you’re ready to start integrating our chat SDK into your application.
Ionic with JavaScript framework
Session state is a key concept in the SDK that describes the authentication status of the client device. There are several session states that the SDK can be in, including:
notLoggedIn
establishing
established
tokenExpired
terminated
The established
state is the normal and fully authenticated state in which the SDK is usable. The other states represent different stages of the authentication process or an error condition.
When SDK is initialized:
If the user is not logged in, the SDK starts in the initial "notLoggedIn
" state.
If the user is already logged in, the SDK automatically resumes the logged-in session and immediately switches to the established
state.
When TS SDK is initialized, the session state always begins as notLoggedIn
.
When logging in:
If login succeeds, it moves to established
state.
If login fails, it moves to notLoggedIn
state.
When logging out manually:
It moves to notLoggedIn
state.
When the user is logged in, but the user is banned or deleted from the system.
It moves to terminated
state.
The error code will be presented in terminated
state. Please refer to Error Handling for more details.
When token has expired:
It moves to tokenExpired
state.
If the access token has expired, all network requests will fail. However, the SDK includes an automatic process for renewing the access token. As long as this process is implemented correctly, it is unlikely that the app will encounter this problem. Please refer to #session-handler for more details.
The SDK provides APIs for reading and observing the session state.
Session state is designed to align with the typical flow of an app. For example, developers can use the session state to guide app navigation, like this:
For logging, the SDK requires SessionHandler
. SDK uses this object to communicate with the app when session handling is required. Currently, SessionHandler
is used for:
Initiate access token renewal when it is about to expire or has expired.
The code above shows a simple session handler. Please note that each function in SessionHandler
can be customized to your app logic.
When a user logs in to the SDK for the first time, an access token is issued that is valid for 30 days.
If the access token is about to expire or has already expired, the SDK automatically initiates the renewal process through the sessionWillRenewAccessToken
method of the SessionHandler
.
During the renewal process, the SDK passes an AccessTokenRenewal
object to the app. The app must call either one of the following methods on this object to complete the process.
The following code shows how the app can implement the sessionWillRenewAccessToken
method by providing an auth token for renewal.
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 over time.
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 list 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 UserRepository
class, you will be able to list all the users, search for list of users whose display name matches your search query and get AmityUser
object from user ID.
You can ban a user globally. When users are globally banned, they can no longer access Amity's network and will be forcibly removed from all their existing channels.
Method on renewal object | |
---|---|
Refer documentation for instructions on how to globally ban a user.
For more information please visit to
platform
The platform template to add (e.g. android
, ios
).
platform
The platform you are using (e.g. android
, ios
).
renew()
Indicates the SDK to renew the access token without an auth token.
renewWithAuthToken(...)
Indicates the SDK to renew the access token with an auth token. (Required for secure login)
unableToRetrieveAuthToken()
Indicates the SDK to postpone renewal.
SDK will re-initiate access token renewal at a later time, but no sooner than 10 minutes.
Name | Data Type | Description | Attributes |
|
| The id of this user |
|
| A list of user's roles |
|
| The display name of the user |
|
| The number of users that have flagged this user |
|
| The metadata of the user |
|
| A hash for checking internally if this user was flagged by the user |
|
| The date/time the user was created at |
|
| The date/time the user was updated at |
|
| Flag that indicates if the user is globally banned. Note: This is not yet supported for Typescript |
|
| Custom Url provided for this user avatar |
|
| Flag that indicates if the user is deleted |
In Amity SDK, creating a new user can be done through the login method. Once the user account has been created, the user can then log into the app using their userId
and displayName
using the SDK's social and chat features.
You may need to create a new user account via the SDK, such as when integrating the SDK with an existing user authentication system. In these cases, you can use the login
method. Here's how the login
method works:
If a user already exists for the specified userId
, the SDK will log the user into the app using the provided userId
. The displayName
parameter can be updated upon calling the login
method. If the displayName
parameter is not provided, the system will retain the existing user's displayName
.
If a user account does not already exist for the specified userId
, the SDK will automatically create a new user account with the provided displayName
and log the user into the app. If displayName
is not provided, the userId
will be used as displayName
.
Note:
When user edits / adds their display name, it can be up to 100 characters in length.
When a user ID is created, it can be up to 50 characters in length.
If displayName
is passed, but secured mode is enabled, the values will be ignored.
Version 6 and Beta(v0.0.1)
Query for users by their display name, receiving a collection of AmityUser
matching your search. It requires two parameters: the display name you're searching for, and a 'sort option' from the AmityUserSortOption
enum. If no keyword is supplied, the list of users will be organized alphabetically by display name.
Users also have the option to sort by lastCreated
, firstCreated
, or displayName
. When a keyword is provided, the list will be arranged based on search rank. The displayName
sort option will be specified by default if it isn't specified.
If the collection is sorted by displayName
, the results will be alphabetically and case-sensitively ordered (aA-zZ). For example: adam, arthur, Alice, Andre, charlie, Kristen.
Note: If the user ID or display name you’re searching for contains special characters, you’ll need to enter the whole keyword in order for it to appear in the search results.
The code above will provide you with the list of users which matches with display name "Brian".
The above example searches for all users whose display names start with "Test User 1".
The queryUsers
provides a way to search for users by their display name.
Query for users to receive a collection of AmityUser
based on a single parameter: a 'sort option' from the AmityUserSortOption
enum. Sort the list by options such as displayName
, firstCreated
, or lastCreated
. The displayName
sort option will be specified by default if it isn't specified.
If you wish to observe for changes to a collection of users, you can use liveUsers
In the Amity SDK, a user is represented by an AmityUser
object, which contains the user's unique userId
and displayName
. The userId
is an immutable value that is assigned to a user when their account is created, and cannot be changed afterwards. This value serves as a unique identifier for the user within the SDK, and is used to perform actions such as sending messages or creating connections between users.
To retrieve an AmityUser
object for a specific userId
, you can use the getUser
method provided by the UserRepository
. This method accepts the userId
as a parameter and returns a Live Object of AmityUser
. The live object allows developers to observe changes to the user's properties in real-time, ensuring that their app remains up-to-date with the latest user information.
Follow the below code to retrieve a user object:
The User Repository provides a method to get a single user. It returns a LiveObject which you can observe.
You can also use the code below to get one user:
The User Repository provides a method to get a list of all users, which will be returned as a LiveCollection:
This method takes an optional sortBy
parameter which must be a UserSortingMethod
- these include displayName
, firstCreated
, and lastCreated
:
The functionality isn't currently supported by this SDK.
To retrieve multiple users, you can use getUserByIds
method provided by UserRepository
. This method accepts a collection of userId
as a parameter and returns a Live Collection ofAmityUser
.
The functionality isn't currently supported by this SDK.
The functionality isn't currently supported by this SDK.
The functionality isn't currently supported by this SDK.
Update current user information, including display name, avatar, user description, metadata, etc., using the updateUser
method in the 'amityClient' class. This method updateUser
accepts these optional parameters:
The method accepts the following optional parameters:
displayName
- user's display name
description
- user's description
avatarFile
- file ID of the user's avatar
avatarCustomUrl
- custom url of the user's avatar
roles
- user's role
metadata
- user's metadata
The updateCurrentUser
method accepts the following optional parameters:
displayName
- user's display name
description
- user's description
avatarFile
- file ID of the user's avatar
avatarCustomUrl
- custom url of the user's avatar
roles
- user's role
metadata
- user's metadata
Below is a sample code on how to update the current user's display name, description, and metadata. This method returns a promise. If the update is successful, the method will return true,
else it throws an error.
You can upload an image and set it as an avatar for the current user.
First, you need to upload image using AmityFileRepository
and then update the image info.
Step 1 — Upload an image:
Step 2 — Passing AmityImageData
from step 1 into the builder, and call user update API.
If you have an avatar present in your current system/server and just want to integrate that existing avatar to AmitySDK, you can just set the URL for the avatar directly.
Note: getAvatarInfo
provides the information associated with a particular Avatar
First, you need to upload image and then update the image info. If you have an avatar present in your current system/server and just want to integrate that existing avatar to AmitySDK, you can just set the URL for the avatar directly.
If you have an avatar present in your current system/server and just want to integrate that existing avatar to AmitySDK, you can just set the URL for the avatar directly.
Either you wish to let us handle your user's avatar, or if you already have a system for it we got you covered. The 2 properties avatarFileId
and avatarCustomUrl
answer those two use-cases separately.
You can easily retrieve the url of a file from our FileRepository object and use it to display in your app later on. Here's an example in React:
You can easily retrieve the url of a file using observeFile
and use it to display in your app later on. Here's an example in React:
AmityClient
class provides a method hasPermission
which allows you to check if the current logged in user has permission to do stuff in given channel.
We determine a user's moderation capabilities based on their current role. Amity SDK has the following default roles:
Member - has no moderation privileges
Community/Channel Moderator - can assert general moderation privileges on other users
Super Moderator - can assert general moderation privileges and be exempt from moderation from other users
Global Admin (Admin Only) - can assign the roles of others, assert all moderation privileges and be exempt from moderation
The Global Admin role cannot be assigned to a user.
*UserV3
*ChannelV3
*CommunityV3
Each role can be assigned with many permissions. Below is a list of all the possible permissions that can be assigned to a user.
A user's role can be changed via Console. Refer to for the instructions on how to change a user's role.
Below are tables for each category that show the default roles and permissions. You can create new roles and assign a specific set of permissions for each role in the ASC Console. Refer to .
Permission | Global Admin | Super Moderator | Community Moderator | Channel Moderator |
---|
Permission | Global Admin | Super Moderator | Community Moderator | Channel Moderator |
---|
Permission | Global Admin | Super Moderator | Community Moderator | Channel Moderator |
---|
There is no limit to the number of moderators in a community. If there are 100 members in the community, all 100 members can be promoted to moderator. Promoting a user to a community-level moderator can be done using the or through the SDK.
Permission | Global Admin | Super Moderator | Community Moderator | Channel Moderator |
---|
ASC Console Access | ✅ | ✅ | ❌ | ❌ |
Create, Edit, & Delete, Roles | ✅ | ✅ | ✅ | ✅ |
Ban & Edit User* | ✅ | ❌ | ❌ | ❌ |
Exempt from filters | ✅ | ✅ | ❌ | ❌ |
Exempt from rate limits | ✅ | ✅ | ❌ | ❌ |
Exempt from mute | ✅ | ✅ | ❌ | ❌ |
Exempt from ban | ✅ | ✅ | ❌ | ❌ |
Exempt from blacklist & whitelist | ✅ | ✅ | ❌ | ❌ |
Exempt from repitition check | ✅ | ✅ | ❌ | ❌ |
Edit, Ban, Add, Remove, & Mute Channel User * | ✅ | ✅ | ❌ | ✅ |
Edit & Mute Channel* | ✅ | ✅ | ❌ | ✅ |
Edit & Delete Message* | ✅ | ✅ | ❌ | ✅ |
Edit Channel Rate Limit* | ✅ | ❌ | ❌ | ❌ |
Ban, Mute, Rate limit, & Manage Users | ✅ | ✅ | ❌ | ✅ |
Mute Channels | ✅ | ✅ | ❌ | ✅ |
Rate Limit Channels | ✅ | ✅ | ❌ | ✅ |
Manage Messages | ✅ | ✅ | ❌ | ✅ |
Global Access | ✅ | ✅ | ❌ | ❌ |
Create, delete, Edit Community Categories | ✅ | ✅ | ✅ | ❌ |
Edit & Delete Communities* | ✅ | ✅ | ✅ | ❌ |
Edit, Add, Ban, & Remove Community Users* | ✅ | ✅ | ✅ | ❌ |
Edit, Delete, & Review Community Posts* | ✅ | ✅ | ✅ | ❌ |
Edit & Delete Community Comments* | ✅ | ✅ | ✅ | ❌ |
Manage Community | ✅ | ✅ | ✅ | ❌ |
Manage Community Stories | ✅ | ✅ | ✅ | ❌ |
Edit & Delete User Feed Post | ✅ | ✅ | ✅ | ❌ |
Edit & Delete User Feed Comment | ✅ | ✅ | ✅ | ❌ |
Manage Posts & Comments | ✅ | ✅ | ✅ | ❌ |
Manage Network Settings | ✅ | ✅ | ✅ | ✅ |
Source | Permission | Description |
Channel |
| Can mute/unmute channel |
| Can close channel |
| Can edit channel |
| Can set rate limit of channel |
| Can edit all messages |
| Can delete all messages |
| Can ban/unban user from channel |
| Can mute/unmute user in channel |
| Can add users to channel |
| Can add remove user from channel |
| Can edit users in channel |
User |
| Can global ban/unban user |
| Can edit users |
| Can assign role to users |
User feed |
| Can edit all posts on user feed |
| Can delete all posts in user feed |
| Can edit all comments on user feed |
| Can delete all comments in user feed |
Community |
| Can add users to community |
| Can remove users from community |
| Can edit users in community |
| Can ban users in community |
| Can mute users in community |
| Can edit community |
| Can delete community |
| Can edit all posts in community feed |
| Can delete all posts in community feed |
| Can edit all comments in community feed |
| Can delete all comments in community feed |
| Can review community post |
| Can create and delete community story |
Community Category |
| Can create new community categories |
| Can edit community categories |
| Can delete community categories |
Network |
| Can create new roles |
| Can edit roles |
| Can delete roles |
Notification |
| Can manage notification settings |
Delete User API is called to delete a user from the system. The display name of the deleted user is replaced with “Deleted User”. This API can be called only by admin users.
Please note that this action is a hard delete, and all deleted data will be lost and cannot be recovered.
When deleting a user, you can specify that the user should be marked as deleted but the user’s data should remain unchanged, or you can specify that all personal data associated with the user should be deleted:
if the deleteAll
parameter is set to true, all personal data (i.e. profile, photos, images, and files), message channels, posts and comments of the user will be deleted.
the markMessageDeleted
parameter, when set to true, deletes all message channels and messages that the user has created
the hardDeletePost
parameter, if set to true, deletes all posts created by the user as well as the comments, reactions, child posts and child comments of the corresponding post
the hardDeleteComment
parameter, if set to true, deletes all comments and reactions of the user
Once a user has been deleted from the system, the account cannot be reactivated under any circumstances. In order to protect the user account data, no other user will be allowed to reactivate the account after it has been deleted by the user.
The user's system ID will still be stored in the database, but to protect the user's identity, the account's username will be replaced with the text "Deleted User". All deleted accounts will be marked as "Deleted Account".
If the user account is deleted, all conversation channels created by that user will be deleted immediately and no other user will be able to access those channels afterwards.
After the account is deleted, all messages for all channels and all attachments that created by the user are deleted and cannot be restored.
When a user is deleted, the channel members are updated in all channels where the user was a member, so that only active users are counted in the channels.
All the user's data, including profile, photos, videos, images, text, audio, video, attachments, files and anything else that the user has added to the system as a user will be permanently deleted from the system and cannot be recovered.
All posts created/shared by the deleted user will be deleted and all comments added by the deleted user will also be removed from all posts. No comments or sub-posts will be available after the user deletes the account.
All reactions and comments posted by the deleted user are detected and updated in the posts.
The status of the user's account is marked as "deleted" when queried and the user can no longer access it.
API response will be different based on the request and records match. The request may have successful response , or it may have bad request error, and it may respond as User not found. As the responses of API call are mentioned below.
{
"success":true
}
{ "status": "error",
"code": 400000,
"message": "User is already deleted"
}
{ "status": "error",
"code": 400400,
"message": "User Not Found."
}
API token management is a login authentication process that allows an amity user to access amity applications in a unified and streamlined environment.
Amity SDK provides AmityUserTokenManager to manage user credentials. This includes an access token that can be used to access some Beta features.
NOTE: Please be aware that we do not provide any API to support the usage of user tokens on the client SDK. To use this user token, you must interact with ASC services with your own effort.
To create a new user token, refer to the following example and the parameters are.
userId
: This is a required parameter of type String
that represents the unique identifier of the user whose credentials are being managed by the AmityUserTokenManager
.
displayName
: This is an optional parameter of type String
that represents the display name of the user. If provided, it will be associated with the user's credentials.
authToken
: This is an optional parameter of type String
that represents the user's authentication token. If provided, it will be used to authenticate the user when accessing the Amity application. For further information about security please visit the security page.
Version 6 and Beta(v0.0.1)
Flag / Unflag User feature is an essential tool for maintaining a safe and engaging chat community. With Amity Social Cloud, you can use the flag and unflag user feature to allow moderators and administrators to monitor any inappropriate behavior within a chat channel.
In this section, we will discuss how to use the flag and unflag user feature of Amity Chat SDK to maintain a safe and engaging chat community.
To flag / unflag users on iOS, Android and Flutter SDK, create an instance of UserFlagger
first:
The UserFlagger
lets you flag and unflag a user. It also exposes an asynchronous way to check whether the current logged-in user has already flagged the given user or not.
To flag a user, call the following method:
To unflag a user, call the following method:
To check whether a user has been flagged by the current user:
The use of images as a visual representation of information is crucial in many software applications. Our SDK provides the tools and functionality needed to easily handle images. In this section, we will introduce you to image handling in Amity, including how to upload and retrieve images in the SDK.
To upload an image to the system, you can use the Amity Image Upload API provided by the SDK. The API allows you to upload an image to the Amity server/ The SDK simplifies the process of uploading images by providing pre-built components that you can easily integrate into your application.
Supported ✅ (please wait while we prepare a real example!)
Supported image formats are JPG, PNG and cannot exceed 1GB in size.
You can retrieve an image from Amity using the Amity Image Retrieval API provided by the SDK. The API enables you to retrieve an image from the Amity server by supplying the image URL. Once an image is uploaded to the server, the image will be automatically transformed into four different sizes for versatile usage. We provided an option to retrieve a specific image size which are:
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 number 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.
Supported ✅ (please wait while we prepare a real example!)
Supported ✅ (please wait while we prepare a real example!)
File upload and download are key features of our product, which enable developers to easily incorporate file-sharing functionality into their applications. With support for a wide range of file types, including images, videos, audio, and documents, developers can create highly engaging and interactive user experiences that drive engagement and increase retention. The maximum file size of a file regardless of its type is 1 GB.
By enabling users to share files directly within the chat or social feed, developers can create highly personalized and engaging experiences that foster deeper connections among users. For example, users can share photos and videos with friends and family, or exchange documents and other files within a community. To support various use cases and make it easy to handle files, images, and videos, we offer convenient methods for managing these types of content:
The SDK does not manage the caching of any images or files. It is recommended to effectively handle caching to ensure optimal performance. You can use a pre-existing implementation or library to handle the caching of files or images.
Files are an essential component of modern software applications. Amity provides a powerful file management system that enables you to easily handle different types of files, such as document files, videos, and audio files. In this section, we will introduce you to the concept of a file in Amity and provide an overview of file handling in Amity.
To upload a file to the system, you can use the Amity File Upload API provided by the SDK. The API allows you to upload a file to the Amity server by providing the file's data and the file metadata, such as the file name, file type, and file size. The SDK simplifies the process of uploading files by providing pre-built components that you can easily integrate into your application.
On Android, you can separately observe uploading states outside of the uploading method by using:
Version 6 and Beta(v0.0.1)
You can retrieve a file from Amity using the Amity File Retrieval API provided by the SDK. The API enables you to retrieve a file from the Amity server by supplying the file ID. The SDK streamlines the process of retrieving files by offering pre-made components that can be smoothly integrated into your app.
In addition to uploading and retrieving files, Amity provides a deleting function to delete a file that is no longer needed.
The response will return true
if the file deletion is successful.
Version 6 and Beta(v0.0.1)
The response will return true
if the file deletion is successful.
Otherwise, if an error is encountered during the deletion, it will return the following errors:
Content-type | application/json |
---|---|
Path | Data field |
---|---|
Property | Description |
---|
Property | Description |
---|
Authorization
Bearer{{Admin Token}}
UserID
User public id
| Identifier for the uploaded file |
| The HTTP web URL for the uploaded file. You can use this |
| Contains a dictionary with values for of uploaded image |
| Contains additional metadata dictionary related to uploaded image such as |
| Root file key on cloud storage |
| HTTP link for file download |
| File type |
| Date/time when a file is uploaded |
| Date/time when a file is updated |
| Information about the file |
The video data is the representation of the video that has been uploaded using the SDK. The uploaded video will be transcoded to other different resolutions depending on console settings. Below is a table of properties that it contains.
The fileUrl
and videoUrl.original
provides the URL of the same video resolution.
The difference being, fileUrl
returns the actual file format while videoUrl.original
returns MP4 format.
To upload a video to the system, you can use the Amity Video Upload API provided the SDK. The API allows you to upload a video to the Amity server. The SDK simplifies the process of uploading videos by providing pre-built components that you can easily integrate into your application.
Supported ✅ (please wait while we prepare a real example!)
Version 6 and Beta(v0.0.1)
If an error is encountered while creating the file, it will return the following errors:
Once you uploaded a video the videos undergo transcoding from their original resolution. You can quickly access the original size of the video right after you make the video message. However, it takes time for the transcoded resolutions to be ready. Here are the available transcoded resolutions.
1080p
720p
480p
360p
original
Supported ✅ (please wait while we prepare a real example!)
Here's an example of getting a specific video resolution from a post.
Additionally, you can display a video preview in the user interface by utilizing a video thumbnail image. This allows for a more visually appealing representation of the video and provides a quick preview for users before they choose to view the full video. The thumbnail may not immediately available after the video was uploaded. However, eventually, the thumbnail will be become available.
Supported ✅ (please wait while we prepare a real example!)
Supported ✅ (please wait while we prepare a real example!)
The functionality isn't currently supported by this SDK.
Push notifications are small pop-up messages triggered by an application, even when the application is not open. Push notifications are an essential part of social features that a customer must provide to their end users.
Clients who want to have the push notifications delivered to their own servers first in order to customise before it reaches their users, can opt for this method.
In this solution, events are sent from Amity’s servers to the client’s servers via webhook. Clients can decide what to do with each events before it reaches the end user's device as notification. Clients have the ability to edit the notifications (i.e: translate the message), filter them (based on specific use case or user preferences), and perform analytics before sending them to the users. With this new feature, clients can also have notifications for web apps.
In this scenario, there's no SDK involvement needed. The whole notification process is managed on your end.
With this solution, the notifications will be triggered and delivered to your users directly by Amity's servers. There's nothing that the iOS client has to do in order to display the notification to your users. Amity's servers will prepare for you a notification that can be directly displayed to the user as and when it's received.
Direct push notifications only support on iOS, Android, and Flutter SDKs.
As Amity's servers are responsible for choosing the content of the push notification, 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 other 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 user has joined a channel. Push Notification Title: %s
(%s
= user display name) Push Notification Body: %1s has joined %2s
(%1s
= user display name, %2s
= channel display name)
Event: A new message has been received in a channel where the user is already a member. Push Notification Title: %1s (%2s)
(%1s
= user display name, %2s
= 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.
Process to setup iOS push notification certificates to receive notification from AmitySDK / AmityUIKit.
In order to send or receive push notifications using our SDK, you would need to create push notification certificates from Apple Developer Console & Upload in our Amity console.
Here are the steps to generate push notification certificate from Apple Developer Console.
When a new .p12 certificate is created, previous certificate gets revoked and cannot be used again.
Step 1:
Step 2:
Select Apple Push Notification Service SSL (Sandbox & Production)
This certificate will be applicable for both Sandbox & Production environments so you do not need to create a separate for each one.
Step 3:
Follow the rest of the steps of creating certificates as shown by apple & download the .cer file.
Step 4:
Double click on .cer file you downloaded in the last step in Finder. After few seconds, Keychain Access program should open.
Step 5:
Select Login → My Certificates, then right click on the Apple Push Services certificate that you just installed. It would show you with some options as shown below.
Step 6:
Select Export “Apple Push Services …” option and save the file using .p12 extension. If you add a password while exporting, you will need to enter the same password in Amity Console.
Step 7:
Open Amity Console. Select Settings → Push Notifications & Upload this .p12 file to Amity Console.
This certificate can be used to receive push notification in your production build (Distributed through Appstore or Testflight). Currently we do not support receiving push notification in Debug build.
Please make sure you have Push Notification capabilities enabled in your Xcode Project.
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:
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.
Property | Description |
---|---|
For more information, go to settings.
Click for more .
Click to learn on different SDK .
Go to Apple Developer Console (i.e ) and click on Certificates.
That’s it. Now the certificate is setup, Please follow the steps shown in section to correctly send APNS token to receive push notification.
To retrieve push notifications, use a service that extends FirebaseMessagingService
. Refer to Firebase's documentation for the detailed information.
Note: Baidu push services require number of additional permissions. You can find .
fileId
Identifier for the uploaded file
fileUrl
The HTTP web URL for the uploaded file. You can use this fileUrl
for downloading the original video file. (The file format remains unchanged)
attributes
Contains a dictionary with values for name
, extension
, size
and mimeType
of uploaded video.
attributes.metadata
Contains a dictionary with values for video
and audio
of uploaded video.
attributes.metadata.video
Contains a dictionary with values for width
, height
, duration
, bit_rate
, avg_frame_rate
and display_aspect_ratio
attributes.metadata.audio
Contains a dictionary with values for duration
, bit_rate
and sample_rate
videoUrl
After video uploaded and transcoded by the server. The video data will contain videoUrl
that provides different video URLs for each resolution.
original - the equivalent resolution to fileUrl
1080p - 1920×1080 in horizontal, and 1080x1920 in vertical
720p - 1280×720 horizontal, and 720x1280 in vertical
480p - 640x480 horizontal, and 480x640 in vertical
360p - 480x360 horizontal, and 360x480 in vertical
(All transcoded videos are in MP4 format)
status
An enum represents 4 video statues
uploaded - the video is uploaded and users can watch the original raw file on fileUrl
transcoding - the video is being transcoded to pre-defined resolutions
transcoded - the video is transcoded and the resolutions are provided to videoUrl
error - the video encounters an issue while transcoding
The SDK has three levels of notifications and in order for it to be sent, a notification has to pass throughout all three levels.
Network Level: (via Admin Panel) turning off notifications at this level effectively disable push notifications altogether for all of your customers.
User Level: (via client) A user can choose to enable/disable notifications per feature module. Please note that this setting is per user, not per device: regardless of which device sets this toggle, the new preference will take effect in all the devices where the user is logged in.
Channel or Community Level: (via client) A user can choose to enable/disable notifications per channel or community (where is member of). Again, this preference is per user, not per device.
In addition to push notifications, we also offer a Notification Tray that stores the notification history for each user.
Registering your app for push notification will require a registered AmityClient
instance (necessary to know which user is associated with this device) and a push notification token.
Amity's Development Kit does not manage:
user-facing requests for push notifications and authorizations
the creation and refreshing of push notification tokens
It's up to your app to take those steps and pass the notification token to the SDK.
We recommend observing the completion block outcome to ensure a successful registration.
If the device was previously registered with this or another user, the previous registration is invalidated as soon as this new request is received, which means that the device will always receive notifications of up to one user.
Unlike the registration, unregistering for push does not require the AmityClient
instance to be associated with any user, therefore you can unregister the device from receiving push notifications as soon as the AmityClient
has been initialized with a valid API key.
The unregistration allows 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.
You can register and unregister as many times as you'd like, however please remember that we use the "Last write wins" strategy.
The SDK offers push notification settings per user, allowing users to configure whether to enable or disable push notifications for specific feature modules. This configuration applies universally to every device logged in as the same user.
Configurable modules include CHAT
, SOCIAL
, and LIVE_STREAM.
The SDK provides "getSettings()
" function within User Notification to inspect the current settings of each feature module.
The functionality isn't currently supported by this SDK.
The SDK provides "enable()
" function where user can specify the settings of each module and "disableAll()
" function where user can choose to disable notifications on every module.
The functionality isn't currently supported by this SDK.
The SDK offers push notification settings per channel, allowing users to configure whether to enable or disable push notifications for specific channel. This configuration applies universally to every device logged in as the same user.
The SDK provides "getSettings()
" function within Channel Notification to check whether push notification is enabled on the channel.
The functionality isn't currently supported by this SDK.
The SDK provides "enable()
" and "disable()
" functions where user can choose whether to enable or disable push notifications coming from the channel.
The functionality isn't currently supported by this SDK.
The SDK offers push notification settings per community, allowing users to configure which notification events should be enabled on the community. This configuration applies universally to every device logged in as the same user.
Configurable events include POST_CREATED
, POST_REACTED
, COMMENT_CREATED
, COMMENT_REACTED
, COMMENT_REPLIED
, STORY_CREATED
, STORY_REACTED
, STORY_COMMENT_CREATED
The SDK provides "getSettings()
" function within Community Notification to inspect which notification events are enabled on the community.
The functionality isn't currently supported by this SDK.
The SDK provides "enable()
" function where user can choose which notification events to be enabled on the community and "disable()
" function to disable all notification events on the community.
The functionality isn't currently supported by this SDK.
Mentions allow users to tag other users in messages, comments, and posts. It's a powerful tool for fostering engagement and collaboration within your social application. With mentions, users can easily direct messages to specific individuals or groups and can alert them to new content or important updates. In the SDK, mentions can be implemented in a range of ways, depending on your application's needs and user experience. Here are the models that support mentions creation and highlighting:
you have the flexibility to define your own mention data structure for representing mentions. This allows you to highlight mentioned text in a way that best suits the needs of your application and users. The most important aspect of mentions is to notify users when they have been mentioned, regardless of the specific data structure used. This ensures that users are able to quickly and easily engage with the content that is most relevant to them.
Upon creating a model above (a post, comment, or message) with a mention, you can include a JSON object in the metadata parameter. The metadata represents the mention object, which depends on the design of your data structure. However, Amity provides a default structure to help you create the mention metadata.
To ensure prompt notification of the person mentioned, it's important to provide the list of user IDs for the mention users parameter. This will help ensure that the mentioned users are notified and able to engage with the content.
mentionUsers(userIds)
- In order to mention users and notify specific users. This function supports all mentionable models.
mentionChannel(channelId)
- In order to mention and notify the whole channel. This function supports only a message model.
metadata
- a flexible JSON object which can accommodate any information regarding the mentioned users. Our default structure for representing mentions is also in the metadata property.
To represent mentions using our structure, you will need to utilize the AmityMention object. This object can be created during mentionable model creation, as well as during rendering. The model contains of four properties:
type
- type of the mention - the possible types are user and channel, for post and comment only support mentioning user but message supports mention channel additionally.
index
- start index of current mention
userId
- userId of the user being mentioned. If the type of the mention is channel, then userId
is undefined.
length
- length of the mention
The length property doesn’t include the “@“ mention sign. For example, “@all” mention’s length is 3.
Below is an example to create a comment with mentions by using our default mention metadata structure:
We do not allow banned users to be mentioned, as we take a firm stance against harmful or inappropriate content in social applications. However, admins may still be able to access the names of banned users through the search users function. Once a message is sent, however, banned users' information will be excluded from the payload. Banned users will also not be notified or receive any push notifications if they are mentioned, further ensuring that they do not engage with the content.
As we mentioned that we provided the flexibility for you to define your own mention object data structure to represent mentions. You can use the default data structure provided by the SDK to render mentions in your application, which can be accessed through the helper class. This allows you easily retrieve mentions and render them. The mentionable model contains properties related to the mention feature:
mentionUsers
- The AmityUser object array contains details about users mentioned in the current content.
metadata
- a flexible JSON object which can accommodate any information regarding the mentioned users. Our predefined structure for representing mentions is also in the metadata property.
Below is an example to render mentions in a comment by using our default mention data structure:
The following example demonstrate how AmityMentionMapper
and AmityMention
works in a comment. The function getAttributedString
uses AmityMentionMapper
to extract AmityMention
from metadata, and return the highlighted text.
There is no restrictions over how you'll handle the highlighting the mentions in your UI. At Amity, we pass this metadata property inside CommentRepository.createTextcomment
and CommentRepository.editTextComment
along with other parameters to conveniently highlight across the platforms.
When users are being mentioned, they will receive push notifications. You can customize the push notification content such as the title and the body using the notification setting API. Providing the notification title and body in the titleTemplate
and bodyTemplate
parameters respectively. Here is a sample model:
The Amity Social SDK encompasses comprehensive support for polls, offering developers an effortless way to incorporate polls into their social applications. Polls enable users to create and participate in a diverse range of topics, sparking targeted engagement and conversations among users.
As demonstrated in the code sample below, here's a way to create a poll in the poll post.
Polls can be created with the following settable controls:
question
- A question that can be up to 500 characters long.
answer
- A set of two to ten answers. Each answer can be up to 200 characters long.
answerType
- Indicates whether the survey allows multiple choices. The available options are Single
(default) and Multiple
.
timeToClosePoll
- A time window limiting how long the poll will be open. By default, the setTimeToClosePoll
value is set to 30 days if no value has been set for it.
This function enables you to cast a single vote and the vote cannot be revoked. If the poll type is multiple, you have the option to select multiple choices.
Here's an explanation of the method's parameters:
pollId
: This is a required parameter of type String
, which represents the ID of the poll that the user wants to vote on.
answerIds
: This is a required parameter of type Array<String>
, which represents an array of IDs of the answer options that the user wants to vote for. Users can select one or multiple answers depending on the poll's configuration.
The ability to close a poll is restricted exclusively to individuals who have ownership permissions, such as the creator of the poll or an administrator. It is important to note that a poll can only be closed prior to its designated closing time.
Here's an explanation of the method's parameter:
pollId
: This is a required parameter of type String
, which represents the ID of the poll that the user wants to close.
The deletion of a poll is limited exclusively to individuals who possess ownership permissions, such as the creator of the poll or an administrator.
Here's an explanation of the method's parameter:
pollId
: This is a required parameter of type String
, which represents the ID of the poll that the user wants to delete.
Supported ✅ (Please wait while we prepare a real example!)
To integrate poll functionality, developers can utilize the poll features offered by the Amity Social SDK in their applications. Polls can be tailored to meet specific needs, including options for single or multiple-choice polls, setting poll expiration dates, and more. Users can then participate in the poll by choosing their preferred option. At present, the Amity Social SDK only supports the integration of polls within posts, please refer to - , .
Presence state is a vital aspect of any modern application, acting as a driving factor for engagement products by showing the user's current availability. The AmitySDK supports both observing and notifying the presence of users, analogous to being online and observing users' online statuses.
AmitySDK offers specific methods that allow the logged-in user to enable, disable, or query about presence settings. When these presence settings are enabled, the user is prepared to synchronize their presence state with the server.
Users can enable or disable their presence state feature. Disabled users will be considered offline and cannot use any presence-related functionalities. Network-level settings can also affect this feature.
Presence State feature is disabled by default at both the network and user levels. Please consult with Amity Team to enable this feature on the network level.
The SDK user can invoke the enable()
method within client.presence
to activate their presence status.
The SDK user can invoke the disable()
method within client.presence
to deactivate their presence status. When disabled, the user will be unable to sync both their own heartbeat and the presence of other users in the network. This action also halts any ongoing heartbeat synchronization processes.
The SDK user can invoke the isEnabled()
method within client.presence
to check their presence status. This method also determines if the presence state feature is available for the app. If unavailable, isEnabled()
returns false
. If the feature is available, the method checks the user-level settings, which are managed through the enable()
and disable()
methods as previously described.
The presence heartbeat is a mechanic to signal the system whether a user is online or offline. The SDK offers two convenient methods that allow users to periodically sync or unsync their presence status with the server. When the server receives a heartbeat sync request, it records the timestamp at the time of the request, designating it as the lastHeartbeat
timestamp for that user.
The SDK automatically manages the periodic syncing of this heartbeat once the startHeartbeat
method is called. To cease syncing your presence with the server, the user must invoke the stopHeartbeat
method.
Invoke the startHeartbeat
method in client.presence
to initiate the heartbeat synchronization process. This method automatically checks the user's presence settings within the network, and if enabled, begins to sync the heartbeat at specified intervals defined in the SDK. The synchronization process is handled automatically, streamlining the user's interaction with the system.
The heartbeat sync interval is determined automatically by SDK. Normally you can except heartbeat to be synced every 20-30 seconds.
Utilize the stopHeartbeat()
method within client.presence
to cease the heartbeat synchronization process. To restart the sync, you must invoke the startHeartbeat()
method again.
The SDK also offers functionality to query and synchronize the presence of other users, enabling the creation of a UI that displays their online status. For example, you might use a green dot to indicate whether a particular user is online or offline.
Within the SDK, a user's presence is represented by the AmityUserPresence
object, which contains three properties.
The SDK enables users to query the presence state for a list of users, with a maximum limit of 220. The getUserPresence
method from the AmityUserPresenceRepository
class can be used to fetch a list of AmityUserPresence
objects.
In addition to querying user presence, the SDK also offers a method to periodically sync the presence of other users. This functionality keeps users informed about the online status of others. One application of this feature would be to display a list of users and provide an online indicator for those who are currently online.
The SDK includes the syncUserPresence(id, viewId)
method in the AmityUserPresenceRepository
class to synchronize the presence of another user. This method adds the specified ID to the list of user IDs for presence synchronization, occurring periodically at set intervals. To observe the results of this process, use the getSyncingUserPresence()
method. When presence information is obtained for the currently syncing user IDs, notifications are sent through the observer returned from the getSyncingUserPresence()
method. For further details on observing presence, refer to the #observe-user-presence section.
For optimal use, particularly when displaying a list of users, call this method as a list item appears to synchronize the user's presence state. Conversely, utilize the unsyncUserPresence(id, viewId)
method to stop synchronization when a list item is no longer visible, ensuring that the maximum sync limit is never reached.
The maximum number of user IDs that can be synced at a time is 20. If the count exceeds this limit, the SDK will log an error message to the console. To remove a user ID from the list, use the unsyncUserPresence(id:viewId:) method.
This syncUserPresence(id, viewId)
method also provides an optional viewId parameter. viewId is the unique id of the view that this user id is tied to. In most of the cases, you do not need to specify any value to this parameter. viewId is useful if you want to bind same user id to multiple views in same screen. In that case, if you want to unsync presence for one view, it won't affect presence syncing for same user id in another view.
SDK will log a message in console incase of any error which occurs during syncing process.
The SDK includes the unsyncUserPresence(id, viewId)
method to cease syncing the presence of a specific user ID. When a user ID is unsynced, the SDK removes it from the current list of synced IDs, and the observer returned from the getSyncingUserPresence()
method will no longer provide presence information for that user. The method also features an optional viewId
parameter, functioning similarly to the syncUserPresence(id, viewId)
method.
The SDK also provides a convenient method to unsync all user ids which are currently being synced. This is particularly useful when you don’t care about the user ids being synced. One usecase for this is when user navigates to another screen which do not care about syncing previously synced users at all. So you can call unsyncAllUserPresence()
method when the previous screen disappears.
After adding users for synchronization, the next step involves observing their presence. The SDK offers an observer via the getSyncingUserPresence()
method. Whenever presence information is retrieved for users synced through syncUserPresence(id, viewId)
, this information is published through the observer.
Accessing User Presence:
You can access the presence information for synced users in two ways:
Through the Observer Returned from getSyncingUserPresence()
: When the presence information is updated, the observer provides an array of [AmityUserPresence]
for the user IDs being synced. Users need to map AmityUserPresence
from this array to the view where the information is to be displayed.
Through the AmityUser
Object: When presence information is fetched from the server, the lastHeartbeat
timestamp is mapped to the lastHeartbeat
property of the AmityUser
object, if available. Users can directly access the lastHeartbeat
property from the AmityUser
object to determine whether a user is online or offline.
The SDK provides the getOnlineUsersCount
method in the AmityUserPresenceRepository
class to query the count of online users. Please note that this count does not update automatically.
The SDK provides a method getOnlineUsersSnapshot in AmityUserPresenceRepository to query list of online users in a network. The list of users can be accessed through users property which returns an array of AmityUser.
This snapshot is not auto updating & supports query of up to 1000 online users.
When this snapshot object is initialized, it fetches the snapshot of user presences of all online users in current network. Then it maps those information to AmityUser per page and provides list of AmityUser with pagination. Each page can contain max 20 users. When snapshot is returned, it will contains users for first page. You can still fetch more users if available through loadMore() method. Once more users are fetched, user can access those users through users property. You can also use canLoadMore property to determine if there are more online users which can be fetched.
The SDK also provides a way to query & sync presence of members of conversation channel. This allows you to create a UI which displays presence status of other members in the conversation channel. Example: A green dot to indicate whether other user is online or offline in conversation channel.
In SDK, channel presence is represented by AmityChannelPresence
object. This object contains 3 properties.
The SDK also offers the functionality to query and synchronize the presence of members within a conversation channel. This enables the creation of a user interface that displays the presence status of other members in the channel, such as using a green dot to indicate whether a user is online or offline within a specific conversation. In the SDK, channel presence is represented by the AmityChannelPresence
object, which contains three properties.
When displaying a list of conversation channels, it is advisable to use this method. The observer offers a class named AmityChannelPresence
that holds the presence information for the channel's members. Likewise, the unsyncChannelPresence(id, viewId)
method should be used to stop syncing the presence state when a list item is no longer visible, ensuring that the maximum sync limit is never reached.
Only syncing of Conversation channel type is supported ! The maximum number of channel IDs that can be synced at a time is 20. If the count exceeds this limit, the SDK will log an error message to the console. To remove a channel ID from the list, use the unsyncChannelPresence(id, viewId
) method.
This syncChannelPresence(id, viewId)
method also provides an optional viewId
parameter. viewId
is the unique id of the view that this user id is tied to. In most of the cases, you do not need to specify any value to this parameter. viewId
is useful if you want to bind same channel id to multiple views in same screen. In that case, When you unsync channel presence in one view, it won't affect presence syncing for same channel id in another view.
SDK will log a message in console incase of any error which occurs during syncing process.
The SDK offers the unsyncChannelPresence(id, viewId)
method to cease syncing the presence of a particular conversation channel. If the channel ID is unsynced, the SDK will remove it from the list of channel IDs whose members are currently being synced. Consequently, the observer returned by the getSyncingChannelPresence()
method will no longer contain information about this channel. This method includes an optional viewId
parameter and operates similarly to the syncChannelPresence(id, viewId)
method.
The SDK includes a convenient method, unsyncAllChannelPresence()
, to stop syncing all channels that are currently being monitored. This feature is particularly useful when the application no longer requires information about the channels being synced. For example, this method can be called when a user navigates to a different screen that has no dependence on the previously synced channels, allowing for an efficient transition between different parts of the application.
After adding the channels to sync, the next step is observing the user presence. The SDK provides an observer through the getSyncingChannelPresence()
method. Whenever presence information is fetched for channels synced through the syncChannelPresence(id, viewId)
method, that information is published through this observer.
Accessing Channel Presence:
Through the observer returned from getSyncingChannelPresence()
Whenever presence information is updated, the observer will provide an array of [AmityChannelPresence]
for the channels that are being synced. Users must map AmityChannelPresence
from this array to the view where this information is to be displayed
Property | Remarks |
---|---|
Property | Remarks |
---|
The SDK includes the syncChannelPresence(id,viewId)
method in the AmityChannelPresenceRepository
class to synchronize the presence of members within a conversation channel. This method adds the specified ID to the list of channel IDs whose members' presence will be synced, and this process occurs periodically at a predetermined interval. To observe the results of this syncing process, use the getSyncingChannelPresence()
method. When the presence information for the currently syncing channel members is obtained, it is published through the observer returned by the getSyncingChannelPresence()
method. More details can be found in the section.
userId
Id of the user
lastHeartbeat
Timestamp when that user last synced its heartbeat with the server.
isOnline
Convenient property to determine online status. User is considered online if its lastHeartbeat has been within last 60 seconds.
channelId | Id of the Channel |
userPresences | AmityUserPresence object for members whose presence state has been synced |
isAnyMemberOnline | If any user's (except you) lastHeartbeat has been within last 60 seconds |
Live Objects and Live Collections are observable data holders. The observer gets updated when there is a change of data in the local cache.
There are two main sources that can make changes to the object and collection:
When an object gets updated by an action from the current device.
Real-time events of the subscribed objects from the server.
For an in-depth explanation on how your SDK handles Live Objects and Live Collections, refer to the platform-specific subpages in this section.
By subscribing to a specific topic in the Real-time event system, users can ensure that they are receiving the most up-to-date information and notifications related to the observed object across devices.
Live Object allows users to observe the states of a single object within the app, such as a post, message, or channel. With Live Object, users can automatically receive notifications of any data updates related to the observed object, whether from the network or locally.
Live Object also provides additional states, such as isLoading
and error
, which can be helpful for understanding the status of the observed object and any potential issues that may arise.
Live Object API is designed around the observer design pattern, allowing users to subscribe to an object, receive notifications of any data updates, and unsubscribe when necessary. These updates are delivered via Snapshot, a captured state that is frozen and cannot be changed. Users can own and access these snapshots, using them to stay up-to-date with the latest data within the app.
It's worth noting that while data updates may occur internally within the SDK, these updates will not affect previous snapshots. The only way for users to see the latest data is by getting new snapshots delivered via Live Object updates.
Live Collection allows users to observe changes to an entire collection of data within their app in real-time. Live Collection works similarly to Live Object, with the main difference being that Live Collection notifies changes related to the entire collection rather than just a single object.
To use Live Collection, users can observe to changes on a specific collection within the SDK. The collection handler then receives a snapshot of changes since the last result, which includes three possible events:
the indices of the objects that were deleted
the indices of the objects that were inserted
the indices of the objects that were modified.
By subscribing to changes on a specific collection using Live Collection, users can stay up-to-date with the latest changes and updates to important collections within the app. This can be particularly helpful for managing large amounts of data or monitoring changes to frequently updated collections, such as messages or posts.
In iOS AmitySDK, we have a concept of Live Object and Live Collection. LiveObject is represented by AmityObject
instance and LiveCollection is represented by an instance of AmityCollection
. These are generic classes which encapsulates any other object and notifies the observer whenever any property of the encapsulated object changes.
Live Object helps to observe changes in a single object whereas Live Collection helps to observe changes in a list of objects. For example: AmityObject<AmityPost>
or AmityCollection<AmityMessage>
.
SDK handles a lot of data received from various sources. Data can be present in local cache. It might also be queried from the server or received from some real-time events. This means, some data is constantly updating. The data that you are accessing at the moment can get updated by other sources and becomes out of sync.
Live Object and Live Collection helps in syncing these constantly updating data, so you will always get the most recent one. Whenever the data gets updated, you will be notified through helper methods in live object and live collection classes.
New data gets automatically collected everytime when there is an updation and user need not refresh to get the recent data.
Live collection is available for the following functionalities in user/community feeds:
Post Collection
Comment Collection
Reactions Collection
Followers/Following Collection
Channel Collection
Message Collection
Channel Member Collection
Community Collection
Community Members Collection
Both AmityObject
and AmityCollection
provide methods that help to observe changes in objects. The life cycle of observation is tied to its token. As soon as the token is invalidated or deallocated, observation ends.
AmityNotificationToken
is a simple object which keeps track of what is being observed. Each observation from Live Object or Live Collection is tied to its respective token. As soon as the token is invalidated or deallocated, observation ends. The token is declared within the scope of the class.
The token is used in combination with AmityObject
or AmityCollection
. We will explore it more in AmityObject and
AmityCollection
concepts.
AmityObject
is a generic class that keeps track of a single object. It is a live object. In iOS AmitySDK
, any object which is encapsulated by AmityObject
is a live object.
Examples:
AmityObject<AmityMessage>
AmityObject<AmityChannel>
AmityObject
class exposes the following methods:
observe
observeOnce
These methods help observe a live object. Whenever any property for observed object changes, the observer is triggered.
observe
method can be triggered multiple times throughout the lifetime of the application as long as its associated AmityNotificationToken
is retained in memory. observeOnce
method, on the other hand, can only be triggered once.
Both observe
and observeOnce
methods will be called from the main thread so you can perform any UI update-related tasks from within the observe block itself.
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 through the dataStatus
property of AmityObject
.
In parallel, a request is made to server to fetch the latest version of the data. Once the data is returned, the observe block will be triggered again.
Any future changes to that data from any sources can trigger observer.
Lifecycle: The life cycle of the observer is tied to its token. If the token is not retained, then the observer can get deallocated at any time and will not be called. Both observe
and observeOnce
block will be retained using token as shown below.
The AmityNotificationToken
provides a method called invalidate()
which can be used to invalidate the token anytime. As soon as you invalidate the token, your observation stops and observe block will no longer be triggered.
There are multiple ways to access data from AmityObject
. AmityObject
exposes the following properties:
dataStatus
: Indicates whether the data is fresh or local
loadingStatus
: Indicates if the data is being loaded from server or not
object
: The actual object that is being tracked or encapsulated by this AmityObject
Once you add an observer block, you can access both local or fresh data as shown below.
If you want to observe fresh object just once, you can check the data status and invalidate the token once you receive the fresh object.
For
observerOnce
method, if data is present locally, this observer will be triggered only once with that local data. If you are looking for fresh data, use theobserve
block and invalidate the token once fresh data is received as shown above.
If you only care about local data and do not want to observe anything, you can also access the object
property from AmityObject
directly.
While this is possible, we recommend accessing object from within theobserve
or observeOnce
block depending on your requirement.
AmityObject
can be tracked for their loading status by accessing the loadingStatus
property, which is of type AmityLoadingStatus
and it can have one of four possible values.
0 (notLoading): Indicates that the data is already fresh locally and does not need to be loaded.
1 (loading): Indicates that the client is currently loading the data from the server.
2 (loaded) - Indicates that the client has successfully loaded fresh data from the server and is up to date.
3 (error) - Indicates that the data is unable to load due from a specific error.
AmityCollection
is a generic class that keeps track of a collection of objects. It is a live collection. In iOS SDK, any object which is encapsulated by AmityCollection
class is a live collection.
Examples:
AmityCollection<AmityMessage>
AmityCollection<AmityChannel>
AmityCollection
exposes these methods:
observe
observeOnce
These methods help to observe a live collection. Whenever any property for any object within the collection changes, the observer is triggered.
observe
method can get triggered multiple times throughout the lifetime of the application as long as it's associated AmityNotificationToken
is retained in memory. observeOnce
, on the other hand, can only be triggered once.
Both observe
and observeOnce
method will be called from the main thread so you can perform any UI update related task within the observe block itself.
If the requested data collection is stored locally on the device, the block will be called immediately with the local version of the data. This can be verified through the dataStatus
property of AmityCollection
.
In parallel, a request is made to the server to fetch the latest version of the data. Once the data is returned, the observe block will be triggered again.
Any future changes to the data from any sources can trigger observer.
Lifecycle: The life cycle of the observer for AmityCollection is also tied to its token. If the token is not retained, the observer can get deallocated at any time and will not be called. So, both observe
and observeOnce
block should be retained. You can refer to the section in AmityObject
about retaining and invalidating a token.
Unlike most databases, AmityCollection
does not return all data in an array. Instead, data is 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 necessary.
AmityCollection
also exposes a count
property which determines the number of objects present in a collection.
With these two public interfaces, you can create a robust list UI for your use case. Similar to AmityObject
, AmityCollection
also exposes dataStatus
and loadingStatus
property.
Let's look at the typical flow when accessing a collection data.
If you want to observe only fresh or local collection, you can access it using thedataStatus
property and invalidate the token once you have accessed your desired collection data.
For
observerOnce
method, if data is present locally, this observer will be triggered only once with that local data. If you are looking for fresh data, useobserve
block and invalidate the token once fresh data is received as shown above.
Observer also provides you with the AmityCollectionChange
object which contains indexes of what is added, deleted, or modified in a collection. You can also refer to these properties to update the UI for the list.
While SDK provides liveCollection.object(at:)
to access a single item, you might often find the need to iterate through all objects in the collection. The SDK has a convenient way to do this using .allObjects()
.
Using the above method is the same with this logic:
AmityCollection
in SDK returns a maximum of 20 items per page. It has nextPage()
and previousPage()
method to fetch more data. It also exposes hasNext
and hasPrevious
property to check if next page or previous page is present.
Once next page is available, the same observe
block gets triggered and you can access the collection as shown above. If you want to shrink the collection to the original first page, you can do so by calling resetPage()
method on the same collection.
One typical usage of Live Collection is in UITableView
. Below is an example of fetching a collection and displaying it in a tableview.
AmityObject and AmityCollection are now observable object with its properties marked with @Published
annotation. Now you can use live object & live collection directly within your SwiftUI views.
Since AmityObject
& AmityCollection
are observable object, it can be used as an ObservedObject within SwiftUI views. We recommend to create small view which observes AmityCollection & AmityObject as ObservedObject as shown in code sample below.
Live Collection - SwiftUI
Since the properties are published, If you are using Combine Framework, you can also subscribe to changes on those properties.
Live Object - Combine
Live Collection - Combine
ℹ️ States of live collection & live object are published before snapshots so that you can compare the state from within subscriber.
#1: LiveCollection is not updated when used from inside of another observable class.
AmityCollection
& AmityObject
is an ObservableObject
. When this live collection or live object is embedded inside another Observable Object, SwiftUI cannot observe the changes in snapshot occurring within Live collection & Live object. As a result, there might be a situation where you see your view is not getting updated even when snapshot(s) are updated. This is a common problem with nested observable object in SwiftUI.
To solve this issue we recommend to create a specific view which observes AmityCollection
& AmityObject
as @ObservedObject
as shown in code example.
#2: Published property still returns old values.
Since the properties of AmityCollection & AmityObject are marked with @Published
annotation, the publishing of changes occurs in the property’s willSet
block, meaning that any subscribers will receive an update before the property is changed. This behaviour can easily lead to unexpected bugs.
For more details, please refer to https://developer.apple.com/documentation/combine/published
Live Object | @Published | Remarks |
---|---|---|
Live Collection | @Published | Remarks |
---|---|---|
dataStatus
✅
-
loadingStatus
✅
-
snapshot
✅
New
error
✅
-
object
❌
Deprecated
dataStatus
✅
-
loadingStatus
✅
-
snapshots
✅
New
error
✅
New
Live Objects are supported in the Android SDK with RxJava Data Streaming
The RxJava3 library is being used in Android development to achieve Live Object and Live Collection behavior.
It is a Java VM implementation of ReactiveX, a library for composing asynchronous and event-based programs by using observable sequences. The building blocks of RxJava are Observables and Subscribers. Observable is used for emitting items and Subscriber is used for consuming those items.
You can visit ReactiveX for more information.
SDK handles lots of data received from various sources. Data can be present in local cache. It might also be queried from the server or received from some real-time events. What this means is that same data is constantly updating. The data that you are accessing at the moment can get updated by other sources and becomes out of sync.
Rx3 Data Stream helps in syncing the data so you will always get the most recent one. Whenever the data updates, you will be notified through Flowable Objects and Flowable Collection.
New data gets automatically collected everytime when there is an updation and user need not refresh to get the recent data.
Live Collection is available for the following functionalities in user/community feeds via pagingData APIs:
For any specific errors that's handled in PagingData please visit the web page below to properly handle its errors https://developer.android.com/topic/libraries/architecture/paging/load-state#adapter
Post Collection
Comment Collection
Reactions Collection
Followers/Following Collection
Channel Collection
Message Collection
Channel Member Collection
Community Collection
Community Members Collection
To retrieve data from the RxStream, we need to subscribe to the Stream(Flowable/Single/Completable) by defining subscribing and observing threads.
In the RxJava3 framework we have these different types of objects that can be observed:
Flowable - emits a stream of elements
doOnNext
doOnError
Single - emits exactly one element
doOnSuccess
doOnError
Completable - emits a “complete” event, without emitting any data type, just a success/failure
doOnComplete
doOnError
Data Stream uses all standard RxJava3 operators.
To get channel data, below is a sample code.
The Amity Android SDK comes equipped with asynchronous and data stream capabilities, powered by RxJava3 by default. However, for those who prefer to use Kotlin's Coroutines, the SDK can be seamlessly integrated with the following Kotlin extension functions, allowing for easy interoperability between Amity Android SDK functions and Kotlin Coroutines functions.
By using the .await()
method, it enables the conversion of Completable
and Single<T>
functions of the Amity Android SDK into suspend
functions.
By using the .asFlow()
method, it enables the conversion of Flowable<T>
functions of the Amity Android SDK into Flow
functions.
Amity Android SDK seamlessly integrates with Jetpack Compose UI, allowing you to take full advantage of the modern UI toolkit provided by Jetpack Compose. You can effortlessly incorporate our SDK into your Jetpack Compose-based projects to enhance your app's social experience. This compatibility ensures that you can leverage the power of Jetpack Compose while benefiting from the features and capabilities our SDK provides.
In Jetpack Compose, integrating data from a `Flow<PagingData<T>>` source into your UI is made easy through the `collectAsLazyPagingItems()` function. This function allows you to seamlessly paginate and display items within your Composable functions.
To start using it, add compose paging dependency in your project app level build.gradle
file.
Then in your Composable functions, you can collect from flow and display data, and also can observe the load state.
By using collectAsState()
method, it can deliver asynchronous data updates to your Compose UI components.