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

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
• Una risorsa distribuita di Servizi di comunicazione di Azure. Creare una risorsa di Servizi di comunicazione di Azure.
• Token Servizi di comunicazione di Azure. Vedere questo esempio.

Accedere a queste guide introduttive

• Componenti dell'interfaccia utente
• Compositi
• Client con stato (chat)

Accedere a questi storybook

• Componenti dell'interfaccia utente
• Compositi
• Client con stato (chat)

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

Prerequisiti

• Un account Azure e una sottoscrizione di Azure attiva. Creare un account gratuitamente.
• Un sistema operativo che esegue Android Studio.
• Una risorsa distribuita di Servizi di comunicazione di Azure. Prendere nota dell'URL dell'endpoint.
• Token di accesso e identificatore utente di Servizi di comunicazione di Azure.
• Un thread di chat Servizi di comunicazione di Azure con l'utente del passaggio precedente aggiunto.

Configurare il progetto

Completare le sezioni seguenti per configurare il progetto della guida introduttiva.

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.

   

3. Selezionare Avanti.

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

5. Selezionare Fine.

   

Installare i pacchetti

Per installare i pacchetti dell'applicazione necessari, completare le sezioni seguenti.

Aggiungere una dipendenza

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

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 settings.gradle, in dependencyResolutionManagement(Gradle version 6.8 or greater). Per le versioni precedenti di Android Studio (4.*), repositories si trova a livello di progetto build.gradle in allprojects{}.

   // 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, dal menu File scegliere Sincronizza progetto con file gradle.

Aggiungere un pulsante ad activity_main.xml

Nel file di layout app/src/main/res/layout/activity_main.xml, aggiungere il codice seguente per creare un pulsante per l'avvio del 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à () o le funzioni (kotlinjava) per endpoint, displayNameacsIdentity, accessToken, e ThreadId. Sostituire endpoint con l'URL della risorsa fornita 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 oggetto pertinentedisplayName. Sostituire ThreadId con il valore restituito al momento della creazione del thread. Aggiungere l'utente al thread tramite la chiamata api REST o il client az command-line interface prima di provare a eseguire l'esempio di avvio rapido. In caso contrario, al client viene negato l'accesso 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()
        }
    }
}

package com.example.uilibraryquickstart;

import androidx.appcompat.app.AlertDialog;
import androidx.appcompat.app.AppCompatActivity;
import android.content.DialogInterface;
import android.os.Bundle;
import android.view.View;
import android.view.ViewGroup;
import android.widget.Button;
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;

public class MainActivity extends AppCompatActivity {
    private ChatAdapter chatAdapter;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        Button startButton = findViewById(R.id.startButton);
        startButton.setOnClickListener(l -> {
            CommunicationTokenRefreshOptions communicationTokenRefreshOptions =
                    new CommunicationTokenRefreshOptions(this::accessToken, true);
            CommunicationTokenCredential communicationTokenCredential =
                    new CommunicationTokenCredential(communicationTokenRefreshOptions);
            chatAdapter = new ChatAdapterBuilder()
                    .endpoint(endpoint())
                    .credential(communicationTokenCredential)
                    .identity(new CommunicationUserIdentifier(acsIdentity()))
                    .displayName(displayName())
                    .threadId(threadId())
                    .build();
            try {
                chatAdapter.connect(MainActivity.this).get();
                View chatView = new ChatThreadView(MainActivity.this, chatAdapter);
                addContentView(chatView, new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,ViewGroup.LayoutParams.MATCH_PARENT));
            }
            catch (Exception e){
                String messageCause = "Unknown error";
                if (e.getCause() != null && e.getCause().getMessage() != null){
                    messageCause = e.getCause().getMessage();
                }
                showAlert(messageCause);
            }
        });
    }
    /**
     *
     * @return String endpoint URL from Azure Communication Services Admin UI, "https://example.domain.com/"
     */
    private String endpoint(){
        return "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 String acsIdentity(){
        return "";
    }
    /**
     *
     * @return String display name of the user joining the chat
     */
    private String displayName(){
        return "";
    }
    /**
     *
     * @return String secure Azure Communication Services access token for the current user
     */
    private String accessToken(){
        return "";
    }
    /**
     *
     * @return String id of Azure Communication Services chat thread to join
     * Looks like "19:AVNnEll25N4KoNtKolnUAhAMu8ntI_Ra03saj0Za0r01@thread.v2"
     */
    private String threadId(){
        return "";
    }
    void showAlert(String message){
        runOnUiThread(new Runnable() {
            @Override
            public void run() {
                new AlertDialog.Builder(MainActivity.this)
                        .setMessage(message)
                        .setTitle("Alert")
                        .setPositiveButton("OK", new DialogInterface.OnClickListener() {
                            @Override
                            public void onClick(DialogInterface dialogInterface, int i) {
                            }
                        })
                        .show();
            }
        });
    }
}

Eseguire il codice

In Android Studio compilare e avviare l'applicazione.

1. Selezionare Avvia esperienza.
2. Il client di chat si unisce 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 az riga di comando.

Ottenere l'applicazione iOS di esempio per questa guida introduttiva nella libreria dell'interfaccia utente Servizi di comunicazione di Azure open source 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 portachiavi. È necessario che sia installato anche CocoaPods per recuperare le dipendenze.
• Una risorsa distribuita di Servizi di comunicazione di Azure. Prendere nota dell'URL dell'endpoint.
• Token di accesso e identificatore utente di Servizi di comunicazione di Azure.
• Un thread di chat Servizi di comunicazione di Azure. Aggiungere l'utente creato nel passaggio precedente a questo thread di chat.

Configurare il progetto

Completare le sezioni seguenti per configurare il progetto della guida introduttiva.

Creare un nuovo progetto Xcode

Creare un nuovo progetto in Xcode.

1. Nel menu File selezionare Nuovo>Progetto.

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

   

3. In Scegli 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.

   

Installare il pacchetto e le relative 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 generato con estensione .xcworkspace.

Disattivare Bitcode

Nel progetto Xcode, in Impostazioni di compilazione, impostare l'opzione Abilita Bitcode su No. Per individuare l'impostazione, modificare il filtro da Base a Tutto o usare la barra di ricerca.

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, è consigliabile usare la larghezza minima di 250 e l'altezza minima di 300.

Eseguire il codice

Per compilare ed eseguire l'app nel simulatore iOS, selezionare Product Run (Esecuzione prodotto>). È anche possibile 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 unisce 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 la chiamata all'API REST o usando l'interfaccia della riga di comando az.