Comparteix a través de

Inicio rápido: Adición de chat con la biblioteca de interfaz de usuario

  • Article

Comience a usar la biblioteca de la interfaz de usuario de Azure Communication Services para integrar rápidamente las experiencias de comunicación en sus aplicaciones. En este inicio rápido, aprenderá a integrar compuestos de chat de la biblioteca de interfaz de usuario en una aplicación y a configurar la experiencia para los usuarios de la aplicación.

La biblioteca de interfaz de usuario de Communication Services representa una experiencia de chat completa directamente en la aplicación. Lo que hace es conectarse a los servicios de chat de Azure Communication Services y actualizar la presencia del participante automáticamente. Como desarrollador, tiene que preocuparse de en qué parte de la experiencia de usuario de la aplicación quiere que se inicie la experiencia de chat y crear solo los recursos de Azure Communication Services que sean necesarios.

Nota:

Puede encontrar documentación detallada e inicios rápidos sobre la biblioteca de interfaz de usuario web en el libro de historias sobre la Biblioteca de interfaz de usuario.

Requisitos previos

Puede acceder a los siguientes inicios rápidos:

Importante

Esta característica de Azure Communication Services se encuentra actualmente en versión preliminar.

Las API y los SDK en versión preliminar se proporcionan sin contrato de nivel de servicio. Se recomienda no usarlos para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que sus funcionalidades estén limitadas.

Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

Obtenga la aplicación Android de ejemplo para este inicio rápido en la biblioteca de interfaz de usuario de código abierto de Azure Communication Services para Android.

Requisitos previos

Configuración del proyecto

Complete las secciones siguientes para configurar el proyecto de inicio rápido.

Creación de un nuevo proyecto de Android

En Android Studio, cree un proyecto nuevo:

  1. En el menú Archivo, seleccione Nuevo>Nuevo proyecto.

  2. En Nuevo proyecto, seleccione la plantilla de proyecto Actividad vacía.

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

  3. Seleccione Siguiente.

  4. En Actividad vacía, asigne al proyecto el nombre UILibraryQuickStart. En lenguaje, seleccione Java/Kotlin. Como SDK mínimo, seleccione API 23: Android 6.0 (Lollipop) o posterior.

  5. Seleccione Finalizar.

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

Instalación de los paquetes

Complete las secciones siguientes para instalar los paquetes de aplicación necesarios.

Adición de una dependencia

En el archivo UILibraryQuickStart/app/build.gradle de nivel de aplicación (en la carpeta de la aplicación), agregue la dependencia siguiente:

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

Agregar repositorios de Maven

Se requiere el repositorio de paquetes de Azure para integrar la biblioteca:

Para agregar el repositorio:

  1. En los scripts de Gradle del proyecto, asegúrese de agregar los siguientes repositorios. Para Android Studio (2020.*), repositories está en settings.gradle, que a su vez está en dependencyResolutionManagement(Gradle version 6.8 or greater). Para versiones anteriores de Android Studio (4.*), repositories está en el nivel de proyecto build.gradle, en allprojects{}.

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

  2. Sincronice el proyecto con los archivos de Gradle. Para sincronizar el proyecto, en el menú Archivo, seleccione Sincronizar proyecto con archivos Gradle.

Adición de un botón a activity_main.xml

En el archivo de diseño app/src/main/res/layout/activity_main.xml, agregue el código siguiente para crear un botón para iniciar el compuesto:

<?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>

Inicialización del compuesto

Para inicializar el compuesto:

  1. Ir a MainActivity.

  2. Agregue el siguiente código para inicializar los componentes compuestos de llamada. Reemplace los valores de cadena de las propiedades (kotlin) o las funciones (java) en endpoint, acsIdentity, displayNameaccessToken y ThreadId. Reemplace endpoint por la dirección URL del recurso proporcionado por Azure Communication Services. Reemplace acsIdentity y accessToken por los valores proporcionados por Azure Communication Services al crear el token de acceso y use un nombre para mostrar adecuado. Reemplace ThreadId por el valor devuelto al crear el subproceso. Recuerde agregar el usuario al subproceso a través de la llamada a la API REST o el cliente de la interfaz de la línea de comandos az antes de intentar ejecutar el ejemplo de inicio rápido o se denegará el acceso al cliente para unirse al subproceso.

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()
        }
    }
}

Ejecución del código

En Android Studio, compile e inicie la aplicación:

  1. Seleccione Iniciar Experiencia.
  2. El cliente de chat se unirá al subproceso de chat y se podrá empezar a escribir y enviar mensajes.
  3. Si el cliente no puede unirse al subproceso y ve errores de chatJoin, compruebe que el token de acceso del usuario sea válido y que el usuario se haya agregado al subproceso de chat mediante una llamada a la API REST o mediante la interfaz de línea de comandos az.

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

Importante

Esta característica de Azure Communication Services se encuentra actualmente en versión preliminar.

Las API y los SDK en versión preliminar se proporcionan sin contrato de nivel de servicio. Se recomienda no usarlos para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que sus funcionalidades estén limitadas.

Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

Obtenga la aplicación iOS de ejemplo para este inicio rápido en la biblioteca de interfaz de usuario de código abierto de Azure Communication Services para iOS.

Requisitos previos

  • Una cuenta y una suscripción activa de Azure. Cree una cuenta gratuita.
  • Un Mac ejecutando Xcode 13 o posterior junto con un certificado de desarrollador válido instalado en su keychain. CocoaPods también debe instalarse para capturar dependencias.
  • Un recurso de Azure Communication Services implementado. Anote la dirección URL del punto de conexión.
  • Un token de acceso y un identificador de usuario de Azure Communication Services.
  • Un subproceso de chat Azure Communication Services. Ahora agregue el usuario que creó en el último paso a este subproceso de chat.

Configuración del proyecto

Complete las secciones siguientes para configurar el proyecto de inicio rápido.

Creación de un nuevo proyecto de Xcode

En Xcode, cree un nuevo proyecto:

  1. En el menú Archivo, seleccione Nuevo>Proyecto.

  2. En Elegir una plantilla para el nuevo proyecto, seleccione la plataforma iOS y seleccione la plantilla de aplicación App. En el inicio rápido se usan guiones gráficos de UIKit.

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

  3. En Elegir opciones para el nuevo proyecto, escriba en el nombre del producto UILibraryQuickStart. Para la interfaz, seleccione Storyboard. El inicio rápido no crea pruebas, por lo que puede desactivar la casilla Incluir pruebas.

    Screenshot that shows setting new project options in Xcode.

Instale el paquete y sus dependencias

  1. (Opcional) Para MacBook con M1, instale y habilite Rosetta en Xcode.

  2. Cree un Podfile en el directorio raíz del proyecto mediante la ejecución de pod init. Actualice CocoaPods a la versión actual en caso de que se produzca un error.

  3. Agregue el código siguiente a su Podfile. Reemplace UILibraryQuickStart por el nombre del proyecto.

    platform :ios, '14.0'

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

  4. Ejecute pod install --repo-update.

  5. En Xcode, abra el archivo xcworkspace generado.

Desactivación de Bitcode

En el proyecto Xcode, en Configuración de compilación, establezca la opción Habilitar bitcode en No. Para encontrar la configuración, cambie el filtro de Básico a Todo o use la barra de búsqueda.

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

Inicialización del compuesto

Para inicializar el compuesto:

  1. Ir a ViewController.

  2. Agregue el siguiente código para inicializar los componentes compuestos de un chat. Reemplace <USER_ID> por el identificador de usuario. Reemplace <USER_ACCESS_TOKEN> con el token de acceso. Reemplace <ENDPOINT_URL> por la dirección URL del punto de conexión. Reemplace <THREAD_ID> por el identificador del subproceso de chat. Reemplace <DISPLAY_NAME> por su propio nombre. (El límite de longitud de cadena de <DISPLAY_NAME> es de 256 caracteres).

    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. Si decide colocar la vista de chat en un marco menor que el tamaño de pantalla, el ancho mínimo recomendado es 250 y el alto mínimo recomendado es 300.

Ejecución del código

Para compilar y ejecutar la aplicación en el simulador de iOS, seleccione Producto>Ejecutar o use el método abreviado de teclado (⌘-R). Pruebe ahora la experiencia de chat en el simulador:

  1. Seleccione Iniciar Experiencia.
  2. El cliente de chat se unirá al subproceso de chat y podrá empezar a escribir y enviar mensajes.
  3. Si el cliente no puede unirse al subproceso y aparecen errores de chatJoin, compruebe que el token de acceso del usuario sea válido y que el usuario se haya agregado al subproceso de chat mediante la llamada a la API REST o mediante la interfaz de la línea de comandos az.

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

Limpieza de recursos

Si quiere limpiar y quitar una suscripción a Communication Services, puede eliminar el recurso o grupo de recursos.

Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.

Obtenga más información sobre la limpieza de recursos.