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

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

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

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

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