# SDK di messaggistica per client di Chat IVS: guida per Android
<a name="chat-sdk-android"></a>

L'SDK per Android di Amazon Interactive Video (IVS) Chat Client Messaging fornisce interfacce che consentono di incorporare facilmente l'[API IVS Chat Messaging](https://docs.aws.amazon.com//ivs/latest/chatmsgapireference/welcome.html) su piattaforme che utilizzano Android.

Il pacchetto `com.amazonaws:ivs-chat-messaging` implementa l'interfaccia descritta in questo documento.

**Ultima versione dell'SDK di messaggistica per client di chat IVS per Android:** 1.1.0 ([Note di rilascio](https://docs.aws.amazon.com//ivs/latest/ChatUserGuide/release-notes.html#jan31-23))

**Documentazione di riferimento:** per informazioni sui metodi più importanti disponibili nell'SDK per Android di Amazon IVS Chat Client Messaging consultare la documentazione di riferimento all'indirizzo [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/)

**Codice di esempio:** consultare l'archivio di esempio per Android su GitHub: [https://github.com/aws-samples/amazon-ivs-chat-for-android-demo](https://github.com/aws-samples/amazon-ivs-chat-for-android-demo)

**Requisiti della piattaforma:** per lo sviluppo è necessario Android 5.0 (livello API 21) o versioni successive.

# Guida introduttiva all'SDK di messaggistica per client di chat IVS
<a name="chat-android-getting-started"></a>

Prima di iniziare, acquisire familiarità con [Nozioni di base su Amazon IVS Chat](getting-started-chat.md).

## Aggiungere il pacchetto
<a name="chat-android-add-package"></a>

Aggiungere `com.amazonaws:ivs-chat-messaging` alle proprie dipendenze `build.gradle`:

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

## Aggiungere le regole ProGuard
<a name="chat-android-proguard-rules"></a>

Aggiungere le seguenti voci al file delle regole di R8/ProGuard (`proguard-rules.pro`):

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

## Impostazione del backend
<a name="chat-android-setup-backend"></a>

Questa integrazione richiede endpoint sul server che comunichino con l'[API Amazon IVS](https://docs.aws.amazon.com//ivs/latest/LowLatencyAPIReference/Welcome.html). Utilizzare le [librerie AWS ufficiali](https://aws.amazon.com/developer/tools/) per accedere all'API Amazon IVS dal proprio server. Queste sono accessibili in diverse lingue dai pacchetti pubblici, ad esempio node.js e Java.

Poi creare un endpoint del server che comunichi con [Amazon IVS Chat API](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/Welcome.html) (API di Amazon IVS Chat) creando un token.

## Stabilire una connessione al server
<a name="chat-android-setup-server"></a>

Creare un metodo che richieda `ChatTokenCallback` come parametro e recuperi un token di chat dal proprio backend. Passare tale token al metodo `onSuccess` del callback. In caso di errore, passare l'eccezione al metodo `onError` del callback. Questo è necessario per istanziare la principale entità della `ChatRoom` nella fase successiva.

Di seguito è disponibile un esempio di codice che implementa quanto sopra usando una chiamata di `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)
        }
    })
}
// ...
```

# Utilizzo dell'SDK di messaggistica per client di chat IVS su Android
<a name="chat-android-using-sdk"></a>

Questo documento illustra i passaggi necessari per l'utilizzo dell'SDK di messaggistica per client di chat Amazon IVS su Android.

## Inizializzare un'istanza di chat room
<a name="chat-android-initialize-room"></a>

Creare un'istanza della classe `ChatRoom`. Ciò richiede il passaggio di `regionOrUrl`, che in genere è la Regione AWS in cui è ospitata la chat room, e il `tokenProvider` che è il metodo di recupero dei token creato nella fase precedente.

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

Quindi, creare un oggetto listener che implementerà i gestori per gli eventi relativi alla chat e assegnarlo alla proprietà `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

// ...
```

L'ultimo passaggio dell'inizializzazione di base consiste nel connettersi alla stanza specifica stabilendo una connessione WebSocket. Per farlo, chiamare il metodo `connect()` all'interno dell'istanza della stanza. Consigliamo di farlo nel metodo del ciclo di vita `onResume() ` per assicurarsi che mantenga la connessione se l'app riprende in background.

```
room.connect()
```

L'SDK cercherà di stabilire una connessione a una chat room codificata nel token di chat ricevuto dal server. Se fallisce, tenterà di ricollegarsi tante volte quante quelle specificate nell'istanza della stanza.

## Esecuzione di azioni in una chat room
<a name="chat-android-room-actions"></a>

La classe `ChatRoom` dispone di azioni per inviare ed eliminare messaggi e disconnettere altri utenti. Queste azioni accettano un parametro di callback opzionale che consente di ricevere notifiche di conferma o rifiuto della richiesta.

### Invio di un messaggio
<a name="chat-android-room-actions-send-message"></a>

Per questa richiesta è necessario disporre della funzionalità `SEND_MESSAGE` codificata nel proprio token di chat.

Per attivare una richiesta di invio di messaggi:

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

Per ottenere una conferma/rifiuto della richiesta, fornire un callback come secondo parametro:

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

### Eliminazione di un messaggio
<a name="chat-android-room-actions-delete-message"></a>

Per questa richiesta è necessario disporre della funzionalità DELETE\$1MESSAGE codificata nel proprio token di chat.

Per attivare una richiesta di eliminazione di un messaggio:

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

Per ottenere una conferma/rifiuto della richiesta, fornire un callback come secondo parametro:

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

### Disconnessione di un altro utente
<a name="chat-android-room-actions-disconnect-user"></a>

Per questa richiesta è necessario disporre della funzionalità `DISCONNECT_USER` codificata nel proprio token di chat.

Per disconnettere un altro utente a scopo di moderazione:

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

Per ottenere una conferma/rifiuto della richiesta, fornire un callback come secondo parametro:

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

## Disconnessione da una chat room
<a name="chat-android-disconnect-room"></a>

Per chiudere la connessione alla chat room, chiamare il metodo `disconnect()` sull'istanza della stanza:

```
room.disconnect()
```

Poiché la connessione WebSocket smetterà di funzionare dopo un breve periodo di tempo, quando l'applicazione è in background, si consiglia di connettersi/disconnettersi manualmente durante la transizione da/verso uno stato di background. A tale scopo, abbinare la chiamata `room.connect()` nel metodo del ciclo di vita `onResume()`, su Android `Activity` o `Fragment`, con la chiamata `room.disconnect()` nel metodo del ciclo di vita `onPause()`.