Démarrage rapide : Ajouter une conversation avec la bibliothèque d’interface utilisateur

  • Article

Découvrez comment bien démarrer avec la bibliothèque d’interface utilisateur Azure Communication Services pour intégrer rapidement des expériences de communication à vos applications. Dans ce guide de démarrage rapide, découvrez comment intégrer des composites de conversation de bibliothèque d’interface utilisateur à une application et configurer l’expérience pour les utilisateurs de votre application.

La bibliothèque d’interface utilisateur Communication Services affiche une expérience de conversation complète directement dans votre application. Elle prend en charge la connexion aux services de conversation Azure Communication Services et met automatiquement à jour la présence des participants. En tant que développeur, vous devez vous soucier de l’emplacement où, dans l’expérience utilisateur de votre application, vous souhaitez que l’expérience de conversation soit lancée, et créer uniquement les ressources Azure Communication Services en fonction des besoins.

Remarque

Pour obtenir une documentation détaillée et des démarrages rapides sur la bibliothèque d’interface utilisateur web, consultez le Storybook de la bibliothèque d’interface utilisateur web.

Prérequis

Vous pouvez accéder aux démarrages rapides suivants

Important

Cette fonctionnalité d’Azure Communication Services est actuellement en préversion.

Ces interfaces de programmation d’applications et kits de développement logiciel (SDK) en préversion sont fournis sans contrat au niveau du service. Nous vous recommandons de ne pas les utiliser pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge.

Pour plus d’informations, consultez Conditions d’utilisation supplémentaires relatives aux préversions de Microsoft Azure.

Obtenez l’exemple d’application Android pour ce guide de démarrage rapide dans la bibliothèque d’interface utilisateur pour Android open source Azure Communication Services.

Prérequis

Configuration du projet

Effectuez les étapes des sections suivantes pour configurer le projet de démarrage rapide.

Créer un projet Android

Dans Android Studio, créez un projet :

  1. Dans le menu Fichier, sélectionnez Nouveau>Nouveau projet.

  2. Dans Nouveau projet, sélectionnez le modèle de projet Activité vide.

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

  3. Cliquez sur Suivant.

  4. Dans Activité vide, nommez le projet UILibraryQuickStart. Pour le langage, sélectionnez Java/Kotlin. Pour le kit de développement logiciel (SDK) minimal, sélectionnez API 23 : Android 6.0 (Marshmallow) ou une version ultérieure.

  5. Cliquez sur Terminer.

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

Installer les packages

Effectuez les étapes des sections suivantes pour installer les packages d’application nécessaires.

Ajouter une dépendance

Dans votre fichier UILibraryQuickStart/app/build.gradle au niveau de l’application (dans le dossier de l’application), ajoutez la dépendance suivante :

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

Ajouter des référentiels Maven

Le référentiel de packages Azure est requis pour intégrer la bibliothèque :

Pour ajouter le référentiel :

  1. Dans vos scripts Gradle de projet, vérifiez que les dépôts suivants sont ajoutés. Pour Android Studio (2020.*), repositories se trouve dans settings.gradle, sous dependencyResolutionManagement(Gradle version 6.8 or greater). Pour les versions antérieures d’Android Studio (4.*), repositories se trouve dans build.gradle au niveau du projet, sous allprojects{}.

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

  2. Synchronisez votre projet avec les fichiers Gradle. Pour synchroniser le projet, dans le menu Fichier, sélectionnez Synchroniser le projet avec les fichiers Gradle.

Ajouter un bouton à activity_main.xml

Dans le fichier de disposition app/src/main/res/layout/activity_main.xml, ajoutez le code suivant pour créer un bouton destiné à démarrer le composite :

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

Initialiser le composite

Pour initialiser le composite :

  1. Accédez à MainActivity.

  2. Ajoutez le code suivant afin d’initialiser nos composants composites pour l’appel. Remplacez les valeurs de chaîne pour les propriétés (kotlin) ou les fonctions (java) pour endpoint, acsIdentity, displayName, accessToken et ThreadId. Remplacez endpoint par l’URL de votre ressource telle que fournie par Azure Communication Services. Remplacez acsIdentity et accessToken par les valeurs fournies par Azure Communication Services lorsque vous avez créé le jeton d’accès et utilisez un displayName approprié. Remplacez ThreadId par la valeur obtenue lorsque vous avez créé le thread. N’oubliez pas d’ajouter l’utilisateur au thread par le biais d’un appel d’API REST ou du client d’interface de ligne de commande az avant d’essayer d’exécuter l’exemple de démarrage rapide, sinon l’accès au client sera refusé pour rejoindre le 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()
        }
    }
}

Exécuter le code

Dans Android Studio, générez et démarrez l’application :

  1. Sélectionnez Démarrer l’expérience.
  2. Le client de conversation rejoint le thread de conversation et vous pouvez commencer à taper et à envoyer des messages
  3. Si le client n’est pas en mesure de rejoindre le thread et que vous voyez des erreurs d’échec chatJoin, vérifiez que le jeton d’accès de votre utilisateur est valide et que l’utilisateur a été ajouté au thread de conversation par appel d’API REST ou à l’aide de l’interface de ligne de commande az.

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

Important

Cette fonctionnalité d’Azure Communication Services est actuellement en préversion.

Ces interfaces de programmation d’applications et kits de développement logiciel (SDK) en préversion sont fournis sans contrat au niveau du service. Nous vous recommandons de ne pas les utiliser pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge.

Pour plus d’informations, consultez Conditions d’utilisation supplémentaires relatives aux préversions de Microsoft Azure.

Obtenez l’exemple d’application IOS pour ce guide de démarrage rapide dans la bibliothèque d’interface utilisateur pour IOS open source Azure Communication Services.

Prérequis

  • Un compte Azure et un abonnement Azure actif. Créez un compte gratuitement.
  • Un Mac exécutant Xcode 13+ ou version ultérieure, ainsi qu’un certificat de développeur valide installé dans votre trousseau. CocoaPods doit également être installé pour permettre la récupération des dépendances.
  • Une ressource Azure Communication Services déployée, notez l’URL du point de terminaison.
  • Un jeton d’accès Azure Communication Services et un identificateur d’utilisateur.
  • Un thread de conversation Azure Communication Services, ajoutez maintenant l’utilisateur que vous avez créé à la dernière étape à ce thread de conversation.

Configuration du projet

Effectuez les étapes des sections suivantes pour configurer le projet de démarrage rapide.

Créer un nouveau projet Xcode

Dans Xcode, créez un nouveau projet :

  1. Dans le menu Fichier, sélectionnez Nouveau>projet.

  2. Dans Choisir un modèle pour votre nouveau projet, sélectionnez la plateforme iOS et sélectionnez le modèle d’application Application . Le guide de démarrage rapide utilise les plans conceptuels UIKit.

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

  3. Dans Choisir les options de votre nouveau projet, pour le nom du produit, entrez UILibraryQuickStart. Dans le champ Interface, sélectionnez Plan conceptuel. Le guide de démarrage rapide ne crée pas de tests. Vous pouvez donc décochez la case Inclure les tests .

    Screenshot that shows setting new project options in Xcode.

Installez le package et ses dépendances

  1. (Facultatif) Pour Mackbook avec M1, installez et activez Rosetta dans Xcode.

  2. Dans le répertoire racine de votre projet, exécutez pod init pour créer un Podfile. Si vous rencontrez une erreur, mettez à jour CocoaPods vers la version actuelle.

  3. Ajoutez le code suivant à votre Podfile. Remplacez UILibraryQuickStart par votre nom de projet.

    platform :ios, '14.0'

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

  4. Exécutez pod install --repo-update.

  5. Dans Xcode, ouvrez le fichier xcworkspace généré.

Désactiver Bitcode

Dans le projet Xcode, sous Paramètres de génération, définissez l’option Activer Bitcode sur Non. Pour rechercher le paramètre, remplacez le filtre De base par Tout ou utilisez la barre de recherche.

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

Initialiser le composite

Pour initialiser le composite :

  1. Accédez à ViewController.

  2. Ajoutez le code suivant afin d’initialiser vos composants composites pour une conversation. Remplacez <USER_ID> par l’identificateur d’utilisateur. Remplacez <USER_ACCESS_TOKEN> par votre jeton d’accès. Remplacez <ENDPOINT_URL> par votre URL de point de terminaison. Remplacez <THREAD_ID> par votre ID de thread de conversation. Remplacez <DISPLAY_NAME> par votre nom. (La limite de longueur de chaîne pour <DISPLAY_NAME> est de 256 caractères).

    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 vous choisissez de placer l’affichage de conversation dans un cadre inférieur à la taille de l’écran, la largeur minimale recommandée est de 250 et la hauteur minimale recommandée est de 300.

Exécuter le code

Générez et exécutez votre application sur le simulateur iOS en sélectionnant Produit>Exécuter ou en utilisant le raccourci clavier (⌘-R). Testez ensuite l’expérience de conversation sur le simulateur :

  1. Sélectionnez Démarrer l’expérience.
  2. Le client de conversation rejoint le thread de conversation et vous pouvez commencer à taper et à envoyer des messages.
  3. Si le client n’est pas en mesure de rejoindre le thread et que vous voyez des erreurs d’échec chatJoin, vérifiez que le jeton d’accès de votre utilisateur est valide et que l’utilisateur a été ajouté au thread de conversation par appel de l’API REST ou à l’aide de l’interface de ligne de commande az.

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

Nettoyer les ressources

Si vous voulez nettoyer et supprimer un abonnement Communication Services, vous pouvez supprimer la ressource ou le groupe de ressources.

La suppression du groupe de ressources efface également les autres ressources qui y sont associées.

Apprenez-en davantage sur le nettoyage des ressources.