# SDK de mensajería para clientes del chat de IVS: guía para Android
<a name="chat-sdk-android"></a>

El SDK de mensajería del cliente de chat de Amazon Interactive Video Service (IVS) proporciona interfaces que le permiten incorporar fácilmente nuestras [API de mensajería de chat de IVS](https://docs.aws.amazon.com//ivs/latest/chatmsgapireference/welcome.html) en plataformas que utilizan Android.

El paquete de `com.amazonaws:ivs-chat-messaging` implementa la interfaz descrita en este documento.

**Versión más reciente del SDK de mensajería para clientes de Chat de IVS para Android:** 1.1.0 ([Notas de la versión](https://docs.aws.amazon.com//ivs/latest/ChatUserGuide/release-notes.html#jan31-23))

**Documentación de referencia:** a fin de obtener información sobre los métodos más importantes disponibles en el SDK de mensajería del cliente de chat de Amazon IVS para Android, consulte la documentación de referencia en: [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/)

**Código de muestra:** consulte el repositorio de muestra de Android en GitHub: [https://github.com/aws-samples/amazon-ivs-chat-for-android-demo](https://github.com/aws-samples/amazon-ivs-chat-for-android-demo)

**Requisitos de la plataforma:** se requiere Android 5.0 (API nivel 21) o posterior para el desarrollo.

# Introducción al SDK para Android de mensajería para clientes de Chat de IVS
<a name="chat-android-getting-started"></a>

Antes de comenzar, debe estar familiarizado con [Primeros pasos en el chat de Amazon IVS](getting-started-chat.md).

## Añadir el paquete
<a name="chat-android-add-package"></a>

Añada `com.amazonaws:ivs-chat-messaging` a sus dependencias `build.gradle`:

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

## Añadir las normas de Proguard
<a name="chat-android-proguard-rules"></a>

Añada las siguientes entradas a su archivo de reglas de R8/Proguard (`proguard-rules.pro`):

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

## Configuración del backend
<a name="chat-android-setup-backend"></a>

Esta integración requiere puntos de conexión en su servidor que se comuniquen con la [API de Amazon IVS](https://docs.aws.amazon.com//ivs/latest/LowLatencyAPIReference/Welcome.html). Utilice las [bibliotecas oficiales de AWS](https://aws.amazon.com/developer/tools/) para acceder a la API de Amazon IVS desde su servidor. Se puede acceder a ellas en varios idiomas desde los paquetes públicos, por ejemplo, node.js y Java.

A continuación, cree un punto de conexión de servidor que se comunique con la [API de chat de Amazon IVS](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/Welcome.html) y cree un token.

## Configurar una conexión de servidor
<a name="chat-android-setup-server"></a>

Cree un método que tome `ChatTokenCallback` como parámetro y obtenga un token de chat de su backend. Pase ese token al método `onSuccess` de devolución de llamada. En caso de error, pase la excepción al método `onError` de devolución de llamada. Esto es necesario para instanciar la entidad `ChatRoom` principal en el siguiente paso.

A continuación, puede encontrar un código de ejemplo que implementa lo anterior mediante una llamada `Retrofit`.

```
// ...

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)
        }
    })
}
// ...
```

# Uso del SDK para Android de mensajería para clientes de Chat de IVS
<a name="chat-android-using-sdk"></a>

Este documento explica los pasos necesarios para utilizar el SDK para Android de mensajería para clientes de Chat de Amazon IVS.

## Inicialización de una instancia de sala de chat
<a name="chat-android-initialize-room"></a>

Cree una instancia de la clase `ChatRoom`. Esto requiere pasar `regionOrUrl`, que normalmente es la región de AWS en la que está alojada la sala de chat, y `tokenProvider`, que es el método de obtención de tokens creado en el paso anterior.

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

A continuación, cree un objeto oyente que implemente controladores para los eventos relacionados con el chat y asígnelo a la propiedad `room.listener`:

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

// ...
```

El último paso de la inicialización básica es conectarse a la sala específica mediante el establecimiento de una conexión WebSocket. Para ello, llame al método `connect()` dentro de la instancia de la sala. Le recomendamos que lo haga en el método de ciclo de vida `onResume() ` para asegurarse de que mantiene una conexión si su aplicación se reanuda desde el segundo plano.

```
room.connect()
```

El SDK intentará establecer una conexión con una sala de chat codificada en el token de chat recibido de su servidor. Si falla, intentará volver a conectarse el número de veces especificado en la instancia de la sala.

## Realizar acciones en una sala de chat
<a name="chat-android-room-actions"></a>

La clase `ChatRoom` tiene acciones para enviar y eliminar mensajes y desconectar a otros usuarios. Estas acciones aceptan un parámetro de devolución de llamada opcional que le permite recibir notificaciones de confirmación o rechazo de solicitudes.

### Envío de un mensaje
<a name="chat-android-room-actions-send-message"></a>

Para esta solicitud, debe tener la capacidad `SEND_MESSAGE` codificada en su token de chat.

Para activar una solicitud de envío de mensajes:

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

Para obtener una confirmación/rechazo de la solicitud, proporcione una devolución de llamada como segundo parámetro:

```
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.
   }
})
```

### Eliminar mensajes
<a name="chat-android-room-actions-delete-message"></a>

Para esta solicitud, debe tener la función DELETE\$1MESSAGE (eliminar mensaje) codificada en su token de chat.

Para activar una solicitud de eliminación de mensajes:

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

Para obtener una confirmación/rechazo de la solicitud, proporcione una devolución de llamada como segundo parámetro:

```
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.
   }
})
```

### Desconectar otro usuario
<a name="chat-android-room-actions-disconnect-user"></a>

Para esta solicitud, debe tener la capacidad `DISCONNECT_USER` codificada en tu token de chat.

Para desconectar a otro usuario con fines de moderación:

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

Para obtener la confirmación/rechazo de la solicitud, proporcione una devolución de llamada como segundo parámetro:

```
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.
   }
})
```

## Desconectarse de una sala de chat
<a name="chat-android-disconnect-room"></a>

Para cerrar la conexión con la sala de chat, llame al método `disconnect()` en la instancia de la sala:

```
room.disconnect()
```

Dado que la conexión WebSocket dejará de funcionar al cabo de un breve período de tiempo cuando la aplicación esté en segundo plano, le recomendamos que se conecte o desconecte manualmente al pasar de un estado de segundo plano o a uno en segundo plano. Para ello, haga coincidir la llamada `room.connect()` en el método de ciclo de vida `onResume()`, en Android `Activity` o `Fragment`, con una llamada `room.disconnect()` en el método de ciclo de vida `onPause()`.