# IVS Chat Client Messaging SDK: Android Guide
<a name="chat-sdk-android"></a>

The Amazon Interactive Video (IVS) Chat Client Messaging Android SDK provides interfaces that allow you to easily incorporate our [IVS Chat Messaging API](https://docs.aws.amazon.com//ivs/latest/chatmsgapireference/welcome.html) on platforms using Android.

The `com.amazonaws:ivs-chat-messaging` package implements the interface described in this document.

**Latest version of IVS Chat Client Messaging Android SDK:** 1.1.0 ([Release Notes](https://docs.aws.amazon.com//ivs/latest/ChatUserGuide/release-notes.html#jan31-23))

**Reference documentation:** For information on the most important methods available in the Amazon IVS Chat Client Messaging Android SDK, see the reference documentation at: [https://aws.github.io/amazon-ivs-chat-messaging-sdk-android/1.1.0/](https://aws.github.io/amazon-ivs-chat-messaging-sdk-android/1.1.0/)

**Sample code:** See the Android sample repository on GitHub: [https://github.com/aws-samples/amazon-ivs-chat-for-android-demo](https://github.com/aws-samples/amazon-ivs-chat-for-android-demo)

**Platform requirements:** Android 5.0 (API level 21) or greater is required for development.

# Getting Started with the IVS Chat Client Messaging Android SDK
<a name="chat-android-getting-started"></a>

Before starting, you should be familiar with [Getting Started with Amazon IVS Chat](getting-started-chat.md).

## Add the Package
<a name="chat-android-add-package"></a>

Add `com.amazonaws:ivs-chat-messaging` to your `build.gradle` dependencies:

```
dependencies {
   implementation 'com.amazonaws:ivs-chat-messaging'
}
```

## Add Proguard Rules
<a name="chat-android-proguard-rules"></a>

Add the following entries to your R8/Proguard rules file (`proguard-rules.pro`):

```
-keep public class com.amazonaws.ivs.chat.messaging.** { *; }
-keep public interface com.amazonaws.ivs.chat.messaging.** { *; }
```

## Set Up Your Backend
<a name="chat-android-setup-backend"></a>

This integration requires endpoints on your server that talk to the [Amazon IVS API](https://docs.aws.amazon.com//ivs/latest/LowLatencyAPIReference/Welcome.html). Use the [official AWS libraries](https://aws.amazon.com/developer/tools/) for access to the Amazon IVS API from your server. These are accessible within several languages from the public packages; e.g., node.js and Java.

Next, create a server endpoint that talks to the [Amazon IVS Chat API](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/Welcome.html) and creates a token.

## Set Up a Server Connection
<a name="chat-android-setup-server"></a>

Create a method that takes `ChatTokenCallback` as a param and fetches a chat token from your backend. Pass that token to the `onSuccess` method of the callback. In case of error, pass the exception to the `onError` method of the callback. This is needed to instantiate the main `ChatRoom` entity in the next step.

Below you can find sample code that implements the above using a `Retrofit` call.

```
// ...

private fun fetchChatToken(callback: ChatTokenCallback) {
    apiService.createChatToken(userId, roomId).enqueue(object : Callback<ChatToken> {
        override fun onResponse(call: Call<ExampleResponse>, response: Response<ExampleResponse>) {
            val body = response.body()
            val token = ChatToken(
                body.token,
                body.sessionExpirationTime,
                body.tokenExpirationTime
            )
            callback.onSuccess(token)
        }

        override fun onFailure(call: Call<ChatToken>, throwable: Throwable) {
            callback.onError(throwable)
        }
    })
}
// ...
```

# Using the IVS Chat Client Messaging Android SDK
<a name="chat-android-using-sdk"></a>

This document takes you through the steps involved in using the Amazon IVS chat client messaging Android SDK.

## Initialize a Chat Room Instance
<a name="chat-android-initialize-room"></a>

Create an instance of the `ChatRoom` class. This requires passing `regionOrUrl`, which typically is the AWS region in which your chat room is hosted, and `tokenProvider` which is the token-fetching method created in the previous step.

```
val room = ChatRoom(
    regionOrUrl = "us-west-2",
    tokenProvider = ::fetchChatToken
)
```

Next, create a listener object that will implement handlers for chat related events, and assign it to the `room.listener` property:

```
private val roomListener = object : ChatRoomListener {
    override fun onConnecting(room: ChatRoom) {
      // Called when room is establishing the initial connection or reestablishing connection after socket failure/token expiration/etc
    }

    override fun onConnected(room: ChatRoom) {
        // Called when connection has been established
    }

    override fun onDisconnected(room: ChatRoom, reason: DisconnectReason) {
        // Called when a room has been disconnected
    }

    override fun onMessageReceived(room: ChatRoom, message: ChatMessage) {
        // Called when chat message has been received
    }

    override fun onEventReceived(room: ChatRoom, event: ChatEvent) {
        // Called when chat event has been received
    }

    override fun onDeleteMessage(room: ChatRoom, event: DeleteMessageEvent) {
       // Called when DELETE_MESSAGE event has been received
    }
}

val room = ChatRoom(
    region = "us-west-2",
    tokenProvider = ::fetchChatToken
)

room.listener = roomListener // <- add this line

// ...
```

The last step of basic initialization is connecting to the specific room by establishing a WebSocket connection. To do this, call the `connect()` method within the room instance. We recommend doing so in the `onResume() `lifecycle method to make sure it keeps a connection if your app resumes from the background.

```
room.connect()
```

The SDK will try to establish a connection to a chat room encoded in the chat token received from your server. If it fails, it will try to reconnect the number of times specified in the room instance.

## Perform Actions in a Chat Room
<a name="chat-android-room-actions"></a>

The `ChatRoom` class has actions for sending and deleting messages and disconnecting other users. These actions accept an optional callback parameter that allows you to get request confirmation or rejection notifications.

### Sending a Message
<a name="chat-android-room-actions-send-message"></a>

For this request, you must have the `SEND_MESSAGE` capability encoded in your chat token.

To trigger a send-message request:

```
val request = SendMessageRequest("Test Echo")
room.sendMessage(request)
```

To get a confirmation/rejection of the request, provide a callback as a second parameter:

```
room.sendMessage(request, object : SendMessageCallback {
   override fun onConfirmed(request: SendMessageRequest, response: ChatMessage) {
      // Message was successfully sent to the chat room.
   }
   override fun onRejected(request: SendMessageRequest, error: ChatError) {
      // Send-message request was rejected. Inspect the `error` parameter for details.
   }
})
```

### Deleting a Message
<a name="chat-android-room-actions-delete-message"></a>

For this request, you must have the DELETE\$1MESSAGE capability encoded in your chat token.

To trigger a delete-message request:

```
val request = DeleteMessageRequest(messageId, "Some delete reason")
room.deleteMessage(request)
```

To get a confirmation/rejection of the request, provide a callback as a second parameter:

```
room.deleteMessage(request, object : DeleteMessageCallback {
   override fun onConfirmed(request: DeleteMessageRequest, response: DeleteMessageEvent) {
      // Message was successfully deleted from the chat room.
   }
   override fun onRejected(request: DeleteMessageRequest, error: ChatError) {
      // Delete-message request was rejected. Inspect the `error` parameter for details.
   }
})
```

### Disconnecting Another User
<a name="chat-android-room-actions-disconnect-user"></a>

For this request, you must have the `DISCONNECT_USER` capability encoded in your chat token.

To disconnect another user for moderation purposes:

```
val request = DisconnectUserRequest(userId, "Reason for disconnecting user")
room.disconnectUser(request)
```

To get confirmation/rejection of the request, provide a callback as a second parameter:

```
room.disconnectUser(request, object : DisconnectUserCallback {
   override fun onConfirmed(request: SendMessageRequest, response: ChatMessage) {
      // User was disconnected from the chat room.
   }
   override fun onRejected(request: SendMessageRequest, error: ChatError) {
      // Disconnect-user request was rejected. Inspect the `error` parameter for details.
   }
})
```

## Disconnect from a Chat Room
<a name="chat-android-disconnect-room"></a>

To close your connection to the chat room, call the `disconnect()` method on the room instance:

```
room.disconnect()
```

Because the WebSocket connection will stop working after a short time when the application is in a background state, we recommend that you manually connect/disconnect when transitioning from/to a background state. To do so, match the `room.connect()` call in the `onResume()` lifecycle method, on Android `Activity` or `Fragment`, with a `room.disconnect()` call in the `onPause()` lifecycle method.