إضافة ميزات ذات صلة بالمحادثة إلى تطبيق Android باستخدام واجهتَي برمجة تطبيقات المراسلة والأشخاص

1. قبل البدء

يصعب إنشاء تطبيق مراسلة، وعلى الرغم من أنّ تجربة المستخدم الشاملة هي تجربة ذاتية، يوفّر نظام التشغيل Android واجهتَي برمجة التطبيقات Messaging API وPeople API اللتين تعملان على تحسين تجربة المحادثة وتبسيطها.

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام واجهات برمجة التطبيقات هذه لإنشاء نظام متكامل جذاب لتطبيقات الدردشة على Android. يمكنك توسيع تطبيق JetChat، وهو تطبيق محادثات بسيط وغير وظيفي يستخدم Jetpack Compose.

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

معرفة أساسية بتطوير تطبيقات Android
معرفة أساسية بالإشعارات

ما ستنشئه

تطبيق JetChat موسّع ينفّذ ما يلي:

تعرض هذه الفئة الإشعارات التي تمثّل المحادثات في قسم المحادثات المحجوز في درج الإشعارات.
تتضمّن الإشارات أهداف المشاركة في هذه الإشعارات التي تتيح لك المشاركة في محادثات تطبيقك.
يفرض هذا الإعداد أفضل الممارسات لإنشاء هذه العناصر للاستفادة من التجارب التلقائية التي يوفّرها النظام والتي تعمل على تحسين تطبيقك.

ما ستتعلمه

كيفية عرض الإشعارات المتعلقة بالمحادثات في قسم المحادثات المحفوظة في لوحة الإشعارات
كيفية فهم التجارب المختلفة التي تتيحها واجهات برمجة التطبيقات "المراسلة" و"الأشخاص"

المتطلبات

Git
استوديو Android
حساب على GitHub

2. طريقة الإعداد

تستند نقطة البداية إلى تطبيق JetChat. يوسّع الرمز البرمجي الأولي تطبيق JetChat لعرض Messaging API وPeople API بشكل أفضل.

الحصول على الرمز الأوّلي

للحصول على الرمز الأولي لهذا الدرس العملي، اتّبِع الخطوات التالية:

من سطر الأوامر، استنسِخ مستودع GitHub التالي:

git clone –branch starter-code \
https://github.com/android/people-messaging-codelab.git

افتح المشروع في "استوديو Android"، ثم انقر على تشغيل التطبيق. يظهر جزء المحاكي ويعرض التطبيق.

استكشاف تطبيق JetChat الموسّع

في مربّع النص أدوات إنشاء الرسائل في التطبيق، أدخِل رسالة، ثم انقر على إرسال.
انتقِل إلى تطبيق آخر. بعد بضع ثوانٍ، ستتلقّى إشعارًا فوريًا يتضمّن ردًا من أحد المشاركين في المحادثة.

3- إنشاء إشعارات المحادثات

قدّم نظام التشغيل Android 11 واجهات برمجة تطبيقات تتيح ظهور الإشعارات المرتبطة بالمحادثات في قسم مخصّص في لوحة الإشعارات، وهو مخصّص للمحادثات فقط.

قائمة الإشعارات التي تظهر عند التمرير سريعًا من شريط الحالة إلى أسفل

يجب أن يكون الإشعار من الفئة Notification.MessagingStyle وأن يشير إلى اختصار مشاركة قديم. في هذا القسم، ستتعرّف على كيفية استيفاء متطلبات واجهة برمجة التطبيقات هذه لعرض الإشعارات التي تمثّل المحادثات في قسم المحادثات.

لإعداد إشعارات من الفئة NotificationCompat.MessagingStyle، اتّبِع الخطوات التالية:

في علامة التبويب المشروع في "استوديو Android"، انقر على app > java > com.example.compose.jetchat > conversation ثم انقر مرّتين على ConversationFragment.
في ملف ConversationFragment.kt، ابحث عن الفئة ConversationFragment، ثم ابحث عن كتلة الرمز Notification الخاصة بالدالة createNotification حيث يتم إنشاء الإشعار.
استبدِل طريقة setContentText بطريقة setStyle تضبط نمط الإشعار على الفئة NotificationCompat.MessagingStyle. تضيف فئة المساعد هذه الرسالة التي تم ضبطها باستخدام الطريقة setContextText مع سياق إضافي ذي صلة بالرسالة، مثل وقت إرسالها والشخص الذي أرسلها.

ConversationFragment.kt

private fun createNotification(
   notificationId: Int,
   message: Message,
   person: Person,
   shortcut: ShortcutInfoCompat,
   time: Long
): Notification? {
    ...
    .setStyle(NotificationCompat.MessagingStyle(person).addMessage(
                      NotificationCompat.MessagingStyle.Message(
                          message.content,
                          time,
                          person
                      )
    )
    )
    ...
    .build()
}

تشغيل التطبيق

شغِّل التطبيق.
في مربّع النص أدوات إنشاء الرسائل في التطبيق، أدخِل رسالة، ثم انقر على إرسال.
انتقِل إلى تطبيق آخر. ستتلقّى إشعارًا فوريًا مرة أخرى، ولكن بتصميم مختلف. يتضمّن هذا النوع أفاتارًا وأسلوبًا مميزًا للرسالة. ومع ذلك، هناك المزيد من العمل الذي يجب إنجازه قبل أن تظهر إشعاراتك في المكان المناسب.

4. إنشاء أهداف مشاركة للمحادثات

يجب الإشارة إلى اختصار ميزة المشاركة أو هدف مشاركة في الإشعار. يتم تحديد أهداف المشاركة في ملف shortcuts.xml، وهي نقاط الدخول إلى معالجة الاختصارات التي يتم تحديدها آليًا. تمثّل الاختصارات التي تنشئها المحادثات في التطبيق، وتتيح لك مشاركة المحتوى في محادثاتك.

في علامة التبويب المشروع، انقر بزر الماوس الأيمن على الدليل res، ثم اختَر جديد > دليل.
في مربّع النص، أدخِل xml ثم اضغط على Enter (أو return على جهاز macOS).
انقر بزر الماوس الأيمن على الدليل xml، ثم اختَر ملف.
في مربّع النص، أدخِل shortcuts.xml ثم اضغط على Enter (أو return على جهاز macOS).
في ملف shortcuts.xml، عرِّف هدف المشاركة الذي يتعامل مع مشاركة البيانات من النوع text/plain:

shortcuts.xml

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <share-target android:targetClass="com.example.compose.jetchat.NavActivity">
   <data android:mimeType="text/plain" />
   <category android:name="com.example.compose.jetchat.share.TEXT_SHARE_TARGET" />
 </share-target>
</shortcuts>

في علامة التبويب المشروع، انقر على manifests، ثمّ انقر مرّتين على AndroidManifest.xml.
في ملف AndroidManifest.xml، حدِّد ملف shortcuts.xml:

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.compose.jetchat">

   <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/Theme.Jetchat.NoActionBar">
...
 <meta-data android:name="android.app.shortcuts"
            android:resource="@xml/shortcuts" />

    </application>
</manifest>

في المكوّن activity ضمن ملف AndroidManifest.xml، حدِّد فلتر intent الذي يحتوي على منطق المشاركة:

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
   package="com.example.compose.jetchat">

   ...
       <activity
           ...
           <intent-filter>
               <action android:name="android.intent.action.SEND" />
               <category android:name="android.intent.category.DEFAULT" />
               <data android:mimeType="text/plain" />
           </intent-filter>
...

تحديد الاختصارات

يجب ربط الاختصار المناسب بكل إشعار. يمكنك تحديد اختصار فريد واحد فقط لكل محادثة لأنّ الاختصار الفريد يمثّل جهة الاتصال الوحيدة التي ستتم المشاركة معها.

لإنشاء اختصار، اتّبِع الخطوات التالية:

في علامة التبويب المشروع، انقر على app > java > com.example.compose.jetchat > conversation > util، ثم انقر مرّتين على ConversationUtil.
في ملف ConversationUtil.kt، أضِف الدالة generateShortcut:

ConversationUtil.kt

import android.content.Intent
import androidx.core.content.pm.ShortcutInfoCompat
import com.example.compose.jetchat.NavActivity

class ConversationUtil {

   companion object {
...
fun generateShortcut(context: Context, shortcutId: String): ShortcutInfoCompat {
   return ShortcutInfoCompat.Builder(context, shortcutId)
   .setCategories(setOf(CATEGORY_SHARE))
   .setLongLived(true)
   .setShortLabel(shortcutId)
   .setLongLabel(shortcutId)
   .setIntent(
       Intent(context, NavActivity::class.java)
           .setAction(Intent.ACTION_VIEW)
   )
   .build()
}

تحتوي هذه الدالة على الطريقتَين setPerson وsetLongLived المطلوبتَين لإجراء محادثة. الشخص هو جهة الاتصال المرتبطة بالاختصار، ويضمن ضبط قيمة true على long-lived أن يخزّن النظام هذا الاختصار مؤقتًا وأن يظهره في مساحات عرض مختلفة في واجهة المستخدم.

الرجوع إلى الاختصار في الإشعار

يجب الإشارة إلى اختصار ميزة المشاركة في الإشعار. ومع ذلك، يجب إنشاء الاختصار قبل إرسال الإشعار.

ولإجراء ذلك، اتبع الخطوات التالية:

في ملف ConversationFragment.kt، ابحث عن فئة ConversationFragment.
قبل استدعاء المتغيّر notification، أنشئ المتغيّر shortcut الذي يشير إلى الاختصار الذي تم إنشاؤه من ConversationUtil.generateShortcut.
في طريقة createNotification للمتغيّر notification، استبدِل null بالمتغيّر shortcut كمَعلمة.

ConversationFragment.kt

private fun simulateResponseAsANotification() {
   ...
   if (message.author != "me") {
       ...
       val shortcut = ConversationUtil.generateShortcut(context!!, message.author)
       val notification = createNotification(notificationId, message, person, shortcut, time)
       ...
   }
}

في الطريقة createNotification، أضِف الطريقة NotificationCompat.Builder#setShortcutInfo، ثم مرِّر المتغيّر shortcut كمَعلمة.

ConversationFragment.kt

private fun createNotification(
  notificatoinIf: Int,
  messagin: Message,
  person: Person,
  shortcut: ShortcutInfoCompat?,
  time: Long
): Notification {
...
return NotificationCompat.Builder(context!!,  ConversationUtil.CHANNEL_MESSAGES)
   ...
   .setShortcutInfo(shortcut)
   .build()
}

نشر الاختصار

لنشر الاختصار، استدعِ طريقة pushDynamicShortcut في الدالة simulateResponseAsANotification قبل طريقة notificationManager.notify:

ConversationFragment.kt

import androidx.core.content.pm.ShortcutManagerCompat

...private fun simulateResponseAsANotification() {
   ...
   if (message.author != "me") {
       ...
       ShortcutManagerCompat.pushDynamicShortcut(context!!, shortcut)
       ...
   }
}

تشغيل التطبيق

شغِّل التطبيق.
في مربّع النص أدوات إنشاء الرسائل في التطبيق، أدخِل رسالة، ثم انقر على إرسال.
انتقِل إلى تطبيق آخر. ستتلقّى إشعارًا فوريًا مرة أخرى، ولكن سيتم تنسيقه بشكل أكثر تميزًا كإشعار متعلق بالمحادثة. رمز الأفاتار أكثر وضوحًا ويتضمّن رمز التطبيق. كما أنّ معلومات المُرسِل والوقت والنص أصبحت أكثر بساطة.

5- اختياري: تفعيل الفقاعات

تم طرح الفقاعات في نظام التشغيل Android 9، وتم تحسينها وإعادة استخدامها في سياق المحادثات في نظام التشغيل Android 11. الفقاعات هي تراكبات دائرية تمثّل صور الأفاتار لمحادثاتك. تظهر هذه الفقاعات في مشغّل التطبيقات، وتتيح لك الردّ بسهولة على المحادثات في فقاعة موسّعة. حتى عند تفعيل الفقاعات، تكون اختيارية حسب تفضيلات المستخدم.

لتفعيل الفقاعات، اتّبِع الخطوات التالية:

في ملف AndroidManifest.xml، أضِف السمتَين allowEmbedded وresizeableActivity، ثم اضبط كلّ سمة على القيمة true:

AndroidManifest.xml

<activity
  ...
  android:allowEmbedded="true"
  android:resizeableActivity="true"
  ...
</activity>

في فئة ConversationUtil بملف ConversationUtil.kt، أضِف البيانات الوصفية للفقاعة:

ConversationUtil.kt

import androidx.core.app.NotificationCompat
import androidx.core.graphics.drawable.IconCompat


fun createBubbleMetadata(context: Context, icon: IconCompat): NotificationCompat.BubbleMetadata {
        // Create bubble intent
        val target = Intent(context, NavActivity::class.java)
        val bubbleIntent = PendingIntent.getActivity(context, REQUEST_BUBBLE, target, flagUpdateCurrent(mutable = true))

        // Create bubble metadata
        return NotificationCompat.BubbleMetadata.Builder(bubbleIntent, icon)
            .setDesiredHeight(400)
            .setSuppressNotification(true)
            .build()
    }

في ملف ConversationFragment.kt، أنشئ البيانات الوصفية للفقاعة وأشِر إليها في الإشعار:

ConversationFragment.kt

private fun createNotification(
  notificatoinIf: Int,
  messagin: Message,
  person: Person,
  shortcut: ShortcutInfoCompat?,
  time: Long
): Notification {
...
// Reference the bubble metadata in the notification.
  return NotificationCompat.Builder(context!!,     ConversationUtil.CHANNEL_MESSAGES)
    ...
     .setBubbleMetadata(ConversationUtil.createBubbleMetadata(context!!, person.icon!!))
...
    .build()
}

تشغيل التطبيق

شغِّل التطبيق.
في مربّع النص أدوات إنشاء الرسائل في التطبيق، أدخِل رسالة، ثم انقر على إرسال.
انتقِل إلى تطبيق آخر. بعد بضع ثوانٍ، ستتلقّى إشعارًا من المحادثة في شكل فقاعة.
انقر على الفقاعة. يتم فتح المحادثة من الفقاعة.

فقاعة محادثة

6. اختياري: مشاركة رابط

لقد حدّدت أهداف المشاركة وأشرت إليها في إشعاراتك، ما أتاح أيضًا عرض جهة الاتصال في قائمة مشاركة البيانات، وهي مكوّن من الأسفل إلى الأعلى يظهر عند إرسال intent ACTION. تظهر أهداف المشاركة في أعلى قائمة مشاركة البيانات، وتتيح لك مشاركة محتوى وافٍ في محادثاتك.

لاستدعاء قائمة مشاركة البيانات، اتّبِع الخطوات التالية:

على جهازك، افتح Google Chrome، ثم انتقِل إلى صفحة ويب من اختيارك، مثل developer.android.com.
إذا لزم الأمر، انقر على رمز المزيد.
انقر على رمز المشاركة . تظهر قائمة مشاركة البيانات في أسفل الشاشة.

قائمة مشاركة البيانات

انقر على JetChat إذا كان ذلك ممكنًا. تتم مشاركة عنوان URL في المحادثة.
إذا لم يظهر لك JetChat، انقر على المزيد لاستدعاء ورقة المشاركة في النظام، ثم مرِّر سريعًا للأعلى على ورقة المشاركة وانقر على JetChat. تتم مشاركة عنوان URL في المحادثة.

هذا مثال بسيط. تتوفّر أنواع أكثر ثراءً من المحتوى لمشاركته. لمزيد من المعلومات، يُرجى الاطّلاع على استرداد البيانات البسيطة من التطبيقات الأخرى.

7. تهانينا

تهانينا! أصبحت الآن تعرف كيفية إضافة ميزات متعلقة بالمحادثات إلى تطبيق Android باستخدام Messaging API وPeople API. نتمنّى لك تجربة مراسلة ممتعة!