Share via

Schnellstart: Hinzufügen von Chatfunktionen mit der Benutzeroberflächenbibliothek

  • Artikel

Beginnen Sie mit der Verwendung der Benutzeroberflächenbibliothek von Azure Communication Services, um schnell Kommunikationsumgebungen in Ihre Anwendungen zu integrieren. In dieser Schnellstartanleitung erfahren Sie, wie Sie zusammengesetzte Chatkomponenten der Benutzeroberflächenbibliothek in eine Anwendung integrieren und die Funktion für die Benutzer Ihrer App einrichten.

Die Benutzeroberflächenbibliothek von Communication Services rendert eine vollständige Chatfunktion direkt in Ihrer Anwendung. Sie verarbeitet die Verbindung mit Azure Communication Services-Chatdiensten und aktualisiert automatisch die Anwesenheit von Teilnehmer*innen. Als Entwickler*in müssen Sie sich darüber Gedanken machen, an welcher Stelle der Benutzeroberfläche Ihrer App die Chatfunktion gestartet werden soll. Dabei sollten Azure Communication Services-Ressourcen nur nach Bedarf erstellt werden.

Hinweis

Eine ausführliche Dokumentation und Kurzanleitungen zur Web UI Library finden Sie im Web UI Library Storybook.

Voraussetzungen

Sie können auf die folgenden Schnellstarts zugreifen:

Wichtig

Dieses Feature von Azure Communication Services befindet sich derzeit in der Vorschau.

Vorschau-APIs und -SDKs werden ohne Vereinbarung zum Servicelevel bereitgestellt. Es wird empfohlen, diese nicht für Produktionsworkloads zu verwenden. Einige Features werden möglicherweise nicht unterstützt oder bieten nur eingeschränkte Funktionalität.

Weitere Informationen finden Sie in den ergänzenden Nutzungsbestimmungen für Microsoft Azure-Vorschauversionen.

Rufen Sie sich die Android-Beispielanwendung für diesen Schnellstart in der Open Source-Azure Communication Services UI-Bibliothek für Android ab.

Voraussetzungen

Einrichten des Projekts

Füllen Sie die folgenden Abschnitte aus, um das Schnellstartprojekt einzurichten.

Erstellen eines neuen Android-Projekts

Erstellen Sie in Android Studio ein neues Projekt:

  1. Wählen Sie im Menü Datei die Option Neu>Neues Projekt aus.

  2. Wählen Sie in Neues Projekt die Projektvorlage Leere Aktivität aus.

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

  3. Wählen Sie Weiter aus.

  4. Benennen Sie in Leere Aktivität das Projekt UILibraryQuickStart. Wählen Sie für die Sprache Java/Kotlin aus. Wählen Sie als Mindestversion des SDK API 23: Android 6.0 (Marshmallow) oder höher aus.

  5. Klicken Sie auf Fertig stellen.

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

Installieren der Pakete

Füllen Sie die folgenden Abschnitte aus, um die erforderlichen Anwendungspakete zu installieren.

Hinzufügen einer Abhängigkeit

Fügen Sie in der Datei UILibraryQuickStart/app/build.gradle auf App-Ebene (im App-Ordner) die folgende Abhängigkeit hinzu:

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

Hinzufügen von Maven-Repositorys

Das Azure-Paketrepository ist erforderlich, um die Bibliothek zu integrieren:

So fügen Sie das Repository hinzu:

  1. Vergewissern Sie sich, dass in Ihren Gradle-Skripts die folgenden Repositorys hinzugefügt wurden. Für Android Studio (2020.*) befindet sich repositories in settings.gradle, unter dependencyResolutionManagement(Gradle version 6.8 or greater). Bei früheren Versionen von Android Studio (4.*) befindet sich repositories auf der Projektebene build.gradle, unter allprojects{}.

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

  2. Synchronisieren Sie Ihr Projekt mit den Gradle-Dateien. Um das Projekt zu synchronisieren, wählen Sie im Menü Datei die Option Projekt mit Gradle-Dateien synchronisieren aus.

Hinzufügen einer Schaltfläche zu „activity_main.xml“

Fügen Sie in der Layoutdatei app/src/main/res/layout/activity_main.xml den folgenden Code hinzu, um eine Schaltfläche zum Starten der zusammengesetzten Komponente zu erstellen:

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

Initialisieren der zusammengesetzten Komponente

So initialisieren Sie die zusammengesetzte Komponente

  1. Gehe zu MainActivity.

  2. Fügen Sie den folgenden Code hinzu, um Ihre zusammengesetzten Komponenten für den Anruf zu initialisieren. Ersetzen Sie die Zeichenfolgenwerte für Eigenschaften (Kotlin) oder Funktionen (Java) für endpoint, acsIdentity, displayNameaccessToken und ThreadId. Ersetzen Sie endpoint durch die von Azure Communication Services bereitgestellte URL für Ihre Ressource. Ersetzen Sie acsIdentity und accessToken durch die Werte, die von Azure Communication Services beim Erstellen des Zugriffstokens bereitgestellt wurden, und verwenden Sie einen relevanten displayName-Wert. Ersetzen Sie ThreadId durch den Wert, der beim Erstellen des Threads zurückgegeben wurde. Denken Sie daran, den Benutzer über einen REST-API-Aufruf oder den az-Befehlszeilenschnittstellenclient zum Thread hinzuzufügen, bevor Sie versuchen, das Schnellstartbeispiel auszuführen. Andernfalls wird dem Client die Teilnahme am Thread verweigert.

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

Ausführen des Codes

Erstellen und starten Sie in Android Studio die Anwendung:

  1. Wählen Sie Start Experience aus.
  2. Der Chatclient tritt dem Chatthread bei, und Sie können mit der Eingabe von Text und dem Senden von Nachrichten beginnen.
  3. Wenn der Client dem Thread nicht beitreten kann und chatJoin-Fehler angezeigt werden, vergewissern Sie sich, dass das Zugriffstoken Ihres Benutzers gültig ist und dass der Benutzer dem Chatthread per REST-API-Aufruf oder mithilfe der az-Befehlszeilenschnittstelle hinzugefügt wurde.

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

Wichtig

Dieses Feature von Azure Communication Services befindet sich derzeit in der Vorschau.

Vorschau-APIs und -SDKs werden ohne Vereinbarung zum Servicelevel bereitgestellt. Es wird empfohlen, diese nicht für Produktionsworkloads zu verwenden. Einige Features werden möglicherweise nicht unterstützt oder bieten nur eingeschränkte Funktionalität.

Weitere Informationen finden Sie in den ergänzenden Nutzungsbestimmungen für Microsoft Azure-Vorschauversionen.

Rufen Sie die iOS-Beispielanwendung für diesen Schnellstart in der Open Source-UI-Bibliothek für iOS von Azure Communication Services ab.

Voraussetzungen

  • Ein Azure-Konto und ein aktives Azure-Abonnement. Sie können kostenlos ein Konto erstellen.
  • Einen Mac mit Xcode 13 oder höher und ein gültiges in Ihrer Keychain installiertes Entwicklerzertifikat CocoaPods muss ebenfalls installiert sein, um Abhängigkeiten abrufen zu können.
  • Eine bereitgestellte Azure Communication Services-Ressource. Notieren Sie sich die Endpunkt-URL.
  • Ein Azure Communication Services-Zugriffstoken und ein Azure Communication Services-Benutzerbezeichner.
  • Ein Azure Communication Services-Chatthread. Fügen Sie diesem Chatthread jetzt den Benutzer hinzu, den Sie im letzten Schritt erstellt haben.

Einrichten des Projekts

Füllen Sie die folgenden Abschnitte aus, um das Schnellstartprojekt einzurichten.

Erstellen eines neuen Xcode-Projekts

Erstellen Sie ein neues Projekt in Xcode:

  1. Wählen Sie im Menü Datei die Option Neu>Projekt aus.

  2. Wählen Sie unter Vorlage für neues Projekt auswählen die Plattform iOS und dann die Anwendungsvorlage App aus. In der Schnellstartanleitung werden die UIKit-Storyboards verwendet.

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

  3. Geben Sie unter Optionen für Ihr neues Projekt auswählen als Produktnamen UILibraryQuickStart ein. Wählen Sie als Schnittstelle Storyboard aus. Die Schnellstartanleitung erstellt keine Tests, sodass Sie das Kontrollkästchen Tests einschließen deaktivieren können.

    Screenshot that shows setting new project options in Xcode.

Installieren Sie das Paket und Abhängigkeiten.

  1. (Optional) Installieren und Aktivieren von Rosetta in Xcode für Macbook mit M1.

  2. Führen Sie im Stammverzeichnis Ihres Projekts pod init aus, um eine Podfile-Datei zu erstellen. Wenn ein Fehler auftritt, aktualisieren Sie CocoaPods auf die aktuelle Version.

  3. Fügen Sie Ihrer Podfile-Datei folgenden Code hinzu. Ersetzen Sie UILibraryQuickStart durch Ihren Projektnamen.

    platform :ios, '14.0'

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

  4. Führen Sie pod install --repo-update aus.

  5. Öffnen Sie in Xcode die generierte Datei xcworkspace.

Deaktivieren von Bitcode

Legen Sie im Xcode-Projekt unter Buildeinstellungen die Option Bitcode aktivieren auf Nein fest. Um die Einstellung zu finden, ändern Sie den Filter von Basic in Alle, oder verwenden Sie die Suchleiste.

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

Initialisieren der zusammengesetzten Komponente

So initialisieren Sie die zusammengesetzte Komponente

  1. Gehe zu ViewController.

  2. Fügen Sie den folgenden Code hinzu, um Ihre zusammengesetzten Komponenten für einen Chat zu initialisieren. Ersetzen Sie <USER_ID> durch den Benutzerbezeichner. Ersetzen Sie <USER_ACCESS_TOKEN> durch Ihr Zugriffstoken. Ersetzen Sie <ENDPOINT_URL> durch Ihre Endpunkt-URL. Ersetzen Sie <THREAD_ID> durch Ihre Chatthread-ID. Ersetzen Sie <DISPLAY_NAME> durch Ihren eigenen Namen. (Die maximale Zeichenfolgenlänge für <DISPLAY_NAME> beträgt 256 Zeichen).

    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. Wenn Sie die Chatansicht in einen Frame einfügen, der kleiner als die Bildschirmgröße ist, beträgt die empfohlene Mindestbreite 250 und die empfohlene Mindesthöhe 300.

Ausführen des Codes

Wählen Sie zum Erstellen und Starten Ihrer App im iOS-Simulator Produkt>Ausführen aus, oder verwenden Sie die Tastenkombination (⌘-R). Testen Sie dann die Chatfunktion im Simulator:

  1. Wählen Sie Start Experience aus.
  2. Der Chatclient tritt dem Chatthread bei, und Sie können mit der Eingabe von Text und dem Senden von Nachrichten beginnen.
  3. Wenn der Client dem Thread nicht beitreten kann und chatJoin-Fehler angezeigt werden, vergewissern Sie sich, dass das Zugriffstoken Ihres Benutzers gültig ist und dass der Benutzer dem Chatthread per REST-API-Aufruf oder mithilfe der az-Befehlszeilenschnittstelle hinzugefügt wurde.

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

Bereinigen von Ressourcen

Wenn Sie ein Communication Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen.

Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind.

Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.