# SDK de Mensagens para Clientes do Chat do IVS: Guia para Android
<a name="chat-sdk-android"></a>

O Amazon Interactive Video (IVS) Chat Client Messaging Android SDK fornece interfaces que permitem a você incorporar facilmente nossa [API do IVS Chat Messaging](https://docs.aws.amazon.com//ivs/latest/chatmsgapireference/welcome.html) em plataformas que utilizam Android.

O pacote `com.amazonaws:ivs-chat-messaging` implementa a interface descrita neste documento.

**Versão mais recente do SDK de Mensagens para Clientes do Chat do IVS para Android:** 1.1.0 ([Notas de lançamento](https://docs.aws.amazon.com//ivs/latest/ChatUserGuide/release-notes.html#jan31-23))

**Documentação de referência:** para obter informações sobre os métodos mais importantes disponíveis no Amazon IVS Chat Client Messaging Android SDK, consulte a documentação de referência em [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/).

**Exemplo de código:** consulte o repositório de exemplos para Android no 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 plataforma:** o Android 5.0 (API nível 21) ou superior é necessário para desenvolvimento.

# Introdução ao SDK para Android de mensagens para clientes do Chat do IVS
<a name="chat-android-getting-started"></a>

Antes de começar, você deve se familiarizar com os [Conceitos básicos do Amazon IVS Chat](getting-started-chat.md).

## Adicionar o pacote
<a name="chat-android-add-package"></a>

Adicione `com.amazonaws:ivs-chat-messaging` às dependências de `build.gradle`:

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

## Adicionar regras do Proguard
<a name="chat-android-proguard-rules"></a>

Adicione as seguintes entradas ao arquivo de regras do R8/Proguard (`proguard-rules.pro`):

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

## Configurar seu backend
<a name="chat-android-setup-backend"></a>

Esta integração exige endpoints em seu servidor que conversem com a [API do Amazon IVS](https://docs.aws.amazon.com//ivs/latest/LowLatencyAPIReference/Welcome.html). Use as [bibliotecas oficiais da AWS](https://aws.amazon.com/developer/tools/) para acessar a API do Amazon IVS via servidor. Elas podem ser acessadas em várias linguagens via pacotes públicos, por exemplo, node.js e Java.

Em seguida, crie um endpoint de servidor que se comunique com a [API do Amazon IVS Chat](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/Welcome.html) e crie um token.

## Configurar uma conexão com o servidor
<a name="chat-android-setup-server"></a>

Crie um método que use `ChatTokenCallback` como um parâmetro e busque um token de chat do seu backend. Passe esse token para o método `onSuccess` do retorno de chamada. Em caso de erro, passe a exceção para o método `onError` do retorno de chamada. Isso é necessário para instanciar a entidade na `ChatRoom` principal na próxima etapa.

Um exemplo de código que implementa o código acima usando uma chamada `Retrofit` é mostrado a seguir.

```
// ...

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

# Usar o SDK para Android de mensagens para clientes do Chat do IVS
<a name="chat-android-using-sdk"></a>

Este documento descreve as etapas envolvidas no uso do SDK para Android de mensagens para clientes do Chat do Amazon IVS

## Inicializar uma instância de sala de chat
<a name="chat-android-initialize-room"></a>

Crie uma instância da classe `ChatRoom`. Isso requer passar `regionOrUrl`, que normalmente é a região da AWS na qual sua sala de chat está hospedada, e `tokenProvider`, que é o método de busca de tokens criado na etapa anterior.

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

Em seguida, crie um objeto ouvinte que implementará manipuladores para eventos relacionados ao chat e o atribuirá à propriedade `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

// ...
```

A última etapa da inicialização básica é conectar à sala específica estabelecendo uma conexão WebSocket. Para fazer isso, chame o método `connect()` dentro da instância da sala. Recomendamos fazer isso no método de ciclo de vida `onResume() ` para garantir que ele mantenha uma conexão se a aplicação for retomada em segundo plano.

```
room.connect()
```

O SDK tentará estabelecer uma conexão com uma sala de chat codificada no token de chat recebido do servidor. Se falhar, ele tentará reconectar o número de vezes especificado na instância da sala.

## Executar ações em uma sala de chat
<a name="chat-android-room-actions"></a>

A classe `ChatRoom` tem ações para enviar e excluir mensagens e desconectar outros usuários. Essas ações aceitam um parâmetro opcional de retorno de chamada que permite que você receba notificações de confirmação ou rejeição da solicitação.

### Enviar uma mensagem
<a name="chat-android-room-actions-send-message"></a>

Para esta solicitação, é necessário ter a capacidade `SEND_MESSAGE` codificada em seu token de chat.

Para acionar uma solicitação de envio de mensagem:

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

Para obter uma confirmação/rejeição da solicitação, forneça um retorno de chamada 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.
   }
})
```

### Excluir mensagem
<a name="chat-android-room-actions-delete-message"></a>

Para esta solicitação, é necessário ter a capacidade DELETE\$1MESSAGE codificada em seu token de chat.

Para acionar uma solicitação delete-message:

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

Para obter uma confirmação/rejeição da solicitação, forneça um retorno de chamada 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 outro usuário
<a name="chat-android-room-actions-disconnect-user"></a>

Para esta solicitação, é necessário ter a capacidade `DISCONNECT_USER` codificada em seu token de chat.

Para desconectar outro usuário para fins de moderação:

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

Para obter a confirmação/rejeição da solicitação, forneça um retorno de chamada 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.
   }
})
```

## Desconectar de uma sala de chat
<a name="chat-android-disconnect-room"></a>

Para fechar sua conexão com a sala de chat, chame o método `disconnect()` na instância da sala:

```
room.disconnect()
```

Como a conexão WebSocket deixará de funcionar após um curto período quando a aplicação estiver em segundo plano, recomendamos se conectar/desconectar manualmente ao fazer a transição de/para um estado de segundo plano. Para fazer isso, combine a chamada `room.connect()` no método de ciclo de vida `onResume()`, em `Activity` ou `Fragment` do Android, com uma chamada `room.disconnect()` no método de ciclo de vida `onPause()`.