# SDK per la messaggistica per client di Chat IVS - Tutorial per Android, parte 1: chat room Questo è il primo di un tutorial a due parti. Scoprirai gli elementi essenziali per utilizzare l'SDK di messaggistica di chat Amazon IVS creando un'app Android funzionale e completa con il linguaggio di programmazione [Kotlin](https://kotlinlang.org/). Chiameremo l'app *Chatterbox*. Prima di avviare il modulo, dedica qualche minuto a familiarizzare con i prerequisiti, i concetti chiave alla base dei token di chat e il server di backend necessario per creare le chat room. Questi tutorial sono creati per sviluppatori Android esperti che non hanno mai utilizzato l'SDK per la messaggistica di chat IVS. Dovrai essere a tuo agio con il linguaggio di programmazione Kotlin e con la creazione di interfacce utente sulla piattaforma Android. Questa prima parte del tutorial è suddivisa in diverse sezioni: 1. [Configurazione di un server di autenticazione/autorizzazione locale](#chat-android-rooms-auth-server) 1. [Creazione di un progetto Chatterbox](#chat-android-rooms-chatterbox) 1. [Connessione a una chat room e osservazione degli aggiornamenti della connessione](#chat-android-rooms-connect-state) 1. [Creazione di un provider di token](#chat-android-rooms-token-provider) 1. [Fasi successive](#chat-android-rooms-next-steps) Per la documentazione completa dell'SDK, inizia con l'[SDK di messaggistica per client di chat Amazon IVS](chat-sdk.md) (qui nella *Guida per l'utente di Chat Amazon IVS*) e la [Documentazione di riferimento dell'SDK di messaggistica per client di chat per Android](https://aws.github.io/amazon-ivs-chat-messaging-sdk-android/1.0.0/) su GitHub. ## Prerequisiti + Devi avere dimestichezza con Kotlin e con la creazione di applicazioni sulla piattaforma Android. Se non hai dimestichezza con la creazione di applicazioni per Android, scopri le nozioni di base nella guida [Creazione della prima app](https://developer.android.com/codelabs/basic-android-kotlin-compose-first-app#0) per gli sviluppatori Android. + Leggi e comprendi attentamente [Nozioni di base su Chat Amazon IVS](getting-started-chat.md). + Crea un utente IAM AWS con le capacità `CreateChatToken` e `CreateRoom` definite in una policy IAM esistente. Consultare . [Nozioni di base su Chat Amazon IVS](getting-started-chat.md).) + Assicurati che la chiavi di accesso segrete di questo utente siano archiviata in un file di credenziali AWS. Per istruzioni, consulta la [Guida per l'utente di AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) (in particolare la sezione [Configurazione e impostazioni del file delle credenziali](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)). + Crea una chat room e salva il relativo ARN. Per informazioni, consulta [Nozioni di base su Chat Amazon IVS](getting-started-chat.md). (Se non salvi l'ARN, potrai cercarlo in un secondo momento con la console o l'API di Chat.) ## Configurazione di un server di autenticazione/autorizzazione locale Il tuo server di backend è responsabile sia della creazione di chat room sia della generazione dei token di chat necessari all'SDK di chat IVS per Android per autenticare e autorizzare i client ad accedere alle tue chat room. Consulta [Creazione di un token di chat](getting-started-chat-auth.md) nella *Guida introduttiva ad Amazon IVS Chat*. Come mostrato nel diagramma di flusso, il codice lato server è responsabile della creazione di un token di chat. Ciò significa che l'app deve fornire i propri mezzi per generare un token di chat richiedendone uno dall'applicazione lato server. Utilizziamo il framework [Ktor](https://ktor.io/) per creare un server locale live che gestisca la creazione di token di chat utilizzando l'ambiente AWS locale. A questo punto, ci aspettiamo che le tue credenziali AWS siano configurate correttamente. Per istruzioni dettagliate, consulta la pagina [Configurazione delle credenziali e della regione AWS per lo sviluppo](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-credentials.html). Crea una nuova directory e chiamala `chatterbox` e al suo interno creane un'altra, denominata `auth-server`. La cartella sul server avrà la seguente struttura: ``` - auth-server - src - main - kotlin - com - chatterbox - authserver - Application.kt - resources - application.conf - logback.xml - build.gradle.kts ``` *Nota: puoi copiare/incollare direttamente il codice qui nei file di riferimento.* Successivamente, aggiungiamo tutte le dipendenze e i plugin necessari per il funzionamento del server di autenticazione: **Script Kotlin**: ``` // ./auth-server/build.gradle.kts plugins { application kotlin("jvm") kotlin("plugin.serialization").version("1.7.10") } application { mainClass.set("io.ktor.server.netty.EngineMain") } dependencies { implementation("software.amazon.awssdk:ivschat:2.18.1") implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.7.20") implementation("io.ktor:ktor-server-core:2.1.3") implementation("io.ktor:ktor-server-netty:2.1.3") implementation("io.ktor:ktor-server-content-negotiation:2.1.3") implementation("io.ktor:ktor-serialization-kotlinx-json:2.1.3") implementation("ch.qos.logback:logback-classic:1.4.4") } ``` Ora dobbiamo configurare la funzionalità di registrazione per il server di autenticazione. Per ulteriori informazioni, consulta la sezione [Configurazione del logger](https://ktor.io/docs/logging.html#configure-logger). **XML**: ``` // ./auth-server/src/main/resources/logback.xml %d{YYYY-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n ``` Il server [Ktor](https://ktor.io/docs/welcome.html) richiede delle impostazioni di configurazione, che carica automaticamente dal file `application.*` nella directory `resources`, quindi aggiungiamo anche quelle. Per ulteriori informazioni, consulta la sezione [Configurazione in un file](https://ktor.io/docs/configurations.html#configuration-file). **HOCON**: ``` // ./auth-server/src/main/resources/application.conf ktor { deployment { port = 3000 } application { modules = [ com.chatterbox.authserver.ApplicationKt.main ] } } ``` Infine, implementiamo il server: **Kotlin**: ``` // ./auth-server/src/main/kotlin/com/chatterbox/authserver/Application.kt package com.chatterbox.authserver import io.ktor.http.* import io.ktor.serialization.kotlinx.json.* import io.ktor.server.application.* import io.ktor.server.plugins.contentnegotiation.* import io.ktor.server.request.* import io.ktor.server.response.* import io.ktor.server.routing.* import kotlinx.serialization.Serializable import kotlinx.serialization.json.Json import software.amazon.awssdk.services.ivschat.IvschatClient import software.amazon.awssdk.services.ivschat.model.CreateChatTokenRequest @Serializable data class ChatTokenParams(var userId: String, var roomIdentifier: String) @Serializable data class ChatToken( val token: String, val sessionExpirationTime: String, val tokenExpirationTime: String, ) fun Application.main() { install(ContentNegotiation) { json(Json) } routing { post("/create_chat_token") { val callParameters = call.receive() val request = CreateChatTokenRequest.builder().roomIdentifier(callParameters.roomIdentifier) .userId(callParameters.userId).build() val token = IvschatClient.create() .createChatToken(request) call.respond( ChatToken( token.token(), token.sessionExpirationTime().toString(), token.tokenExpirationTime().toString() ) ) } } } ``` ## Creazione di un progetto Chatterbox Per creare un progetto Android, installa e apri [Android Studio](https://developer.android.com/studio). Segui i passaggi elencati nella [guida Creazione di un progetto](https://developer.android.com/studio/projects/create-project) di Android. + In [Scegli il tuo tipo di progetto](https://developer.android.com/studio/projects/create-project), scegli il modello di progetto **Attività vuota** per la nostra app Chatterbox. + In [Configura il tuo progetto](https://developer.android.com/studio/projects/create-project#configure), scegli i seguenti valori per i campi di configurazione: + **Nome**: My App + **Nome del pacchetto**: com.chatterbox.myapp + **Percorso di salvataggio**: fai riferimento alla cartella `chatterbox` creata nel passaggio precedente + **Lingua**: Kotlin + **Livello minimo API**: API 21: Android 5.0 (Lollipop) Dopo aver specificato correttamente tutti i parametri di configurazione, la struttura dei file all'interno della cartella `chatterbox` dovrebbe essere la seguente: ``` - app - build.gradle ... - gradle - .gitignore - build.gradle - gradle.properties - gradlew - gradlew.bat - local.properties - settings.gradle - auth-server - src - main - kotlin - com - chatterbox - authserver - Application.kt - resources - application.conf - logback.xml - build.gradle.kts ``` Ora che abbiamo un progetto Android funzionante, possiamo aggiungere [com.amazonaws:ivs-chat-messaging](https://mvnrepository.com/artifact/com.amazonaws/ivs-chat-messaging) alle nostre dipendenze `build.gradle`. Per ulteriori informazioni sul toolkit di compilazione [Gradle](https://gradle.org/), consulta la pagina [Configurazione della compilazione](https://developer.android.com/build). **Nota**: nella parte superiore di ogni frammento di codice, è riportato il percorso del file in cui dovresti apportare modifiche al tuo progetto. Il percorso fa riferimento alla cartella del progetto. *Nel codice seguente, sostituisci `` con il numero di versione corrente dell'SDK di chat per Android (ad esempio, 1.0.0)*. **Kotlin**: ``` // ./app/build.gradle plugins { // ... } android { // ... } dependencies { implementation("com.amazonaws:ivs-chat-messaging:") // ... } ``` Dopo aver aggiunto la nuova dipendenza, esegui **Sincronizzazione dei progetti con i file Gradle** in Android Studio per sincronizzare il progetto con la nuova dipendenza. Per ulteriori informazioni, consulta la pagina [Aggiungere dipendenze di compilazione](https://developer.android.com/build/dependencies). Per eseguire comodamente il server di autenticazione che abbiamo creato nella sezione precedente dalla root del progetto, lo includiamo come nuovo modulo in `settings.gradle`. Per ulteriori informazioni, consulta la pagina [Strutturazione e costruzione di componenti software utilizzando Gradle](https://docs.gradle.org/current/userguide/multi_project_builds.html). **Script Kotlin**: ``` // ./settings.gradle // ... rootProject.name = "Chatterbox" include ':app' include ':auth-server' ``` D'ora in avanti, dato che `auth-server` è incluso nel progetto Android, puoi eseguire il server di autenticazione con il seguente comando dalla root del progetto: **Shell (interprete di comandi)**: ``` ./gradlew :auth-server:run ``` ## Connessione a una chat room e osservazione degli aggiornamenti della connessione Per aprire una connessione alla chat room, utilizziamo il [callback del ciclo di vita dell'attività onCreate()](https://developer.android.com/guide/components/activities/activity-lifecycle), che si attiva quando l'attività viene creata per la prima volta. Il [costruttore di ChatRoom](https://aws.github.io/amazon-ivs-chat-messaging-sdk-android/1.0.0/-amazon%20-i-v-s%20-chat%20-messaging%20-s-d-k%20for%20-android/com.amazonaws.ivs.chat.messaging/-chat-room/index.html) ci richiede di fornire `region` e `tokenProvider` per inizializzare una connessione alla chat room. **Nota**: la funzione `fetchChatToken` nel frammento di seguito verrà implementata [nella sezione successiva](#chat-android-rooms-token-provider). **Kotlin**: ``` // ./app/src/main/java/com/chatterbox/myapp/MainActivity.kt package com.chatterbox.myapp // ... import androidx.appcompat.app.AppCompatActivity // ... // AWS region of the room that was created in Getting Started with Amazon IVS Chat const val REGION = "us-west-2" class MainActivity : AppCompatActivity() { private var room: ChatRoom? = null // ... override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) // Create room instance room = ChatRoom(REGION, ::fetchChatToken) } // ... } ``` Visualizzare i cambiamenti nello stato della connessione di una chat room e reagire a essi sono parti essenziali della creazione di un'app di chat come `chatterbox`. Prima di poter iniziare a interagire con la chat room, dobbiamo iscriverci agli eventi sullo stato di connessione della chat room per ricevere aggiornamenti. [ChatRoom](https://aws.github.io/amazon-ivs-chat-messaging-sdk-android/1.0.0/-amazon%20-i-v-s%20-chat%20-messaging%20-s-d-k%20for%20-android/com.amazonaws.ivs.chat.messaging/-chat-room/index.html) si aspetta che colleghiamo un'implementazione dell'[interfaccia ChatRoomListener](https://aws.github.io/amazon-ivs-chat-messaging-sdk-android/1.0.0/-amazon%20-i-v-s%20-chat%20-messaging%20-s-d-k%20for%20-android/com.amazonaws.ivs.chat.messaging/-chat-room/listener.html) per presentare eventi del ciclo di vita. Per ora, le funzioni del listener registreranno solo i messaggi di conferma, quando richiamati: **Kotlin**: ``` // ./app/src/main/java/com/chatterbox/myapp/MainActivity.kt // ... package com.chatterbox.myapp // ... const val TAG = "IVSChat-App" class MainActivity : AppCompatActivity() { // ... private val roomListener = object : ChatRoomListener { override fun onConnecting(room: ChatRoom) { Log.d(TAG, "onConnecting") } override fun onConnected(room: ChatRoom) { Log.d(TAG, "onConnected") } override fun onDisconnected(room: ChatRoom, reason: DisconnectReason) { Log.d(TAG, "onDisconnected $reason") } override fun onMessageReceived(room: ChatRoom, message: ChatMessage) { Log.d(TAG, "onMessageReceived $message") } override fun onMessageDeleted(room: ChatRoom, event: DeleteMessageEvent) { Log.d(TAG, "onMessageDeleted $event") } override fun onEventReceived(room: ChatRoom, event: ChatEvent) { Log.d(TAG, "onEventReceived $event") } override fun onUserDisconnected(room: ChatRoom, event: DisconnectUserEvent) { Log.d(TAG, "onUserDisconnected $event") } } } ``` Ora che abbiamo implementato il `ChatRoomListener`, lo colleghiamo alla nostra istanza di chat room: **Kotlin**: ``` // ./app/src/main/java/com/chatterbox/myapp/MainActivity.kt package com.chatterbox.myapp // ... override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) binding = ActivityMainBinding.inflate(layoutInflater) setContentView(binding.root) // Create room instance room = ChatRoom(REGION, ::fetchChatToken).apply { listener = roomListener } } private val roomListener = object : ChatRoomListener { // ... } ``` Successivamente, dobbiamo fornire la capacità di leggere lo stato della connessione della chat room. Lo manterremo nella [proprietà](https://kotlinlang.org/docs/properties.html) `MainActivity.kt` e lo inizializzeremo allo stato predefinito DISCONNECTED (disconnesso) per le chat room (consulta la sezione `ChatRoom state` nella [Documentazione di riferimento dell'SDK di chat IVS per Android](https://aws.github.io/amazon-ivs-chat-messaging-sdk-android/latest/)). Per poter mantenere aggiornato lo stato locale, dobbiamo implementare una funzione di aggiornamento dello stato, che chiameremo `updateConnectionState`: **Kotlin**: ``` // ./app/src/main/java/com/chatterbox/myapp/MainActivity.kt package com.chatterbox.myapp // ... enum class ConnectionState { CONNECTED, DISCONNECTED, LOADING } class MainActivity : AppCompatActivity() { private var connectionState = ConnectionState.DISCONNECTED // ... private fun updateConnectionState(state: ConnectionState) { connectionState = state when (state) { ConnectionState.CONNECTED -> { Log.d(TAG, "room connected") } ConnectionState.DISCONNECTED -> { Log.d(TAG, "room disconnected") } ConnectionState.LOADING -> { Log.d(TAG, "room loading") } } } } ``` Successivamente, integriamo la funzione di aggiornamento dello stato con la proprietà [ChatRoom.listener](https://aws.github.io/amazon-ivs-chat-messaging-sdk-android/1.0.0/-amazon%20-i-v-s%20-chat%20-messaging%20-s-d-k%20for%20-android/com.amazonaws.ivs.chat.messaging/-chat-room/listener.html): **Kotlin**: ``` // ./app/src/main/java/com/chatterbox/myapp/MainActivity.kt package com.chatterbox.myapp // ... class MainActivity : AppCompatActivity() { // ... private val roomListener = object : ChatRoomListener { override fun onConnecting(room: ChatRoom) { Log.d(TAG, "onConnecting") runOnUiThread { updateConnectionState(ConnectionState.LOADING) } } override fun onConnected(room: ChatRoom) { Log.d(TAG, "onConnected") runOnUiThread { updateConnectionState(ConnectionState.CONNECTED) } } override fun onDisconnected(room: ChatRoom, reason: DisconnectReason) { Log.d(TAG, "[${Thread.currentThread().name}] onDisconnected") runOnUiThread { updateConnectionState(ConnectionState.DISCONNECTED) } } } } ``` Ora che abbiamo la possibilità di salvare, ascoltare e reagire agli aggiornamenti dello stato di [ChatRoom](https://aws.github.io/amazon-ivs-chat-messaging-sdk-android/1.0.0/-amazon%20-i-v-s%20-chat%20-messaging%20-s-d-k%20for%20-android/com.amazonaws.ivs.chat.messaging/-chat-room/index.html), è il momento di inizializzare una connessione: **Kotlin**: ``` // ./app/src/main/java/com/chatterbox/myapp/MainActivity.kt package com.chatterbox.myapp // ... enum class ConnectionState { CONNECTED, DISCONNECTED, LOADING } class MainActivity : AppCompatActivity() { private var connectionState = ConnectionState.DISCONNECTED // ... private fun connect() { try { room?.connect() } catch (ex: Exception) { Log.e(TAG, "Error while calling connect()", ex) } } private val roomListener = object : ChatRoomListener { // ... override fun onConnecting(room: ChatRoom) { Log.d(TAG, "onConnecting") runOnUiThread { updateConnectionState(ConnectionState.LOADING) } } override fun onConnected(room: ChatRoom) { Log.d(TAG, "onConnected") runOnUiThread { updateConnectionState(ConnectionState.CONNECTED) } } // ... } } ``` ## Creazione di un provider di token È il momento di creare una funzione responsabile della creazione e della gestione dei token di chat nell'applicazione. In questo esempio utilizziamo il [client HTTP Retrofit per Android](https://square.github.io/retrofit/). Prima di poter inviare traffico di rete, dobbiamo impostare una configurazione di sicurezza di rete per Android. Per ulteriori informazioni, consulta la pagina [Configurazione della sicurezza di rete](https://developer.android.com/privacy-and-security/security-config). Iniziamo con l'aggiunta delle autorizzazioni di rete al file [App Manifest](https://developer.android.com/guide/topics/manifest/manifest-intro). Nota che sono stati aggiunti il tag `user-permission` e l'attributo `networkSecurityConfig`, che indirizzeranno alla nostra nuova configurazione di sicurezza di rete. *Nel codice seguente, sostituisci `` con il numero di versione corrente dell'SDK di chat per Android (ad esempio, 1.0.0)*. **XML**: ``` // ./app/src/main/AndroidManifest.xml ") // ... implementation("com.squareup.retrofit2:retrofit:2.9.0") } ``` Dichiara i domini `10.0.2.2` e `localhost` come attendibili per iniziare a scambiare messaggi con il nostro backend: **XML**: ``` // ./app/src/main/res/xml/network_security_config.xml 10.0.2.2 localhost ``` Successivamente, dobbiamo aggiungere una nuova dipendenza, insieme al [Gson converter addition](https://github.com/square/retrofit/tree/trunk/retrofit-converters/gson) per l'analisi delle risposte HTTP. *Nel codice seguente, sostituisci `` con il numero di versione corrente dell'SDK di chat per Android (ad esempio, 1.0.0)*. **Script Kotlin**: ``` // ./app/build.gradle dependencies { implementation("com.amazonaws:ivs-chat-messaging:") // ... implementation("com.squareup.retrofit2:retrofit:2.9.0") } ``` Per recuperare un token di chat, dobbiamo effettuare una richiesta HTTP POST dalla nostra app `chatterbox`. Definiamo la richiesta in un'interfaccia da implementare con Retrofit. (Consulta la [documentazione di Retrofit](https://square.github.io/retrofit/). Inoltre, acquisisci familiarità con le specifiche dell'operazione [CreateChatToken](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/API_CreateChatToken.html#API_CreateChatToken_RequestBody).) **Kotlin**: ``` // ./app/src/main/java/com/chatterbox/myapp/network/ApiService.kt package com.chatterbox.myapp.network // ... import androidx.annotation.Keep import com.amazonaws.ivs.chat.messaging.ChatToken import retrofit2.Call import retrofit2.http.Body import retrofit2.http.POST data class CreateTokenParams(var userId: String, var roomIdentifier: String) interface ApiService { @POST("create_chat_token") fun createChatToken(@Body params: CreateTokenParams): Call } ``` Ora che la rete è stata configurata, è il momento di aggiungere una funzione responsabile della creazione e della gestione del token di chat. La aggiungiamo a `MainActivity.kt`, che è stato creato automaticamente quando il progetto è stato [generato](#chat-android-rooms-chatterbox): **Kotlin**: ``` // ./app/src/main/java/com/chatterbox/myapp/MainActivity.kt package com.chatterbox.myapp import androidx.appcompat.app.AppCompatActivity import android.os.Bundle import android.util.Log import com.amazonaws.ivs.chat.messaging.* import com.chatterbox.myapp.network.CreateTokenParams import com.chatterbox.myapp.network.RetrofitFactory import retrofit2.Call import java.io.IOException import retrofit2.Callback import retrofit2.Response // custom tag for logging purposes const val TAG = "IVSChat-App" // any ID to be associated with auth token const val USER_ID = "test user id" // ID of the room the app wants to access. Must be an ARN. See Amazon Resource Names(ARNs) const val ROOM_ID = "arn:aws:..." // AWS region of the room that was created in Getting Started with Amazon IVS Chat const val REGION = "us-west-2" class MainActivity : AppCompatActivity() { private val service = RetrofitFactory.makeRetrofitService() private lateinit var userId: String override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) } private fun fetchChatToken(callback: ChatTokenCallback) { val params = CreateTokenParams(userId, ROOM_ID) service.createChatToken(params).enqueue(object : Callback { override fun onResponse(call: Call, response: Response) { val token = response.body() if (token == null) { Log.e(TAG, "Received empty token response") callback.onFailure(IOException("Empty token response")) return } Log.d(TAG, "Received token response $token") callback.onSuccess(token) } override fun onFailure(call: Call, throwable: Throwable) { Log.e(TAG, "Failed to fetch token", throwable) callback.onFailure(throwable) } }) } } ``` ## Fasi successive Ora che hai stabilito una connessione alla chat room, vai alla parte 2 di questo tutorial per Android, [Messaggi ed eventi](chat-sdk-android-tutorial-messages-events.md)