Requirements

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

android {
    ...
    defaultConfig {
        minSDKVersion 21 // at least 21
    }
}

Installation

Add the Jitpack repository in your project level build.gradle at the end of repositories:

dependencyResolutionManagement {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

allprojects {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

Add the dependency in your module level build.gradle. Find latest SDK version at Changelog.

implementation 'com.github.AmityCo.Amity-Social-Cloud-SDK-Android:amity-sdk:x.y.z'

implementation("com.github.AmityCo.Amity-Social-Cloud-SDK-Android:amity-sdk:x.y.z")

Android API level below 24

If your minSDKVersion is below 24, ie., 23 or 21, there are additional configurations required.

In your project build.gradle,

buildscript {
    repositories {
        google()
        gradlePluginPortal()
        ...
    }
    dependencies {
        ...
        classpath 'gradle.plugin.com.github.sgtsilvio.gradle:android-retrofix:0.4.1'
    }
}

Managing conflicting file generation

In your app module's build.gradle, add the following packaging options.

android {
    ...
    packagingOptions {
        exclude 'META-INF/INDEX.LIST'
        exclude 'META-INF/io.netty.versions.properties'
    }
}

Code Obfuscation

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.

-keep class com.ekoapp.ekosdk.** { *; }
-keep interface com.ekoapp.ekosdk.** { *; }
-keep enum com.ekoapp.ekosdk.** { *; }
-keep class com.amity.socialcloud.** { *; }
-keep interface com.amity.socialcloud.** { *; }
-keep enum com.amity.socialcloud.** { *; }
-keep class co.amity.rxupload.** { *; }

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:

-keepclassmembers class * implements java.io.Serializable {
private static final java.io.ObjectStreamField[] serialPersistentFields;
private void writeObject(java.io.ObjectOutputStream);
private void readObject(java.io.ObjectInputStream);
java.lang.Object writeReplace();
java.lang.Object readResolve();
}

Amity SDK Log Visibility

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.

android {
    defaultConfig {
        resValue 'bool', "IS_HIDDEN_AMITY_LOG", "true"
        …
    }
    …
}

In the 'build.gradle' application, you can also customize the log display depending on the build variant, as in this example.

android {
    def IS_HIDDEN_AMITY_LOG = "IS_HIDDEN_AMITY_LOG"
    
    buildTypes {
        release {
            resValue 'bool', IS_HIDDEN_AMITY_LOG, "true"
            …
        }
        debug {
            resValue 'bool', IS_HIDDEN_AMITY_LOG, "false"
            …
        }
    }

}

Installation

Add the SDK to your repository via npm: npm install @amityco/js-sdk --save.

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 community.amity.co.

If you already installed our SDK with the name eko-sdk, be sure to check our migration guide from version 4 to 5.

Browser Support

• Chrome: 38+

• Firefox: 42+

• Microsoft Edge: 13+

• Safari: 9+

• Opera: 25+

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 Dynamic Import with SSR disabled.

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.

Getting Started

We will walk you through the process of installing ionic and all the necessary dependencies for development.

Installing Ionic

Ionic comes with a convenient command line utility to start, build, and package Ionic apps. To install it, simply run:

sudo npm install -g @ionic/cli 

Adding Capacitor to your app

In the root of your application, install Capacitor:

npm install @capacitor/core --save

Adding support for native platform

Now, we need to copy the native platform template into your application:

ionic capacitor add <platform>

Opening the Application

To open the application in your IDE, run:

npx cap open <platform>

Where to go next

Now you’re ready to start integrating our chat SDK into your application.

Using our Chat SDK

• Ionic with JavaScript framework

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

Installation

Add the SDK to your repository by adding amity_sdk depedency

With Flutter:

 $ flutter pub add amity_sdk

This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get) :

dependencies:
  amity_sdk: ^0.22.0

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)

Behavioral Change Announcement

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:

1. Post creators will still have the ability to view their own soft-deleted posts.

2. Admins/Super Admins will still retain the privilege to view user's soft-deleted posts.

3. Non-Admin users, however, will no longer be able to access soft-deleted posts of other users.

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

API Deprecation Notice: v3/files for Image Moderation

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.

RxJava2 and PagedList Deprecation Notice

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.

What this means:

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

Objective-C Deprecation Notice & Minimum Target Upgrade to iOS 13

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.

Managed UI Kit Deprecation Announcement

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.

What happens once the managed version UI Kit is deprecated?

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

How to migrate off the managed version UI Kit?

iOS SDK Breaking Changes

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?

According to Apple’s announcement here, "Starting April 2022, all iOS and iPadOS apps submitted to the App Store must be built with Xcode 13 and the iOS 15 SDK."

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

Maintenance Strategy for Breaking Changes

Updated: 27 April 2021

• EkoSDK 4.8 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.

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

Follow / Unfollow Limited Availability Announcement

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.

iOS SDK Breaking Changes

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?

According to Apple’s announcement here, "Starting April 2021, all iOS and iPadOS apps submitted to the App Store must be built with Xcode 12 and the iOS 14 SDK."

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?

Please refer to this announcement section for details.

SDK Installation

For instructions on installing the Amity Social Cloud SDK, refer to the installation guide for your platform.

• iOS

• Android

• JavaScript

• TypeScript

• React Native

• Flutter

• Ionic

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.

Initialization

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:

1. Click Settings to expand the menu.

2. Select Security.

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

let client = try! AmityClient(apiKey: "api-key", region: .global)

Specify Endpoints Manually (Optional)

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.

let endpoint = AmityEndpoint(httpUrl: "http-endpoint",
                              rpcUrl: "rpc-endpoint",
                            mqttHost: "mqtt-host")
let client = try! AmityClient(apiKey: "api-key", endpoint: endpoint)

We currently support multi-data center capabilities for the following regions:

Specify database encryption mode (Optional)

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.

Database Encryption Modes:

The SDK offers three encryption modes:

1. NONE: No encryption is applied.

2. AUTH: Access token storage is encrypted.

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

Authentication

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.

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.

Logout

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.

client.logout()

client.unregisterSession();

Disconnect

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.

client.disconnect()

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.

Devices

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.

Tutorials

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!

Amity Social Cloud Developer Kits

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.

Download our Developer Kits

API

{
  "paging": {
    "next": "eyJza2lwIjoyMCwibGltaXQiOjEwfQ=="
  },
}

curl --location --globoff 'https://api.sg.amity.co/api/v3/communities?filter=all&sortBy=lastCreated&options[token]=eyJza2lwIjoxMCwibGltaXQiOjEwfQ%3D%3D' \
--header 'accept: application/json' \
--header 'Authorization: Bearer xxx'

curl --location 'https://api.sg.amity.co/api/v2/blacklist/records' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxx' \
--data '{
  "regexs": [
    "word1",
    "word2",
    "word3"
  ],
  "isMatchExactWord": true
}'

curl --location --request PUT 'https://api.sg.amity.co/api/v3/network-settings/social' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxx' \
--data '{
  "isFollowWithRequestEnabled": false
}'

Social and Chat

curl --location 'https://api.sg.amity.co/api/v3/communities?filter=all&isDeleted=false'
--header 'accept: application/json'
--header 'Authorization: Bearer xxx'

curl --location 'https://api.sg.amity.co/api/v3/communities?filter=member' \
--header 'accept: application/json' \
--header 'Authorization: Bearer xxx'

curl --location 'https://api.sg.amity.co/api/v4/communities/657306a3189cef362ea99923/users/roles' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxx' \
--data '{
  "roles": [
    "community-moderator"
  ],
  "userIds": [
    "test"
  ]
}'

iOS

Poll

Console

Portal

Alternative solutions for unsupported features

Beta features

{
  "apiKey": "xxx",
  "from": 0,
  "query": {
    "isDeleted": false,
    "targetId": [
      "test"
    ],
    "targetType": "community"
  },
  "size": 20,
  "sort": {
    "createdAt": {
      "order": "desc"
    }
  },
  "userId": "test"
}

"query": {
    "isDeleted": false
}

Frequent error types: Definition

const [sessionState, setSessionState] = useState('');

useEffect(() => {
  return Client.onSessionStateChange((state: Amity.SessionStates) => {
    setSessionState(state);
  });
}, []);

"paging": {
    "next": "string",
    "previous": "string"
}

General

curl --location --request DELETE 'https://api.sg.amity.co/api/v4/users/test2?deleteAll=true&markMessageDeleted=false&hardDeletePost=false&hardDeleteComment=false' \
--header 'accept: application/json' \
--header 'Authorization: Bearer xxx'

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

Manual Installation

Download the latest iOS SDK

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

Using Dependency Manager

AmitySDK supports installation via dependency managers.

• SwiftPM

• Cocoapods

• Carthage

SwiftPM Installation

To integrate AmitySDK into your project via SwiftPM, please follow the instruction below.

• Add a Package Dependency

Enter the repository URL to search the package, and choose to install AmitySDK.

https://github.com/AmityCo/Amity-Social-Cloud-SDK-iOS-SwiftPM

Carthage Installation

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

binary "https://raw.githubusercontent.com/AmityCo/Amity-Social-Cloud-SDK-iOS/master/AmitySDK.json" ~> 5.3.0 

Cocoapods Installation:

To integrate the Amity Social Cloud SDK into your Xcode project using CocoaPods, specify the following lines of code in your Podfile:

platform :ios, '12.0'

use_frameworks!

pod 'AmitySDK'

This installs the latest version of SDK. To get more info about our latest release, please look into changelog 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 Github repo for further resolutions.

Additional Steps for Amity Video

Amity Video requires the AmitySDK as dependencies. First, ensure you have installed the AmitySDK as per the instructions above.

To use live video broadcast:

• Import AmityLiveVideoBroadcastKit.xcframework to your project.

To use live video player:

For version 6.0.0 - 6.7.0

• Import AmityVideoPlayerKit.xcframework to your project

• Download MobileVLCKit.xcframework, and import 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.

• Add a Package Dependency

For version 6.8.0 and above

• Import AmityVideoPlayerKit.xcframework to your project

• Download MobileVLCKit.xcframework, and import to your project.

• Switch each framework to Embed & Sign, all xcframeworks.

Amity Video with SwiftPM

To install Swift Packages for Amity Video, please follow the instructions below.

• Add a Package Dependency

1. Install AmityVideoBroadcast

To use live video broadcast functionalities. Enter the repository URL to search the package, and choose to install AmityVideoBroadcast.

https://github.com/AmityCo/Amity-Social-Cloud-SDK-iOS-VideoBroadcast-SwiftPM

Try it in your code

import AmityLiveVideoBroadcastKit

2. Install AmityVideoPlayer

To use live video player functionalities. Enter the repository URL to search the package, and choose to install AmityVideoPlayer.

https://github.com/AmityCo/Amity-Social-Cloud-SDK-iOS-VideoPlayer-SwiftPM

Try it in your code

import AmityVideoPlayerKit

Using AmitySDK with Objective C Code

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.

Mixed Language 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: Swift Attributes

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: Importing Swift into Objective-C

// Example of a Swift file which contains a class to interact with AmitySDK.

@objc class SDKLoginManager: NSObject {
    
    let client: AmityClient?
    
    @objc init(apiKey: String) {
        self.client = try? AmityClient(apiKey: apiKey)
    }
    
    @objc func login(userId: String, displayName: String, authToken: String, completion: @escaping (Bool, Error?) -> Void) {
        self.client?.login(userId: userId, displayName: displayName, authToken: authToken, completion: completion)
    }
}

#import "ViewController.h"
#import "YourProjectName-Swift.h" // <- This import exposes above Swift file to your Objc project.

@interface ViewController ()

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    // Do any additional setup after loading the view.
}

- (void)testSDKUsage {

    SDKLoginManager *loginManager = [[SDKLoginManager alloc] initWithApiKey:@"my-api-key"];
    [loginManager loginWithUserId:@"user-id" displayName:@"display-name" authToken:@"auth-token" completion:^(BOOL isSuccess, NSError * _Nullable error) {
        
        // Handle login completion here
    }];
}

@end

Introduction

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.

Features

• 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 Products

Installation

Add the SDK to your repository with this code:

npm:

npm install @amityco/ts-sdk --save

yarn:

yarn add @amityco/ts-sdk

Getting Started

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!

Browser Support

• Chrome: 38+

• Firefox: 42+

• Microsoft Edge: 13+

• Safari: 9+

• Opera: 25+

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.

React Native Framework

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.

npm install core-js

Then, import fromEntries in the root of your project.

import 'core-js/features/object/from-entries';

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.

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 Moderation, Roles & Privileges 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 Moderation, Roles & Privileges.

User

*UserV3

Channel

*ChannelV3

Community

*CommunityV3

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 Update Role API or through the SDK.

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.

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

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:

• File Handling

• Image Handling

• Video Handling

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 })

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.

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.

userRepo.searchUserByDisplayName('Test User 1')

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.

const liveUserCollection = UserRepository.queryUsers({
    keyword?: string, 
    filter?: 'all' | 'flagged', 
    sortBy?: 'lastCreated' | 'firstCreated' | 'displayName'
})

// filter if flagCount is > 0
// lastCreated: sort: createdAt desc 
// firstCreated: sort: createdAt asc 
// displayName: sort: alphanumerical asc

liveUserCollection.on(“dataUpdated”, models => {
  models.map(model => console.log(model.userId))
})

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

const myMetadata = { whatever: “i want”, toPass: “is ok” }

const success = await amityClient.updateCurrentUser({
  displayName: "Batman",
  description : "Hero that Gotham needs",
  metadata: myMetadata,
})

Update Current User's Avatar

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

import { useState, useEffect, useMemo } from 'react'

// our image component
const FileImage = ({ fileId }) => {
  const [fileUrl, setFileUrl] = useState()

  useEffect(() => {
    const liveObject = FileRepository.fileInformationForId(fileId)

    liveObject.on('dataUpdated', model => setFileUrl(model.fileUrl))
    liveObject.model && setFileUrl(liveObject.model.fileUrl)

    return () => {
      liveObject.dispose()
    }
  }, [fileId])

  return fileUrl ? <img src={fileUrl} /> : null
}

// our user component
const UserHeader = ({ userId }) => {
  const [user, setUser] = useState({})

  const displayName = useMemo(
    () => user?.displayName ?? user?.userId,
    [user],
  )

  useEffect(() => {
    const liveObject = UserRepository.getUser(userId)

    liveObject.on('dataUpdated', setUser)
    liveObject.model && setUser(liveObject.model)

    return () => {
      liveObject.dispose()
    }
  }, [userId])

  return (
    <div>
     {user.avatarFileId && <FileImage fileId={user.avatarFileId} />}
     {user.avatarCustomUrl && <img src={user.avatarCustomUrl} />}
    </div>
  )
} 

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

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

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.

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:

let userRepository: AmityUserRepository = AmityUserRepository(client: client)
let userToBeFlaggedObject: AmityObject<AmityUser> = userRepository.user(forId: "badUser")

guard let userToBeFlagged: AmityUser = userToBeFlaggedObject.object else { return }

let userFlagger = AmityUserFlagger(client: client, userId: IdOfuserToBeFlagged)

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:

userRepo.flag({ userId: 'user123' })

Unflag a User

To unflag a user, call the following method:

userRepo.unflag({ userId: 'user123' })

Check Flagged By User

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

userRepo.flag({ userId: 'user123' })
    .then(() => {})
    .catch(() => {})

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.