# Installation and Authentication

SDK Installation

For instructions on installing the social.plus SDK, refer to the installation guide for your platform.

* <img src="https://i.ibb.co/w67NSLH/iOSicon.png" alt="image-text" data-size="line"> [**iOS**](/getting-started/installation-and-authentication/install-ios-sdk.md)
* <img src="https://i.ibb.co/BPdDhDd/android-Icon.png" alt="image-text" data-size="line"> [**Android**](/getting-started/installation-and-authentication/install-android-sdk.md)
* <img src="https://i.ibb.co/sgNhg9W/webIcon.png" alt="image-text" data-size="line"> [**JavaScript**](/getting-started/installation-and-authentication/install-js-sdk.md)
* <img src="/files/xAhfKUn0ObSZXihKUbPK" alt="" data-size="line"> [**TypeScript**](/getting-started/installation-and-authentication/install-ts-reactnative-sdk.md)
* <img src="/files/7IUXSGrpm4oiamIoWPfc" alt="" data-size="line"> [**React Native**](/getting-started/installation-and-authentication/install-ts-reactnative-sdk.md#react-native-framework)
* <img src="/files/s0y14vFItfGfUiPZdffu" alt="" data-size="line"> [**Flutter**](/getting-started/installation-and-authentication/install-flutter-sdk.md)
* <img src="/files/ba49bP8a9lPuXWQxAzPK" alt="" data-size="line"> [**Ionic**](/getting-started/installation-and-authentication/install-sdk-ionic.md)

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**](/social-plus-sdk/changelogs-and-versioning.md).

{% tabs %}
{% tab title="iOS" %}

* Xcode Version: 14.3
* Realm Version: 10.28.3
* Minimum Target: iOS 13.0
  {% endtab %}

{% tab title="Android" %}

* 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
  {% endtab %}

{% tab title="JavaScript" %}

* Chrome: 38+
* Firefox: 42+
* Microsoft Edge: 13+
* Safari: 9+
* Opera: 25+

{% hint style="danger" %}
Amity JS SDK probably won't work great in Internet Explorer 11. We generally support the recent versions of major browsers listed above.
{% endhint %}

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](https://nextjs.org/docs/advanced-features/dynamic-import#with-no-ssr).
{% endtab %}

{% tab title="TypeScript" %}

* Chrome: 38+
* Firefox: 42+
* Microsoft Edge: 13+
* Safari: 9+
* Opera: 25+

{% hint style="danger" %}
Amity Ts SDK probably won't work great in Internet Explorer 11. We generally support the recent versions of major browsers listed above.
{% endhint %}

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](https://nextjs.org/docs/advanced-features/dynamic-import#with-no-ssr).
{% endtab %}

{% tab title="Flutter" %}
The minimum deployment target is:

* iOS: **iOS 9.0**
* Android: **Android 4.4 (API Level 19)**
  {% endtab %}

{% tab title="React Native" %}
{% hint style="info" %}
Use our **TypeScript SDK** natively to support your applications built using the **React Native** framework.
{% endhint %}

The instructions for setting up your project will vary slightly, depending on your development environment. Refer [this link](https://reactnative.dev/docs/environment-setup) to set up your project if you have not already done so.
{% endtab %}
{% endtabs %}

## Initialization

Before you can use the SP 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[ social.plus Console](https://portal.amity.co/login) or visit our [social.plus Console](/analytics-and-moderation/console.md) page.

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.

![API key in Security page](/files/0jOVT2OaQT3HgUMXSSr2)

If you have trouble finding this, you can post in our community forum at [**community.social.plus.co**](https://community.amity.co/) so our support team can assist you.

{% tabs %}
{% tab title="iOS" %}

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

{% endtab %}

{% tab title="Android" %}
{% embed url="<https://gist.github.com/amythee/9c0ae63ff30db24c5c0eedf47d0df06e#file-amityinitializer-kt>" %}

{% hint style="warning" %}
On Android, it's important to initialize the SDK within the application's lifecycle only once. Failing to do so could lead to multiple SDK instances, resulting in unexpected issues on your application.
{% endhint %}
{% endtab %}

{% tab title="JavaScript" %}
{% embed url="<https://gist.github.com/amythee/e759b8b3bf8fd4ea0b1e37765229c4e1#file-createclient-js>" %}
{% endtab %}

{% tab title="TypeScript" %}
{% embed url="<https://gist.github.com/amythee/15375921b95ffb298d5bd458b0a77ae1#file-createclient-ts>" %}
{% endtab %}

{% tab title="Flutter" %}
{% embed url="<https://gist.github.com/amythee/7fe9f404dcdc6d16fe9cf9caafd11f6c#file-amityinitializer-dart>" %}
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="iOS" %}

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

{% endtab %}

{% tab title="Android" %}
{% embed url="<https://gist.github.com/amythee/e31dea4bf4d47379e8eb80da51cdffc1#file-amityinitializerwithcustomendpoint-kt>" %}
{% endtab %}

{% tab title="JavaScript" %}
{% embed url="<https://gist.github.com/35cac0d2d62d01dab107d582cec5523a>" %}

{% hint style="info" %}
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.
{% endhint %}

{% embed url="<https://gist.github.com/a522a689e8aed33b0cb595ef17f68305>" %}
{% endtab %}

{% tab title="TypeScript" %}
{% embed url="<https://gist.github.com/amythee/15375921b95ffb298d5bd458b0a77ae1#file-createclient-ts>" %}
{% endtab %}
{% endtabs %}

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

|   **Region**  |  **Endpoint**  |
| :-----------: | :------------: |
|     Europe    | AmityRegion.EU |
|   Singapore   | AmityRegion.SG |
| United States | AmityRegion.US |

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

{% hint style="info" %}
Please note that we only support database encryption for **Android SDK 5.35.0** and v6, beginning from version 6.16.0 onwards.
{% endhint %}

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

{% tabs %}
{% tab title="Android" %}
{% embed url="<https://gist.github.com/5a09da8343440e03c01b7904146ab617>" %}
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="Android (v5)" %}
{% embed url="<https://gist.github.com/82e6b6eef00e5893dc418643ef7f1408>" %}
{% endtab %}
{% endtabs %}

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

An `authToken` is also highly recommended to always be provided, which will be used for secure authentication. For more info on how to configure secure settings and obtain `authToken`, refer to our [Security page](/analytics-and-moderation/console/settings/security.md).

A `sessionHandler` is required for SDK to communicate with the app. For more info please refer to [Session Handler](/social-plus-sdk/core-concepts/session-state.md#session-handler). Do note that the `sessionHandler` is not yet available for Flutter SDK.

{% hint style="warning" %}
It is important to maintain the security of your network and user information. In the production environment, we strongly recommend using an authToken for authentication. While the option to not use an authToken may be available, it should only be applied during the development phase and with caution.
{% endhint %}

{% tabs %}
{% tab title="iOS" %}
{% embed url="<https://gist.github.com/0128828a63c7dc152af7c217ac1f7058>" %}
A login example
{% endembed %}
{% endtab %}

{% tab title="Android" %}
{% embed url="<https://gist.github.com/amythee/b6d53829e0295df991381bdccf13e317#file-amityauthentication-kt>" %}
{% endtab %}

{% tab title="JavaScript" %}
{% embed url="<https://gist.github.com/1154b128523e919c030881c449924283>" %}
Without Auth Token
{% endembed %}

{% embed url="<https://gist.github.com/3b7ae26d1294f65bdd4f5e48089083f1>" %}
With Auth Token
{% endembed %}
{% endtab %}

{% tab title="TypeScript" %}
{% embed url="<https://gist.github.com/amythee/8bdba9f89c8780fae2a49e5c7dad33ee#file-login-ts>" %}
Without Auth Token
{% endembed %}

{% embed url="<https://gist.github.com/amythee/48cf885fe2816e10fd3aa95b8dce8411#file-login-ts>" %}
With Auth Token
{% endembed %}
{% endtab %}

{% tab title="Flutter" %}
{% embed url="<https://gist.github.com/amythee/4a3d37b5e164655802bdd2c646f9d44a>" %}
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="iOS" %}

```swift
client.logout()
```

{% hint style="info" %}
Logout is a synchronous operation. Once the logout method is called, the SDK disconnects from the server and wipes out the user session.
{% endhint %}
{% endtab %}

{% tab title="Android" %}
{% embed url="<https://gist.github.com/amythee/ed843d9b3e6942d5306eb7dba89892a7#file-amitylogout-kt>" %}

{% hint style="info" %}
Logging out is a synchronous operation. Once the `logout()` function is called, the SDK disconnects from the server and wipes out user session.
{% endhint %}
{% endtab %}

{% tab title="JavaScript" %}

```javascript
client.unregisterSession();
```

{% endtab %}

{% tab title="TypeScript" %}
{% embed url="<https://gist.github.com/amythee/ba1ee2695c33f911b2233b83ddcda453#file-disconnectclient-ts>" %}
{% endtab %}

{% tab title="Flutter" %}
{% embed url="<https://gist.github.com/amythee/64432b7ba5b93c3f9e0455cb96c22070>" %}
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="iOS" %}
{% embed url="<https://gist.github.com/amythee/02e01b290e75d64db780581b1861ed53>" %}
{% endtab %}

{% tab title="Android" %}
{% embed url="<https://gist.github.com/d12b2fd7761214948c5a1cc7cc3ccca0>" %}
{% endtab %}

{% tab title="TypeScript" %}
{% embed url="<https://gist.github.com/amythee/48b7de82080a1f69442207c05c827325>" %}
{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="iOS" %}

```swift
client.disconnect()
```

{% endtab %}

{% tab title="Android" %}
{% embed url="<https://gist.github.com/amythee/2f4cf54c0458423528e9f5b97878252f#file-amitydisconnection-kt>" %}
{% endtab %}

{% tab title="Flutter" %}
The functionality isn't currently supported by this SDK.
{% endtab %}
{% endtabs %}

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!

<details>

<summary><strong>Visualized Code Examples</strong></summary>

Yes, you're reading it right! Here you can visually learn how your changes could affect the code, compare your work, and see our development pattern recommendations.

Are you ready? Click [**here**](https://www.amity.co/tutorials) to explore.

</details>

<details>

<summary>All Your UIKit Needs</summary>

**How to Create a Social App with ASC**

Explore a step-by-step tutorial by our engineers to help you build your own Social application. Let's get started in creating an amazing user experience platform.

* <img src="/files/SQB52gqBRSP9zyGfLms6" alt="" data-size="line"> [**iOS**](https://medium.com/@worachote/how-to-create-a-social-app-on-ios-with-amity-social-open-source-uikit-62b7b33ceded)
* <img src="/files/KYLAjvE6EwmpknZZxvmw" alt="" data-size="line">[**Android**](https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Android-OpenSource)

**UIKit Open Source Repositories**

Our [**UIKit**](https://github.com/AmityCo/amity-docs/blob/main/getting-started/installation-and-authentication/broken-reference/README.md) is ready to customize and use, the only task left for you is the integration. We make it as simple as that. Let's dig in!

* <img src="/files/SQB52gqBRSP9zyGfLms6" alt="" data-size="line">[**iOS**](https://github.com/AmityCo/Amity-Social-Cloud-UIKit-iOS-OpenSource)
* <img src="/files/KYLAjvE6EwmpknZZxvmw" alt="" data-size="line">[**Android**](https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Android-OpenSource)
* <img src="/files/mX25pqYwlNOvN2NmVJY0" alt="" data-size="line">[**JavaScript**](https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Web-OpenSource)

</details>

<details>

<summary>Creating Notifications and Webhooks with NodeJs</summary>

Push notifications are proven to be one of the best ways to drive & increase user engagement with the platform and with social.plus. [**Read more**](https://medium.com/@worachote/create-a-webhook-url-to-subscribe-to-amity-real-time-events-with-node-js-7c60c11172fc)...

</details>

<details>

<summary>Building an Android Image Feed Application</summary>

Engage your users through image activity feeds as known from known social networks like Instagram and Pinterest. [**Read more**](https://amityhq.webflow.io/tutorials/how-to-build-an-android-image-feed-application#toc-0)

</details>

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

[**Download our Developer Kits**](https://www.amity.co/developer-kits)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.social.plus/getting-started/installation-and-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.