Introduction

Social+ 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 Social+ 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

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

Social Plus SDK is available on both Jitpack and MavenCentral (v6.43.0 onwards). Users must choose one of these repositories to avoid conflicting files.

Maven Central

Add the Maven Central repository to your project-level build.gradle at the end of repositories:

dependencyResolutionManagement {
  repositories {
    ...
     mavenCentral()
  }
}

allprojects {
  repositories {
    ...
    mavenCentral()
  }
}

implementation 'co.amity.android:amity-sdk:x.y.z'

implementation("co.amity.android:amity-sdk:x.y.z")

Jitpack

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

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

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

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

}

Manual Installation

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

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

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

Cocoapod & Carthage:

We have dropped support for Cocoapod & Carthage for AmitySDK. If you want to distribute AmitySDK through cocoapod & carthage, you can use the xcframeworks that we distribute through Swift Package Manager (SPM).

Additional Steps for Amity Video

To use live video broadcast:

• Import AmityLiveVideoBroadcastKit.xcframework to your project.

To use a live video player:

For version 6.0.0 - 6.7.0

• Import AmityVideoPlayerKit.xcframework to your project

• Switch each framework to Embed & Sign, except MobileVLCKit to Do Not Embed.

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

For version 6.8.0 and above

• Import AmityVideoPlayerKit.xcframework 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.

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:

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

SDK Installation

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

Initialization

After logging into the Console:

1. Click Settings to expand the menu.

2. Select Security.

3. On the Security page, you can find the API key in the Keys section.

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

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

To use any SP SDK feature, you must first log in to 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 event messages belonging to the tied user.

An optional displayName can be provided, which will be used in standard push notifications (related to the user's actions, such as when a new message is sent).

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();

Secure Logout

For an extra layer of security, the SDK provides secureLogout(), an asynchronous function, which ensures accessToken revocation prior to performing logout(). Should the SDK fail to revoke the accessToken, the SDK will not proceed to logout and will throw an exception to notify the failure.

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 its Internet connection.

• Users close the app in the background, and 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 which 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. Social Plus'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 the server again.

Tutorials

Now that you've finished getting your SP project set up, here are some step-by-step articles if you need a hand in building your app!

Social Plus Developer Kits

Check out our Social Plus UI Kits and Template Apps.

• UI Kits Our UI Kits include user interfaces to enable fast integration of standard Social Plus Chat and Social Plus Social features into new or existing applications.

• Template Apps Our Template Apps are ready-made template applications to kickstart your own Social Plus project.

With real-life use cases, we guide you through ways you can get started with building stellar applications for yourself your clients, and their users.

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://apix.sg.amity.co/api/v3/communities?filter=member&sortBy=lastCreated&options%5Blimit%5D=100' \
--header 'accept: application/json' \
--header 'Authorization: Bearer xxx'

curl --location 'https://api.sg.amity.co/api/v3/authentication/token?userId=Amity'
--header 'accept: application/json'
--header 'x-server-key: xxx'

curl --location 'https://apix.sg.amity.co/api/v4/sessions' \
--header 'accept: application/json' \
--header 'x-api-key: xxx' \
--header 'Content-Type: application/json' \
--data '{
  "userId": "Amity",
  "deviceId": "test",
  "authToken": "xxx"
}'

curl --location 'https://api.sg.amity.co/api/v3/authentication/token?userId=Amity'
--header 'accept: application/json'
--header 'x-server-key: xxx'

curl --location --request PUT ‘https://api.eu.amity.co/api/v2/users’
–header ‘Content-Type: application/json’
–header ‘Authorization: Bearer xxx’
–data ‘{
“userId”: “Test”,
“metadata”: {
    “testmeta”: “usermetaUpdate”
    }
}’

curl --location --globoff 'https://apix.sg.amity.co/api/v3/communities/65e18cd9e66dfc75f3cd8f7d/users?memberships[]=member&roles[]=moderator&options%5Blimit%5D=10' \
--header 'accept: application/json' \
--header 'Authorization: Bearer xxx'

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"
  ]
}'

import React, { useEffect, useState } from 'react';

const RecentChat = ({ onChannelSelect, onAddNewChannelClick, selectedChannelId }) => {
  // This line retrieves the list of channels, along with some additional information.
  const [channels, hasMore, loadMore] = useChannelsList();

  // This line initializes a state variable to keep track of whether the component has been initialized.
  const [hasInitialized, setHasInitialized] = useState(false);

  // This useEffect function will run when the component is first mounted and whenever 'channels' or 'hasInitialized' changes.
  useEffect(() => {
    // Check if the component hasn't been initialized and there are channels available.
    if (!hasInitialized && channels?.length) {
      // If the conditions are met, select the first channel in the list.
      onChannelSelect(channels[0]);
      
      // Mark the component as initialized to prevent this from happening again.
      setHasInitialized(true);
    }
  }, [channels, hasInitialized]);

  // The rest of your component code goes here...

  return (
    // JSX code for your component...
  );
};

curl --location --globoff 'https://api.sg.amity.co/api/v4/posts?targetId=65e18cd9e66dfc75f3cd8f7d&targetType=community&sortBy=lastCreated&tags[]=tag1&tags[]=tag2' \
--header 'accept: application/json' \
--header 'Authorization: Bearer xxx'

SDKs

Poll

Console

Portal

Alternative solutions for unsupported features

Beta features

"hashtagList":[
     "#tags1",
     "#tags2",
     "#tags3"
   ]

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'

Dashboard

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 a Capacitor to your app

In the root of your application, install Capacitor:

npm install @capacitor/core --save

Adding support for the 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

Installation

Add the SDK to your repository by adding amity_sdk dependency

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)

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.

Browser Support

• Chrome: 38+

• Firefox: 42+

• Microsoft Edge: 13+

• Safari: 9+

• Opera: 25+

React Native Framework

Use our TypeScript SDK natively to support your applications built using the React Native framework.

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';

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

Installation

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

Browser Support

• Chrome: 38+

• Firefox: 42+

• Microsoft Edge: 13+

• Safari: 9+

• Opera: 25+

UIKit v4: Transition from Beta to Production

17 March 2025

• Out of Beta: After extensive testing and feedback, UIKit v4 has matured from its beta phase and is now officially released.

• Feature-Complete & Stable: We’ve incorporated crucial features, addressed known bugs, and improved performance, ensuring a stable release ready for production environments.

• Upgrade to SDK v7: UIKit v4 now leverages SDK v7 (replacing SDK v6), providing enhanced capabilities, improved security, and better long-term support.

• Replacing UIKit v3: UIKit v3 is now in the maintenance phase. Support critical bug fixes for the next 6 months.

Upgrade Announcement: Transitioning from Version 6.x to 7.x

14 March 2025

• Version 6.x introduced updated function names for consistency across all SDK platforms and deprecated older, misaligned versions. These deprecated functions have now been fully removed in Version 7.x.

• We will only provide critical issue fixes for Version 6.x during the transition period. Any necessary hotfixes will be applied to historical versions as needed.

• Version 7.x and future releases (e.g., v7.1, v7.2) will continue to receive new features and improvements. If you have already migrated to the updated function names in v6.x, the impact should be minimal, as the package structure and naming conventions remain consistent.

• Version 6.x will continue receiving critical fixes for six months, after which it will be officially discontinued and no longer supported.

You can find more information about these changes in the respective changes for each platform, which you can access using the links below.

Behavioral Change Announcement

1 August 2023

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

1 August 2023

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?

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

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

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, Social Plus 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 the Social Plus iOS SDK version prior to v4.2

• From April onwards, you will NOT be able to submit an updated version to App Store with the Social Plus 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 Social Plus 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?

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.

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 sorting option will be specified by default if it isn't specified.

With the displayName sorting option, users are sorted alphabetically by their display names using ICU collation for the English locale. This means that special characters such as Ä are treated as variants of A. For example, a sorted list might appear as: adam, Älex, Alice, Arthur, charlie, Kristen.

When providing a search keyword, the API performs an exact-match lookup for special characters.

• For instance, if you search for "Äli", only users whose display name contains the "Äli" characters (e.g., "Älise") will be returned.

• Conversely, searching for "Alice" will not return "Älice".

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.

With the displayName sorting option, users are sorted alphabetically by their display names using ICU collation for the English locale. This means that special characters such as Ä are treated as variants of A. For example, a sorted list might appear as: adam, Älex, Alice, Arthur, charlie, Kristen.

Identity

Social Plus 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, Social Plus 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 Social Plus cannot provide user management functionalities like a 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.

Ban User

You can ban a user globally. When users are globally banned, they can no longer access Social Plus's network and will be forcibly removed from all their existing channels.

In the Social Plus 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.

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, and 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 Accounts".

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

The 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

The API response will be different based on the request and records match. The request may have a successful response, or it may have a bad request error, and it may respond as a User not found. The responses to API calls are mentioned below.

Success

Bad Request error

User Not Found error

Flag / Unflag User feature is an essential tool for maintaining a safe and engaging chat community. With Social Plus, 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 Social Plus 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:

AmityClient class provides a method hasPermission which allows you to check if the current logged-in user has permission to do stuff in a given channel.

We determine a user's moderation capabilities based on their current role. Social Plus 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

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.

In Social Plus 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.