التشغيل السريع: إضافة دردشة باستخدام مكتبة واجهة المستخدم
ابدأ مع مكتبة واجهة مستخدم 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
acsIdentity
displayName
و و.ThreadId
استبدلendpoint
بعنوان URL للمورد الخاص بك كما هو مقدم من Azure Communication Services. استبدلacsIdentity
وaccessToken
بالقيم التي توفرها Azure Communication Services عند إنشاء رمز الوصول المميز واستخدم displayName ذي الصلة. استبدلThreadId
بالقيمة التي تم إرجاعها عند إنشاء مؤشر الترابط. تذكر إضافة المستخدم إلى مؤشر الترابط عبر استدعاء REST API، أو عميل واجهة سطر الأوامر az قبل محاولة تشغيل نموذج البدء السريع أو سيتم رفض وصول العميل للانضمام إلى مؤشر الترابط.
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()
}
}
}
تشغيل التعليمات البرمجية
في Android Studio، أنشئ التطبيق وابدأ تشغيله:
- حدد بدء التجربة.
- سينضم عميل الدردشة إلى مؤشر ترابط الدردشة ويمكنك البدء في كتابة الرسائل وإرسالها
- إذا لم يتمكن العميل من الانضمام إلى مؤشر الترابط، وشاهدت أخطاء فشل chatJoin، فتحقق من أن الرمز المميز للوصول للمستخدم صالح وأن المستخدم قد تمت إضافته إلى مؤشر ترابط الدردشة بواسطة استدعاء REST API، أو باستخدام
az
واجهة سطر الأوامر.
هام
هذه الميزة من Azure Communication Services قيد المعاينة حاليا.
يتم توفير واجهات برمجة التطبيقات وSDKs للمعاينة دون اتفاقية على مستوى الخدمة. نوصي بعدم استخدامها لأحمال عمل الإنتاج. قد لا تكون بعض الميزات مدعومة، أو قد تكون لها قدرات مقيدة.
لمزيد من المعلومات، راجع شروط الاستخدام التكميلية لمعاينات 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. للعثور على الإعداد، قم بتغيير عامل التصفية من أساسي إلى الكل أو استخدم شريط البحث.
تهيئة المركب
لتهيئة المركب:
انتقل إلى
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.
تنظيف الموارد
إذا كنت ترغب في تنظيف وإزالة اشتراك Communication Services، يمكنك حذف المورد أو مجموعة الموارد.
يؤدي حذف مجموعة الموارد إلى حذف أية موارد أخرى مقترنة بها أيضًا.
تعرّف على المزيد حول تنظيف الموارد.