Guida introduttiva: Aggiungere chat con la libreria dell'interfaccia utente

  • Articolo

Introduzione alla libreria dell'interfaccia utente di Servizi di comunicazione di Azure per integrare rapidamente le esperienze di comunicazione nelle applicazioni. Questo argomento di avvio rapido illustra come integrare i compositi della chat della libreria dell'interfaccia utente in un'applicazione e configurare l'esperienza per gli utenti dell'app.

La libreria dell'interfaccia utente di Servizi di comunicazione esegue il rendering di un'esperienza di chat completa direttamente nell'applicazione. Si occupa della connessione a Servizi di comunicazione di Azure servizi di chat e aggiorna automaticamente la presenza del partecipante. Gli sviluppatori devono preoccuparsi della posizione dell'esperienza utente dell'app in cui si vuole avviare l'esperienza di chat e creare solo le risorse Servizi di comunicazione di Azure in base alle esigenze.

Nota

Per la documentazione dettagliata e gli argomenti di avvio rapido sulla libreria dell'interfaccia utente Web, visitare il libro della raccolta dell'interfaccia utente Web.

Prerequisiti

È possibile accedere alle guide introduttive seguenti

Importante

Questa funzionalità di Servizi di comunicazione di Azure è attualmente in anteprima.

Le API di anteprima e gli SDK vengono forniti senza un contratto di servizio. È consigliabile non usarli per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate.

Per altre informazioni, vedere Condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure.

Ottenere l'applicazione Android di esempio per questa guida introduttiva nell'applicazione open source Servizi di comunicazione di Azure libreria dell'interfaccia utente per Android.

Prerequisiti

Configurare il progetto

Completare le sezioni seguenti per configurare il progetto di avvio rapido.

Creare un nuovo progetto Android

In Android Studio creare un nuovo progetto:

  1. Scegliere Nuovo>progetto dal menu File.

  2. In Nuovo progetto selezionare il modello di progetto Attività vuota.

    Screenshot that shows the New Project dialog in Android Studio with Empty Activity selected.

  3. Selezionare Avanti.

  4. In Attività vuota assegnare al progetto il nome UILibraryQuickStart. Per linguaggio selezionare Java/Kotlin. Per l'SDK minimo selezionare API 23: Android 6.0 (Marshmallow) o versione successiva.

  5. Selezionare Fine.

    Screenshot that shows new project options and the Finish button selected.

Installare i pacchetti

Completare le sezioni seguenti per installare i pacchetti dell'applicazione necessari.

Aggiungere una dipendenza

Nel file UILibraryQuickStart/app/build.gradle a livello di app aggiungere la dipendenza seguente:

dependencies {
    ...
    implementation 'com.azure.android:azure-communication-ui-chat:+'
    ...
}

Aggiungere archivi Maven

Il repository di pacchetti di Azure è necessario per integrare la libreria:

Per aggiungere il repository:

  1. Negli script Gradle del progetto assicurarsi che vengano aggiunti i repository seguenti. Per Android Studio (2020.*), repositories è in , in settings.gradledependencyResolutionManagement(Gradle version 6.8 or greater). Per le versioni precedenti di Android Studio (4.*), repositories si trova a livello build.gradleallprojects{}di progetto in .

    // dependencyResolutionManagement
repositories {
    ...
    maven {
        url "https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1"
    }
    ...
}

  2. Sincronizzare il progetto con i file Gradle. Per sincronizzare il progetto, scegliere Sincronizza progetto con file gradle dal menu File.

Aggiungere un pulsante a activity_main.xml

Nel file di layout app/src/main/res/layout/activity_main.xml aggiungere il codice seguente per creare un pulsante per avviare il composito:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <Button
        android:id="@+id/startButton"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Launch"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

Inizializzare il composito

Per inizializzare il composito:

  1. Vai a MainActivity.

  2. Aggiungere il codice seguente per inizializzare i componenti compositi per la chiamata. Sostituire i valori stringa per le proprietà (kotlin) o le funzioni (java) per endpoint, acsIdentitydisplayName, accessToken e ThreadId. Sostituire endpoint con l'URL della risorsa come specificato da Servizi di comunicazione di Azure. Sostituire acsIdentity e accessToken con i valori forniti da Servizi di comunicazione di Azure quando è stato creato il token di accesso e usare un displayName pertinente. Sostituire ThreadId con il valore restituito al momento della creazione del thread. Ricordarsi di aggiungere l'utente al thread tramite la chiamata api REST o il client az command line interface client prima di provare a eseguire l'esempio di avvio rapido o al client verrà negato l'accesso per l'aggiunta al thread.

package com.example.uilibraryquickstart

import android.os.Bundle
import android.view.View
import android.view.ViewGroup
import android.widget.Button
import androidx.appcompat.app.AlertDialog
import androidx.appcompat.app.AppCompatActivity
import com.azure.android.communication.common.CommunicationTokenCredential
import com.azure.android.communication.common.CommunicationTokenRefreshOptions
import com.azure.android.communication.common.CommunicationUserIdentifier
import com.azure.android.communication.ui.chat.ChatAdapter
import com.azure.android.communication.ui.chat.ChatAdapterBuilder
import com.azure.android.communication.ui.chat.presentation.ChatThreadView

class MainActivity : AppCompatActivity() {
    private lateinit var chatAdapter: ChatAdapter

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        val startButton = findViewById<Button>(R.id.startButton)
        startButton.setOnClickListener { l: View? ->
            val communicationTokenRefreshOptions =
                CommunicationTokenRefreshOptions(
                    { accessToken }, true
                )
            val communicationTokenCredential =
                CommunicationTokenCredential(communicationTokenRefreshOptions)
            chatAdapter = ChatAdapterBuilder()
                .endpoint(endpoint)
                .credential(communicationTokenCredential)
                .identity(CommunicationUserIdentifier(acsIdentity))
                .displayName(displayName)
                .threadId(threadId)
                .build()
            try {
                chatAdapter.connect(this@MainActivity).get()
                val chatView: View = ChatThreadView(this@MainActivity, chatAdapter)
                addContentView(
                    chatView,
                    ViewGroup.LayoutParams(
                        ViewGroup.LayoutParams.MATCH_PARENT,
                        ViewGroup.LayoutParams.MATCH_PARENT
                    )
                )
            } catch (e: Exception) {
                var messageCause: String? = "Unknown error"
                if (e.cause != null && e.cause!!.message != null) {
                    messageCause = e.cause!!.message
                }
                showAlert(messageCause)
            }
        }
    }

    /**
     *
     * @return String endpoint URL from Azure Communication Services Admin UI, "https://example.domain.com/"
     */
    private val endpoint: String?
        get() = "https://example.domain.com/"

    /**
     *
     * @return String identity of the user joining the chat
     * Looks like "8:acs:a6aada1f-0b1e-47ac-866a-91aae00a1c01_00000015-45ee-bad7-0ea8-923e0d008a89"
     */
    private val acsIdentity: String?
        get() = ""

    /**
     *
     * @return String display name of the user joining the chat
     */
    private val displayName: String?
        get() = ""

    /**
     *
     * @return String secure Azure Communication Services access token for the current user
     */
    private val accessToken: String?
        get() = ""

    /**
     *
     * @return String id of Azure Communication Services chat thread to join
     * Looks like "19:AVNnEll25N4KoNtKolnUAhAMu8ntI_Ra03saj0Za0r01@thread.v2"
     */
    private val threadId: String?
        get() = ""

    fun showAlert(message: String?) {
        runOnUiThread {
            AlertDialog.Builder(this@MainActivity)
                .setMessage(message)
                .setTitle("Alert")
                .setPositiveButton(
                    "OK"
                ) { _, i -> }
                .show()
        }
    }
}

Eseguire il codice

In Android Studio compilare e avviare l'applicazione:

  1. Selezionare Avvia esperienza.
  2. Il client di chat si unirà al thread di chat ed è possibile iniziare a digitare e inviare messaggi
  3. Se il client non è in grado di partecipare al thread e vengono visualizzati errori di chatJoin non riusciti, verificare che il token di accesso dell'utente sia valido e che l'utente sia stato aggiunto al thread di chat tramite chiamata API REST o usando l'interfaccia della az riga di comando.

GIF animation that shows an example of how the project runs on an Android device.

Importante

Questa funzionalità di Servizi di comunicazione di Azure è attualmente in anteprima.

Le API di anteprima e gli SDK vengono forniti senza un contratto di servizio. È consigliabile non usarli per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate.

Per altre informazioni, vedere Condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure.

Ottenere l'applicazione iOS di esempio per questa guida introduttiva nella libreria dell'interfaccia utente open source Servizi di comunicazione di Azure per iOS.

Prerequisiti

  • Un account Azure e una sottoscrizione di Azure attiva. Creare un account gratuitamente.
  • Un Mac che esegue Xcode 13 o versione successiva e un certificato per sviluppatore valido installato nel keychain. CocoaPods deve essere installato anche per recuperare le dipendenze.
  • Una risorsa Servizi di comunicazione di Azure distribuita, prendere nota dell'URL dell'endpoint.
  • Un Servizi di comunicazione di Azure token di accesso e un identificatore utente.
  • Un Servizi di comunicazione di Azure thread di chat e ora aggiungere l'utente creato nell'ultimo passaggio a questo thread di chat.

Configurare il progetto

Completare le sezioni seguenti per configurare il progetto di avvio rapido.

Creare un nuovo progetto Xcode

In Xcode creare un nuovo progetto:

  1. Scegliere Nuovo>progetto dal menu File.

  2. In Scegliere un modello per il nuovo progetto selezionare la piattaforma iOS e selezionare il modello Applicazione app. La guida introduttiva usa gli storyboard UIKit.

    Screenshot that shows the Xcode new project dialog, with iOS and the App template selected.

  3. In Scegliere le opzioni per il nuovo progetto immettere UILibraryQuickStart per il nome del prodotto. Per l'interfaccia selezionare Storyboard. La guida introduttiva non crea test, quindi è possibile deselezionare la casella di controllo Includi test .

    Screenshot that shows setting new project options in Xcode.

Installare il pacchetto e le dipendenze

  1. (Facoltativo) Per MacBook con M1, installare e abilitare Rosetta in Xcode.

  2. Nella directory radice del progetto eseguire pod init per creare un Podfile. Se si verifica un errore, aggiornare CocoaPods alla versione corrente.

  3. Aggiungere il codice seguente al podfile. Sostituire UILibraryQuickStart con il nome del progetto.

    platform :ios, '14.0'

target 'UILibraryQuickStart' do
    use_frameworks!
    pod 'AzureCommunicationUIChat', '1.0.0-beta.4'
end

  4. Eseguire pod install --repo-update.

  5. In Xcode aprire il file xcworkspace generato.

Disattivare Bitcode

Nel progetto Xcode, in Compila Impostazioni, impostare l'opzione Abilita bitcode su No. Per trovare l'impostazione, modificare il filtro da Basic a All o usare la barra di ricerca.

Screenshot that shows the Build Settings option to turn off Bitcode.

Inizializzare il composito

Per inizializzare il composito:

  1. Vai a ViewController.

  2. Aggiungere il codice seguente per inizializzare i componenti compositi per una chat. Sostituire <USER_ID> con l'identificatore utente. Sostituire <USER_ACCESS_TOKEN> con il token di accesso. Sostituire <ENDPOINT_URL> con l'URL dell'endpoint. Sostituire <THREAD_ID> con l'ID del thread di chat. Sostituire <DISPLAY_NAME> con il proprio nome. Il limite di lunghezza della stringa per <DISPLAY_NAME> è di 256 caratteri.

    import UIKit
import AzureCommunicationCommon
import AzureCommunicationUIChat

class ViewController: UIViewController {
    var chatAdapter: ChatAdapter?

    override func viewDidLoad() {
        super.viewDidLoad()

        let button = UIButton()
        button.contentEdgeInsets = UIEdgeInsets(top: 10.0, left: 20.0, bottom: 10.0, right: 20.0)
        button.layer.cornerRadius = 10
        button.backgroundColor = .systemBlue
        button.setTitle("Start Experience", for: .normal)
        button.addTarget(self, action: #selector(startChatComposite), for: .touchUpInside)

        button.translatesAutoresizingMaskIntoConstraints = false
        self.view.addSubview(button)
        button.widthAnchor.constraint(equalToConstant: 200).isActive = true
        button.heightAnchor.constraint(equalToConstant: 50).isActive = true
        button.centerXAnchor.constraint(equalTo: view.centerXAnchor).isActive = true
        button.centerYAnchor.constraint(equalTo: view.centerYAnchor).isActive = true
    }

    @objc private func startChatComposite() {
        let communicationIdentifier = CommunicationUserIdentifier("<USER_ID>")
        guard let communicationTokenCredential = try? CommunicationTokenCredential(
            token: "<USER_ACCESS_TOKEN>") else {
            return
        }

        self.chatAdapter = ChatAdapter(
            endpoint: "<ENDPOINT_URL>", identifier: communicationIdentifier,
            credential: communicationTokenCredential,
            threadId: "<THREAD_ID>",
            displayName: "<DISPLAY_NAME>")

        Task { @MainActor in
            guard let chatAdapter = self.chatAdapter else {
                return
            }
            try await chatAdapter.connect()
            let chatCompositeViewController = ChatCompositeViewController(
                with: chatAdapter)

            let closeItem = UIBarButtonItem(
                barButtonSystemItem: .close,
                target: nil,
                action: #selector(self.onBackBtnPressed))
            chatCompositeViewController.title = "Chat"
            chatCompositeViewController.navigationItem.leftBarButtonItem = closeItem

            let navController = UINavigationController(rootViewController: chatCompositeViewController)
            navController.modalPresentationStyle = .fullScreen

            self.present(navController, animated: true, completion: nil)
        }
    }

    @objc func onBackBtnPressed() {
        self.dismiss(animated: true, completion: nil)
        Task { @MainActor in
            self.chatAdapter?.disconnect(completionHandler: { [weak self] result in
                switch result {
                case .success:
                    self?.chatAdapter = nil
                case .failure(let error):
                    print("disconnect error \(error)")
                }
            })
        }
    }
}

  3. Se si sceglie di inserire la visualizzazione chat in un frame inferiore alle dimensioni dello schermo, la larghezza minima consigliata è 250 e l'altezza minima consigliata è 300.

Eseguire il codice

Per compilare ed eseguire l'app nel simulatore iOS, selezionare Product Run (Esegui prodotto>) o usare il tasto di scelta rapida (⌘-R). Provare quindi l'esperienza di chat nel simulatore:

  1. Selezionare Avvia esperienza.
  2. Il client di chat si unirà al thread di chat ed è possibile iniziare a digitare e inviare messaggi.
  3. Se il client non è in grado di aggiungere il thread e vengono visualizzati chatJoin errori non riusciti, verificare che il token di accesso dell'utente sia valido e che l'utente sia stato aggiunto al thread di chat tramite chiamata ALL'API REST o usando l'interfaccia della riga di comando az.

GIF animation that demonstrates the final look and feel of the quickstart iOS app.

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di comunicazione, è possibile eliminare la risorsa o il gruppo di risorse.

L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

Altre informazioni sulla pulizia delle risorse.