Getting Started
This section outlines how you can set-up your ASC project and contains all the tutorial links you'll need to get going .

Compatibility

We are always working to enhance our existing SDKs. As a result, the minimum compatibility may vary for our previous version releases. Below is the compatibility list for our latest SDK releases. For a complete compatibility history of any given SDK version, please refer to the corresponding Changelogs.
iOS
Android
JavaScript
TypeScript
React Native
  • Xcode Version: 13.4
  • Realm Version: 10.21.1
  • Minimum Target: iOS 12.0
  • OKHTTP3 - 4.9.0
  • Retrofit - 2.50
  • Android Paging Data Library - 3.0.1
  • Room - 2.4.0-alpha04
  • RxJava2 - 2.3.10
  • Gson - 2.8.10
  • Kotlin-std-lib - 1.5.10
  • HiveMQ mqtt client - 1.2.2

Transitive Library Dependencies

  • androidx.annotation:annotation: 1.2.0
  • androidx.core:core-ktx: 1.3.2
  • androidx.paging:paging-runtime: 3.0.1
  • androidx.paging:paging-rxjava2: 3.0.1
  • androidx.lifecycle:lifecycle-livedata: 2.2.0
  • androidx.lifecycle:lifecycle-reactivestreams:2.1.0-rc01
  • androidx.multidex:multidex:2.0.1
  • androidx.room:room-runtime:2.3.0
  • androidx.room:room-rxjava2:2.3.0
  • com.f2prateek.rx.preferences2:rx-preferences:2.0.1
  • com.github.davidmoten:rxjava2-extras:0.1.24
  • com.google.code.gson:gson: 2.8.7
  • com.google.guava:guava:30.1.1-android
  • com.jakewharton.rxrelay2:rxrelay:2.0.0
  • com.jakewharton.rx2:replaying-share:2.0.1
  • com.jakewharton.timber:timber:4.7.1
  • com.squareup.okhttp3:okhttp: 4.9.0
  • com.squareup.okhttp3:logging-interceptor:3.10.0
  • com.squareup.retrofit2:retrofit: 2.5.0
  • com.squareup.retrofit2:adapter-rxjava2: 2.5.0
  • com.squareup.retrofit2:converter-gson: 2.5.0
  • io.arrow-kt:arrow-core:0.11.0
  • io.arrow-kt:arrow-syntax:0.11.0
  • io.reactivex.rxjava2:rxandroid: 2.1.1
  • io.reactivex.rxjava2:rxjava: 2.2.19
  • io.socket:socket.io-client:1.0.0
  • joda-time:joda-time:2.10.6
  • org.apache.commons:commons-lang3:3.7
  • org.jetbrains.kotlin:kotlin-stdlib: 1.5.10
  • org.jetbrains.kotlin:kotlin-android-extensions-runtime: 1.5.10
  • org.jetbrains.kotlinx:kotlinx-coroutines-android:1.4.3
  • Chrome: 38+
  • Firefox: 42+
  • Microsoft Edge: 13+
  • Safari: 9+
  • Opera: 25+
Amity Js SDK probably won't work great in Internet Explorer 11. We generally support the recent versions of major browsers listed above.
Since Amity Js SDK uses local cache for performance and user experience reason, server side rendering is not supported. To use Amity Js SDK with NextJS, it must be imported using Dynamic Import with SSR disabled.
  • Chrome: 38+
  • Firefox: 42+
  • Microsoft Edge: 13+
  • Safari: 9+
  • Opera: 25+
Amity Ts SDK probably won't work great in Internet Explorer 11. We generally support the recent versions of major browsers listed above.
Since Amity Ts SDK uses local cache for performance and user experience reason, server side rendering is not supported. To use Amity Ts SDK with NextJS, it must be imported using Dynamic Import with SSR disabled.
Use our TypeScript SDK natively to support your applications built using the React Native framework.
The instructions in setting up your project are a bit different, depending on your development environment. Refer to this link to set up your project if you haven't done so already.

SDK Installation

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

Initialization

Before using the ASC SDK, you need to create a new SDK instance with your API key. Please find your account API key in Amity Social Cloud Console.
After logging in Console:
  1. 1.
    Click Settings to expand the menu.
  2. 2.
    Select Security.
  3. 3.
    In the Security page, you can find the API key in the Keys section.
API key in Security page
If you have trouble finding this, you can post in our community forum at community.amity.co so our support team can assist you.
iOS
Android
JavaScript
TypeScript
let client = try! AmityClient(apiKey: "api-key", region: .global)
import AmityClient from '@amityco/js-sdk';
const client = new AmityClient({ apiKey: 'YOUR_API_KEY' });

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.
iOS
Android
JavaScript
TypeScript
let endpoint = AmityEndpoint(httpUrl: "http-endpoint",
rpcUrl: "rpc-endpoint",
mqttHost: "mqtt-host")
let client = try! AmityClient(apiKey: "api-key", endpoint: endpoint)
import AmityClient, { ApiRegion } from '@amityco/js-sdk'
const client = new AmityClient({ apiKey: 'YOUR_API_KEY',
apiRegion: ApiEndpoint.US });
Note: From Js SDK v5.10.0, we introduced Real time events which requires a new endpoint (mqttEndpoint) along with the existing apiEndpoint. So instead of passing multiple parameters for both, we can pass a single apiRegion parameter. The corresponding endpoints will then be created within the SDK using the passed region. This will be the recommended approach to create a new ASClient for different regions.
We currently support multi-data center capabilities for the following regions:
Region
Endpoint
Europe
AmityRegion.EU
Singapore
AmityRegion.SG
United States
AmityRegion.US

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 can also be provided, which will be used for authentication. Should you choose to use insecure settings on your network, this parameter can be ignored.
For more info on how to configure secure settings and obtain authToken, refer to our Security page.
iOS
Android
JavaScript
TypeScript
// Without Auth Token
client.login(userId: "User Id", displayName: "Display Name", authToken: nil)
// With Auth Token
client.login(userId: "User Id", displayName: "Display Name", authToken: "Auth Token")
//Without auth token
const client = new AmityClient({ apiKey })
client.registerSession({ userId: 'user1234', displayName: 'Bob Newton' });
//With auth token
const ascClient = new AmityClient({ apiKey })
ascClient.registerSession({ userId, authToken })
Without Auth Token
With Auth Token
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.
iOS
Android
JavaScript
TypeScript
client.logout()
Logout is a synchronous operation. Once the logout method is called, the SDK disconnects from the server and wipes out user session.
Logging out is a synchronous operation. Once the logout() function is called, the SDK disconnects from the server and wipes out user session.
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.
iOS
Android
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.

Connection Status

If you have any logic or UI around the WebSocket connection status, you can observe the connection status property on the Amity Client instance.
The SDK automatically manages the WebSocket connection and queues up any requests in cases of bad connection. There should be little need to attach additional logic to this status.
This status is exposed so you can check the WebSocket connection state and determine if your tasks are performed in real-time.
iOS
Android
JavaScript
TypeScript
let client = AmityClient(...)
client.delegate = self
extension ViewController: AmityClientDelegate {
func didChangeConnectionStatus(status: AmityConnectionStatus) {
// Observe connection status change here
}
}
The connection status property supports KVO notifications. So alternatively you can also use NSObject's observe methods to be notified whenever this status changes.
var token: NSKeyValueObservation?
func observeSDKConnectionState() {
token = client.observe(\.fconnectionStatus) { client, change in
switch client.connectionStatus {
case .notConnected:
print("notConnected")
case .connecting:
print("connecting")
case .connected:
print("connected")
case .disconnected:
print("disconnected")
@unknown default:
print("not used")
}
}
}
// listen to connectionStatus event
client.on('connectionStatusChanged', ({ oldValue, newValue }) => {
// handle changes
});
// stop listening to connectionStatus event once you are finished
client.removeAllListeners('connectionStatusChanged');
You can only connect to the WebSocket after a successful user authentication.

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!
Visualized Code Examples
All Your UIKit Needs
Creating Notifications and Webhooks with NodeJs
Building an Android Image Feed Application

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.