Guia de início rápido: adicionar bate-papo com a Biblioteca da Interface do Usuário

  • Artigo

Introdução à Biblioteca de Interface do Usuário dos Serviços de Comunicação do Azure para integrar rapidamente experiências de comunicação em seus aplicativos. Neste guia de início rápido, saiba como integrar compósitos de bate-papo da Biblioteca da Interface do Usuário em um aplicativo e configurar a experiência para os usuários do aplicativo.

A Biblioteca da Interface do Usuário dos Serviços de Comunicação renderiza uma experiência de bate-papo completa diretamente em seu aplicativo. Ele cuida da conexão aos serviços de chat dos Serviços de Comunicação do Azure e atualiza a presença do participante automaticamente. Como desenvolvedor, você precisa se preocupar com onde na experiência do usuário do seu aplicativo você deseja que a experiência de bate-papo seja iniciada e crie apenas os recursos dos Serviços de Comunicação do Azure conforme necessário.

Nota

Para obter documentação detalhada e guias de início rápido sobre a Biblioteca da Interface do Usuário da Web, visite o Storybook da Biblioteca da Interface do Usuário da Web.

Pré-requisitos

Você pode acessar os seguintes inícios rápidos:

Importante

Este recurso dos Serviços de Comunicação do Azure está atualmente em visualização.

As APIs e SDKs de visualização são fornecidos sem um contrato de nível de serviço. Recomendamos que você não os use para cargas de trabalho de produção. Alguns recursos podem não ser suportados ou podem ter recursos restritos.

Para obter mais informações, consulte Termos de Utilização Suplementares para Pré-visualizações do Microsoft Azure.

Obtenha o aplicativo Android de exemplo para este início rápido na Biblioteca de Interface do Usuário dos Serviços de Comunicação do Azure de código aberto para Android.

Pré-requisitos

Configurar o projeto

Conclua as seções a seguir para configurar o projeto de início rápido.

Criar um novo projeto Android

No Android Studio, crie um novo projeto:

  1. No menu Arquivo, selecione Novo>Novo Projeto.

  2. Em Novo Projeto, selecione o modelo de projeto Atividade vazia.

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

  3. Selecione Seguinte.

  4. Em Atividade vazia, nomeie o projeto UILibraryQuickStart. Para idioma, selecione Java/Kotlin. Para o SDK mínimo, selecione API 23: Android 6.0 (Marshmallow) ou posterior.

  5. Selecione Concluir.

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

Instalar os pacotes

Conclua as seções a seguir para instalar os pacotes de aplicativos necessários.

Adicionar uma dependência

No arquivo UILibraryQuickStart/app/build.gradle no nível do aplicativo (na pasta do aplicativo), adicione a seguinte dependência:

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

Adicionar repositórios Maven

O repositório de pacotes do Azure é necessário para integrar a biblioteca:

Para adicionar o repositório:

  1. Em seus scripts Gradle de projeto, certifique-se de que os seguintes repositórios sejam adicionados. Para Android Studio (2020.*), repositories está em , em dependencyResolutionManagement(Gradle version 6.8 or greater)settings.gradle. Para versões anteriores do Android Studio (4.*), repositories está no nível build.gradledo projeto, em allprojects{}.

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

  2. Sincronize seu projeto com os arquivos Gradle. Para sincronizar o projeto, no menu Arquivo , selecione Sincronizar projeto com arquivos Gradle.

Adicionar um botão ao activity_main.xml

No arquivo de layout app/src/main/res/layout/activity_main.xml , adicione o seguinte código para criar um botão para iniciar o composto:

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

Inicializar o composto

Para inicializar o composto:

  1. Aceder a MainActivity.

  2. Adicione o seguinte código para inicializar seus componentes compostos para chamada. Substitua os valores de cadeia de caracteres para propriedades (kotlin) ou funções (java) para endpoint, , accessTokenacsIdentitydisplayNamee .ThreadId Substitua endpoint pela URL do seu recurso, conforme fornecido pelos Serviços de Comunicação do Azure. Substitua acsIdentity e pelos valores fornecidos pelos Serviços de Comunicação do Azure quando você criou o token de acesso e accessToken usa um displayName relevante. Substitua ThreadId pelo valor retornado quando você criou o thread. Lembre-se de adicionar o usuário ao thread por meio da chamada da API REST ou do cliente de interface de linha de comando az antes de tentar executar o exemplo de início rápido ou o acesso ao cliente será negado para ingressar no 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()
        }
    }
}

Executar o código

No Android Studio, crie e inicie o aplicativo:

  1. Selecione Iniciar experiência.
  2. O cliente de chat se juntará ao tópico de bate-papo e você poderá começar a digitar e enviar mensagens
  3. Se o cliente não conseguir ingressar no thread e você vir erros de falha no chatJoin , verifique se o token de acesso do usuário é válido e se o usuário foi adicionado ao thread de chat por chamada à API REST ou usando a interface de linha de az comando.

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

Importante

Este recurso dos Serviços de Comunicação do Azure está atualmente em visualização.

As APIs e SDKs de visualização são fornecidos sem um contrato de nível de serviço. Recomendamos que você não os use para cargas de trabalho de produção. Alguns recursos podem não ser suportados ou podem ter recursos restritos.

Para obter mais informações, consulte Termos de Utilização Suplementares para Pré-visualizações do Microsoft Azure.

Obtenha o aplicativo iOS de exemplo para este início rápido na Biblioteca de Interface do Usuário dos Serviços de Comunicação do Azure de código aberto para iOS.

Pré-requisitos

Configurar o projeto

Conclua as seções a seguir para configurar o projeto de início rápido.

Criar um novo projeto Xcode

No Xcode, crie um novo projeto:

  1. No menu Arquivo, selecione Novo>projeto.

  2. Em Escolha um modelo para seu novo projeto, selecione a plataforma iOS e selecione o modelo de aplicativo de aplicativo . O início rápido usa os storyboards UIKit.

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

  3. Em Escolher opções para seu novo projeto, para o nome do produto, digite UILibraryQuickStart. Para a interface, selecione Storyboard. O início rápido não cria testes, portanto, você pode desmarcar a caixa de seleção Incluir testes .

    Screenshot that shows setting new project options in Xcode.

Instalar o pacote e as dependências

  1. (Opcional) Para MacBook com M1, instale e ative o Rosetta no Xcode.

  2. No diretório raiz do projeto, execute pod init para criar um Podfile. Se você encontrar um erro, atualize o CocoaPods para a versão atual.

  3. Adicione o seguinte código ao seu Podfile. Substitua UILibraryQuickStart pelo nome do projeto.

    platform :ios, '14.0'

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

  4. Execute pod install --repo-update.

  5. No Xcode, abra o arquivo xcworkspace gerado.

Desativar Bitcode

No projeto Xcode, em Configurações de compilação, defina a opção Ativar código de bits como Não. Para encontrar a configuração, altere o filtro de Básico para Todos ou use a barra de pesquisa.

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

Inicializar o composto

Para inicializar o composto:

  1. Aceder a ViewController.

  2. Adicione o seguinte código para inicializar seus componentes compostos para um bate-papo. Substitua <USER_ID> pelo identificador do usuário. Substitua <USER_ACCESS_TOKEN> pelo seu token de acesso. Substitua <ENDPOINT_URL> pelo URL do ponto final. Substitua <THREAD_ID> pelo ID do seu tópico de chat. Substitua <DISPLAY_NAME> pelo seu nome. (O limite de comprimento da cadeia de caracteres é <DISPLAY_NAME> 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. Se você optar por colocar a visualização de bate-papo em um quadro menor que o tamanho da tela, a largura mínima recomendada é 250 e a altura mínima recomendada é 300.

Executar o código

Para criar e executar seu aplicativo no simulador do iOS, selecione Executar produto>ou use o atalho de teclado (⌘-R). Em seguida, experimente a experiência de bate-papo no simulador:

  1. Selecione Iniciar experiência.
  2. O cliente de chat se juntará ao tópico de bate-papo e você poderá começar a digitar e enviar mensagens.
  3. Se o cliente não conseguir ingressar no thread e você vir chatJoin erros de falha, verifique se o token de acesso do usuário é válido e se o usuário foi adicionado ao thread de chat por chamada à API REST ou usando a interface de linha de comando az.

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

Clean up resources (Limpar recursos)

Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, você pode excluir o recurso ou grupo de recursos.

A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.

Saiba mais sobre a limpeza de recursos.