Our Core Concepts section will outline functionality and information that is pertinent to all of our Chat SDK Modules.

The following concepts are shared across all platforms and thus are centralized in this section for your ease of navigation and use.

Session State

Users/Permissions

Live Objects

Push Notification

Live Messages

Amity Collection

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.

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

What happens when a user is deleted?

The user cannot be reactivated

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 is still saved, but the username is deleted and replaced with "Deleted 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".

All conversation channels created by the user will be deleted.

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.

All messages, channel names, and file attachments that the User created will be deleted

After the account is deleted, all messages for all channels and all attachments that created by the user are deleted and cannot be restored.

Channel member count will be updated

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 user-related data will be permanently deleted and cannot be recovered

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.

Posts, comments and associated IDs, as well as subordinate posts and subordinate comments of the user will be marked as deleted

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.

Reaction and comment count will be updated

All reactions and comments posted by the deleted user are detected and updated in the posts.

User will be marked as deleted when queried

The status of the user's account is marked as "deleted" when queried and the user can no longer access it.

API Parameters

Headers

Path

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

Bad Request error

User Not Found error

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.

import { UserRepository } from '@amityco/js-sdk';

const liveObject = UserRepository.getUser('userId');
liveObject.on('dataUpdated', user => {
  // user is successfully fetched
});

userRepo.userForId('user123')

let liveUser = UserRepository.getUser("some-user-id")
userObject.on(“dataUpdated”, model => {
   // you can access user object as model here
  console.log(model.userId, model.displayName)
})

userRepo.getAllUsers()

import { UserSortingMethod } from '@amityco/js-sdk'

userRepo.getAllUsers(UserSortingMethod.DisplayName)

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.

Identity

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.

Description of Users

User Repository

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.

import { UserRepository } from '@amityco/js-sdk';
const userRepo = new UserRepository();

Ban User

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.

Refer global ban documentation for instructions on how to globally ban a user.

For more information please visit to User & Content Management

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.

import AmityClient from “@amityco/js-sdk”

const amityClient = new AmityClient({ apiKey, apiEndpoint })
amityClient.registerSession({ userId, displayName, avatarFileId })

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 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.

When token has expired:

• It moves to tokenExpired state.

Read and Observe Session State

The SDK provides APIs for reading and observing the session state.

Implementing an app based on 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:

Session Handler

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.

Access Token Renewal

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.

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.

Create a User Token

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 .

Search User

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.

Query Users

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.

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.

Flag a User

To flag a user, call the following method:

Unflag a User

To unflag a user, call the following method:

Check Flagged By User

To check whether a user has been flagged by the current user:

Update User Information

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

Update Current User's Avatar

You can upload an image and set it as an avatar for the current user.

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:

1. Member - has no moderation privileges

2. Community/Channel Moderator - can assert general moderation privileges on other users

3. Super Moderator - can assert general moderation privileges and be exempt from moderation from other users

4. Global Admin (Admin Only) - can assign the roles of others, assert all moderation privileges and be exempt from moderation

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 .

User

*UserV3

Channel

*ChannelV3

Community

*CommunityV3

User Feed, Posts, Comments, & Notifications

Permissions

Each role can be assigned with many permissions. Below is a list of all the possible permissions that can be assigned to a user.

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.

Webhook

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.

For more information, go to Webhook Events settings.

In this scenario, there's no SDK involvement needed. The whole notification process is managed on your end.

Direct Push Notifications

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.

Click for more Network Level settings.

Click to learn on different SDK Settings.

Push Notification Examples

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)

Push Notification Triggers

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.

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.

Step 1:

Go to Apple Developer Console (i.e https://developer.apple.com) and click on Certificates.

Step 2:

Select Apple Push Notification Service SSL (Sandbox & Production)

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.

That’s it. Now the certificate is setup, Please follow the steps shown in Register & Unregister Push Notifications section to correctly send APNS token to receive push notification.

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.

Image Data

Upload Images

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.

Retrieve Images

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.

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.

File Data

Upload Files

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.

import { FileRepository, LoadingStatus } from '@amityco/js-sdk';

const liveObject = FileRepository.createFile({ 
  file, // https://developer.mozilla.org/en-US/docs/Web/API/File
  onProgress: ({ currentFile, currentPercent }) => {
  },
});

liveObject.on('loadingStatusChanged', ({ newValue }) => {
  if (newValue === LoadingStatus.Loaded) {
    console.log('The file is uploaded', liveObject.model);
  }
});

liveObject.on('dataError', (error) => {
  console.error('can not upload the file', error);
});

// upload video
const liveObject = FileRepository.createVideo({ 
  file,
  onProgress: ({ currentFile, currentPercent }) => {
  },
});
Refer to the 
file model
 for the description of the response after a successful file creation. If an error is encountered while creating the file, it will return the following errors:
//Attached file payload is too large
{
  "status": "error",
  "code": 500000,
  "message": "Payload too large."
}

// Unexpected error
{
  "status": "error",
  "code": 500000,
  "message": "Unexpected error"
}

Retrieve Files

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.

import { FileRepository } from '@amityco/js-sdk';

let file;
const liveObject = FileRepository.getFile(fileId);

liveObject.on('dataUpdated', (updatedModel) => {
  file = updatedModel;
});

liveObject.on('dataError', (error) => {
  console.error('Can not get the file', error);
});

file = liveObject.model;

Delete Files

In addition to uploading and retrieving files, Amity provides a deleting function to delete a file that is no longer needed.

import { FileRepository } from '@amityco/js-sdk';

const success = await FileRepository.deleteFile(fileId);

"data": {
    "success": true
  }

//Permission denied error
{
  "status": "error",
  "code": 400301,
  "message": "Permission denied"
}

Resource Not Found error
{
  "status": "error",
  "code": 400400,
  "message": "Resource Not Found."
}

//Passed the wrong parameters error
{
  "status": "error",
  "code": 500000,
  "message": "Parameters error."
}

Video Data

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.

Upload Videos

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.

//Attached file payload is too large
{
  "status": "error",
  "code": 500000,
  "message": "Payload too large."
}

// Unexpected error
{
  "status": "error",
  "code": 500000,
  "message": "Unexpected error"
}

Retrieve Videos

Get a Specific Video Resolution

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

Get a Video Thumbnail Image

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.

let fileRepository = AmityFileRepository(client: client)
    ...
    
    func downloadVideoThumbnailAsData(from message: AmityMessage) {
        guard let thumbnailFileId = message.data?["thumbnailFileId"] as? String,
              !thumbnailFileId.isEmpty,
              let imageInfo = message.getVideoThumbnailImageInfo() else { return }
        
        
        // Download from url and return saved image url.
        fileRepository.downloadImage(fromURL: imageInfo.fileURL, size: .small) { imageUrl, error in
            // Handle image url and error.
        }
    }
    
    func downloadVideoThumbnailAsUIImage(from message: AmityMessage) {
        guard let thumbnailFileId = message.data?["thumbnailFileId"] as? String,
              !thumbnailFileId.isEmpty,
              let imageInfo = message.getVideoThumbnailImageInfo() else { return }
        
        // Download from url and return image.
        fileRepository.downloadImageAsData(fromURL: imageInfo.fileURL, size: .small) { image, size, error in
            // Handle image and error.
        }
    }

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:

Client Registration

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.

Client Unregistration

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 userId Parameter

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.

Get User Push Notification Settings

The SDK provides "getSettings()" function within User Notification to inspect the current settings of each feature module.

Update Push Notification Settings

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 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.

Initialize Push Notification

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:

Retrieve Push Notifications

Push Notification In China

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.

Live Objects and Live Collections

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>.

How it Works

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

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

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.

Observer

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.

Invalidate token

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.

Accessing Objects

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 the observe 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.

AmityLoadingStatus

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

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.

Observer

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.

Accessing Collection

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, use observe 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.

Iterate through collection

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:

Pagination

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.

SwiftUI Support

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.

Access AmityObject & AmityCollection in 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 Object - SwiftUI

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

FAQ’s:

#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.

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

Get Community Push Notification Settings

The SDK provides "getSettings()" function within Community Notification to inspect which notification events are enabled on the community.

Update Community Push Notification Settings

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 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.

Start Heartbeat

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.

Stop Heartbeat

Utilize the stopHeartbeat() method within client.presence to cease the heartbeat synchronization process. To restart the sync, you must invoke the startHeartbeat() method again.

Overview

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.

Presence Setting

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.

Enable Presence Status

The SDK user can invoke the enable() method within client.presence to activate their presence status.

Disable 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.

Query Presence Status

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 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.

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 - #create-poll-post, #poll-post.

Create Poll

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.

Vote Poll

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.

Close Poll

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.

closePoll = async (pollId: string) => Promise<any>

Delete Poll

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.

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:

• Mention in Post

• Mention in Comment

• Mention in Messages

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.

Mention Users

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.

Default Mention Metdata Structure

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

Mention Users Example

Below is an example to create a comment with mentions by using our default mention metadata structure: