Краткое руководство. Добавление чата с библиотекой пользовательского интерфейса

Статья
10/27/2023

Начните работу с библиотекой пользовательского интерфейса Службы коммуникации Azure, чтобы быстро интегрировать взаимодействие с приложениями. Из этого краткого руководства вы узнаете, как интегрировать составные чаты библиотеки пользовательского интерфейса в приложение и настроить интерфейс для пользователей приложения.

Библиотека пользовательского интерфейса служб коммуникации отображает полный интерфейс чата прямо в приложении. Он заботится о подключении к службам чата Службы коммуникации Azure и автоматически обновляет присутствие участника. Разработчику необходимо беспокоиться о том, где в пользовательском интерфейсе приложения вы хотите запустить чат и создать только Службы коммуникации Azure ресурсы по мере необходимости.

Примечание.

Подробные документацию и краткие руководства по библиотеке веб-пользовательского интерфейса см. в статье "История библиотеки веб-интерфейса".

Необходимые компоненты

Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Развернутый ресурс Служб коммуникации. Создайте ресурс Служб коммуникации.
Маркер Служб коммуникации Azure. Ознакомьтесь с этим примером.

Вы можете получить доступ к следующим кратким руководствам.

Внимание

Эта функция Службы коммуникации Azure сейчас доступна в предварительной версии.

Предварительные версии API и пакеты SDK предоставляются без соглашения об уровне обслуживания. Рекомендуется не использовать их для рабочих нагрузок. Некоторые функции могут не поддерживаться или могут иметь ограниченные возможности.

Дополнительные сведения см . в дополнительных условиях использования для предварительных версий Microsoft Azure.

Получите пример приложения Android для этого краткого руководства в библиотеке пользовательского интерфейса открытый код Службы коммуникации Azure для Android.

Необходимые компоненты

Учетная запись Azure и активная подписка Azure. Создайте учетную запись бесплатно .
ОС, в которой выполняется Android Studio.
Развернутый ресурс Службы коммуникации Azure обратите внимание на URL-адрес конечной точки.
Маркер доступа Службы коммуникации Azure и идентификатор пользователя.
Поток чата Службы коммуникации Azure с указанным выше пользователем.

Настройка проекта

Выполните следующие разделы, чтобы настроить проект быстрого запуска.

Создание нового проекта Android

В Android Studio создайте проект:

В меню "Файл" выберите "Создать>проект".
В новом проекте выберите шаблон проекта "Пустое действие ".
Выберите Далее.
В поле "Пустое действие" назовите project UILibraryQuickStart. Для языка выберите Java/Kotlin. Для минимального пакета SDK выберите API 23: Android 6.0 (Marshmallow) или более поздней версии.
Выберите Готово.

Установка пакетов

Выполните следующие разделы, чтобы установить необходимые пакеты приложений.

Добавление зависимости

В файле UILibraryQuickStart/app/build.gradle (в папке приложения) добавьте следующую зависимость:

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

Добавление репозиториев Maven

Для интеграции библиотеки требуется репозиторий пакетов Azure:

Чтобы добавить репозиторий, выполните следующие действия.

В скриптах проекта Gradle убедитесь, что добавлены следующие репозитории. Для Android Studio (2020.*) repositories находится в settings.gradleразделе dependencyResolutionManagement(Gradle version 6.8 or greater). Для более ранних версий Android Studio (4.*) repositories находится на уровне build.gradleпроекта в разделе allprojects{}.
```
// dependencyResolutionManagement
repositories {
    ...
    maven {
        url "https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1"
    }
    ...
}
```
Синхронизируйте проект с файлами Gradle. Чтобы синхронизировать проект, в меню "Файл " выберите "Синхронизировать проект с файлами Gradle".

Добавление кнопки для activity_main.xml

В файле макета app/src/main/res/layout/activity_main.xml добавьте следующий код, чтобы создать кнопку, чтобы запустить составной элемент:

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

Инициализация составного

Чтобы инициализировать составной элемент, выполните следующие действия.

Переход к MainActivity.
Добавьте следующий код, чтобы инициализировать составные компоненты для вызова. Замените строковые значения свойств (kotlin) или функций (java) для endpoint, acsIdentityи displayNameaccessToken ThreadId. Замените endpoint URL-адрес ресурса, как указано Службы коммуникации Azure. Замените acsIdentity значения, accessToken предоставленные Службы коммуникации Azure при создании маркера доступа и используйте соответствующее отображаемое имя. Замените ThreadId значение, возвращаемое при создании потока. Не забудьте добавить пользователя в поток с помощью вызова REST API или az command line interface client, прежде чем пытаться запустить пример быстрого запуска, или клиент будет отказано в доступе для присоединения к потоку.

Kotlin
Java

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

Выполнение кода

В Android Studio создайте и запустите приложение:

Выберите "Начать работу".
Клиент чата присоединится к потоку чата, и вы можете начать вводить и отправлять сообщения
Если клиент не может присоединиться к потоку, и вы видите ошибки чата, убедитесь, что маркер доступа пользователя действителен и что пользователь был добавлен в поток чата по вызову REST API или с помощью интерфейса командной az строки.

Анимация GIF, показывающая пример запуска проекта на устройстве Android.

Внимание

Эта функция Службы коммуникации Azure сейчас доступна в предварительной версии.

Дополнительные сведения см . в дополнительных условиях использования для предварительных версий Microsoft Azure.

Получите пример приложения iOS для этого краткого руководства в библиотеке пользовательского интерфейса открытый код Службы коммуникации Azure для iOS.

Необходимые компоненты

Учетная запись Azure и активная подписка Azure. Создайте учетную запись бесплатно .
Компьютер Mac под управлением Xcode 13 или более поздней версии и действительный сертификат разработчика, установленный в цепочке ключей. Кроме того, для получения зависимостей необходимо установить CocoaPods.
Развернутый ресурс Службы коммуникации Azure обратите внимание на URL-адрес конечной точки.
Маркер доступа Службы коммуникации Azure и идентификатор пользователя.
Поток чата Службы коммуникации Azure и теперь добавьте пользователя, созданного на последнем шаге в этот поток чата.

Настройка проекта

Выполните следующие разделы, чтобы настроить проект быстрого запуска.

Создание проекта Xcode

В Xcode создайте проект:

В меню "Файл" выберите "Создать>проект".
В разделе "Выбор шаблона" для нового проекта выберите платформу iOS и выберите шаблон приложения. В кратком руководстве используются раскадровки UIKit.
В поле "Выбор параметров для нового проекта" введите UILibraryQuickStart. Для интерфейса выберите "Раскадровка". Краткое руководство не создает тесты, поэтому можно снять флажок "Включить тесты ".

Установка пакета и зависимостей

(Необязательно) Для MacBook с M1 установите и включите Rosetta в Xcode.
В корневом каталоге проекта запустите файл pod init Podfile. При возникновении ошибки обновите CocoaPods до текущей версии.

Добавьте следующий код в podfile. Замените UILibraryQuickStart именем проекта.

platform :ios, '14.0'

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

Запустите pod install --repo-update.
В Xcode откройте созданный файл xcworkspace .

Отключение bitcode

В проекте Xcode в разделе "Параметры сборки" задайте для параметра Enable Bitcode значение No. Чтобы найти параметр, измените фильтр с "Базовый" на "Все" или используйте панель поиска.

Снимок экрана: параметр

Инициализация составного

Чтобы инициализировать составной элемент, выполните следующие действия.

Переход к ViewController.

Добавьте следующий код, чтобы инициализировать составные компоненты для чата. Замените <USER_ID> идентификатором пользователя. Замените <USER_ACCESS_TOKEN> маркер доступа. Замените <ENDPOINT_URL> URL-адрес конечной точки. Замените <THREAD_ID> идентификатором потока чата. Замените <DISPLAY_NAME> собственным именем. (Ограничение <DISPLAY_NAME> длины строки для 256 символов).

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

Если вы решили поместить представление чата в кадр, который меньше размера экрана, рекомендуемая минимальная ширина составляет 250, а рекомендуемая минимальная высота — 300.

Выполнение кода

Чтобы создать и запустить приложение в симуляторе iOS, выберите "Запуск продукта>" или используйте сочетание клавиш (".-R). Затем попробуйте воспользоваться интерфейсом чата на симуляторе:

Выберите "Начать работу".
Клиент чата присоединится к потоку чата, и вы можете начать вводить и отправлять сообщения.
Если клиент не может присоединиться к потоку, и вы chatJoin видите сбои, убедитесь, что маркер доступа пользователя действителен и что пользователь был добавлен в поток чата по вызову REST API или с помощью интерфейса командной строки az.

Анимация GIF, демонстрирующая окончательный внешний вид и ощущение приложения iOS для быстрого запуска.

Очистка ресурсов

Если вы хотите отменить и удалить подписку на Службы коммуникации, можно удалить ресурс или группу ресурсов.

При удалении группы ресурсов также удаляются все связанные с ней ресурсы.

См. сведения об очистке ресурсов.

Поделиться через

Краткое руководство. Добавление чата с библиотекой пользовательского интерфейса

Необходимые компоненты

Вы можете получить доступ к следующим кратким руководствам.

Необходимые компоненты

Настройка проекта

Создание нового проекта Android

Установка пакетов

Добавление зависимости

Добавление репозиториев Maven

Добавление кнопки для activity_main.xml

Инициализация составного

Выполнение кода

Необходимые компоненты

Настройка проекта

Создание проекта Xcode

Установка пакета и зависимостей

Отключение bitcode

Инициализация составного

Выполнение кода

Очистка ресурсов

Обратная связь

Дополнительные ресурсы