التشغيل السريع: إضافة دردشة باستخدام مكتبة واجهة المستخدم

مقالة
03/25/2023

ابدأ مع مكتبة واجهة مستخدم Azure Communication Services لدمج تجارب الاتصال بسرعة في تطبيقاتك. في هذا التشغيل السريع، تعرف على كيفية دمج المكونات المركبة لدردشة مكتبة واجهة المستخدم في أحد التطبيقات وإعداد التجربة لمستخدمي التطبيق.

تقدم مكتبة واجهة مستخدم خدمات الاتصالات تجربة دردشة كاملة مباشرة في تطبيقك. ويهتم بالاتصال بخدمات الدردشة في Azure Communication Services، ويحدث حالة حضور المشارك تلقائيا. بصفتك مطورا، يجب أن تقلق بشأن المكان الذي تريد فيه تشغيل تجربة الدردشة في تجربة مستخدم تطبيقك وإنشاء موارد Azure Communication Services فقط كما هو مطلوب.

إشعار

للحصول على وثائق مفصلة وقوالب تشغيل سريعة حول مكتبة واجهة مستخدم الويب، تفضل بزيارة دفتر قصة مكتبة واجهة مستخدم الويب.

المتطلبات الأساسية

حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
تم نشر مورد Communication Services. إنشاء مورد Communication Services
الرمز المميز لخدمات الاتصالات في Azure. انظر المثال

يمكنك الوصول إلى قوالب التشغيل السريع التالية

يمكنك الوصول إلى الكتب القصصية التالية

هام

هذه الميزة من Azure Communication Services قيد المعاينة حاليا.

يتم توفير واجهات برمجة التطبيقات وSDKs للمعاينة دون اتفاقية على مستوى الخدمة. نوصي بعدم استخدامها لأحمال عمل الإنتاج. قد لا تكون بعض الميزات مدعومة، أو قد تكون لها قدرات مقيدة.

لمزيد من المعلومات، راجع شروط الاستخدام التكميلية لمعاينات Microsoft Azure.

احصل على نموذج تطبيق Android لهذا التشغيل السريع في مصدر مفتوح مكتبة واجهة مستخدم Azure Communication Services لنظام التشغيل Android.

المتطلبات الأساسية

حساب Azure واشتراك Azure نشط. أنشئ حساباً مجاناً.
شغل نظام التشغيل فيAndroid Studio.
مورد Azure Communication Services المنشور، لاحظ عنوان URL لنقطة النهاية.
رمز مميز للوصول إلى Azure Communication Services ومعرف المستخدم.
تمت إضافة مؤشر ترابط دردشة Azure Communication Services مع المستخدم أعلاه إليه.

إعداد المشروع

أكمل الأقسام التالية لإعداد مشروع التشغيل السريع.

قم بإنشاء مشروع Android جديد

في Android Studio، أنشئ مشروعا جديدا:

في القائمة ملف، حدد مشروع جديد جديد>.
في New Project، حدد قالب مشروع Empty Activity .
حدد التالي.
في نشاط فارغ، قم بتسمية المشروع 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و accessToken acsIdentitydisplayNameو و.ThreadId استبدل endpoint بعنوان URL للمورد الخاص بك كما هو مقدم من Azure Communication Services. استبدل acsIdentity و accessToken بالقيم التي توفرها Azure Communication Services عند إنشاء رمز الوصول المميز واستخدم displayName ذي الصلة. استبدل ThreadId بالقيمة التي تم إرجاعها عند إنشاء مؤشر الترابط. تذكر إضافة المستخدم إلى مؤشر الترابط عبر استدعاء REST API، أو عميل واجهة سطر الأوامر az قبل محاولة تشغيل نموذج البدء السريع أو سيتم رفض وصول العميل للانضمام إلى مؤشر الترابط.

كوتلين
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، أنشئ التطبيق وابدأ تشغيله:

حدد بدء التجربة.
سينضم عميل الدردشة إلى مؤشر ترابط الدردشة ويمكنك البدء في كتابة الرسائل وإرسالها
إذا لم يتمكن العميل من الانضمام إلى مؤشر الترابط، وشاهدت أخطاء فشل chatJoin، فتحقق من أن الرمز المميز للوصول للمستخدم صالح وأن المستخدم قد تمت إضافته إلى مؤشر ترابط الدردشة بواسطة استدعاء REST API، أو باستخدام az واجهة سطر الأوامر.

الرسوم المتحركة ل GIF التي تعرض مثالا على كيفية تشغيل المشروع على جهاز Android.

هام

هذه الميزة من Azure Communication Services قيد المعاينة حاليا.

لمزيد من المعلومات، راجع شروط الاستخدام التكميلية لمعاينات Microsoft Azure.

احصل على نموذج تطبيق iOS لهذا التشغيل السريع في مصدر مفتوح مكتبة واجهة مستخدم Azure Communication Services لنظام التشغيل iOS.

المتطلبات الأساسية

حساب Azure واشتراك Azure نشط. أنشئ حساباً مجاناً.
جهاز Mac يعمل ب Xcode 13 أو أحدث وشهادة مطور صالحة مثبتة في سلسلة المفاتيح. ينبغي أيضًا تركيب CocoaPods لإحضار التبعيات.
مورد Azure Communication Services المنشور، لاحظ عنوان URL لنقطة النهاية.
رمز مميز للوصول إلى Azure Communication Services ومعرف المستخدم.
مؤشر ترابط دردشة Azure Communication Services وأضف الآن المستخدم الذي قمت بإنشائه في الخطوة الأخيرة إلى مؤشر ترابط الدردشة هذا.

إعداد المشروع

أكمل الأقسام التالية لإعداد مشروع التشغيل السريع.

إنشاء مشروع 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، ضمن Build Settings، قم بتعيين الخيار Enable Bitcode إلى No. للعثور على الإعداد، قم بتغيير عامل التصفية من أساسي إلى الكل أو استخدم شريط البحث.

لقطة شاشة تعرض خيار Build Settings لإيقاف تشغيل Bitcode.

تهيئة المركب

لتهيئة المركب:

انتقل إلى 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 للتشغيل السريع.

تنظيف الموارد

إذا كنت ترغب في تنظيف وإزالة اشتراك Communication Services، يمكنك حذف المورد أو مجموعة الموارد.

يؤدي حذف مجموعة الموارد إلى حذف أية موارد أخرى مقترنة بها أيضًا.

تعرّف على المزيد حول تنظيف الموارد.

مشاركة عبر

التشغيل السريع: إضافة دردشة باستخدام مكتبة واجهة المستخدم

المتطلبات الأساسية

يمكنك الوصول إلى قوالب التشغيل السريع التالية

يمكنك الوصول إلى الكتب القصصية التالية

المتطلبات الأساسية

إعداد المشروع

قم بإنشاء مشروع Android جديد

قم بتثبيت الحِزَم

إضافة تبعية

إضافة مستودعات Maven

إضافة زر إلى activity_main.xml

تهيئة المركب

تشغيل التعليمات البرمجية

المتطلبات الأساسية

إعداد المشروع

إنشاء مشروع Xcode جديد

تثبيت الحزمة والتبعيات

إيقاف تشغيل Bitcode

تهيئة المركب

تشغيل التعليمات البرمجية

تنظيف الموارد

الملاحظات

الموارد الإضافية