با استفاده از Messaging و People API ویژگی‌های مربوط به چت را به برنامه Android اضافه کنید

۱. قبل از شروع

ساخت یک اپلیکیشن پیام‌رسان چالش‌برانگیز است. اگرچه تجربه کلی کاربر سلیقه‌ای است، اندروید APIهای Messaging و People را ارائه می‌دهد که تجربه چت را بهبود بخشیده و ساده می‌کنند.

در این آزمایشگاه کد، یاد می‌گیرید که چگونه از این APIها برای ایجاد یک اکوسیستم جذاب برای برنامه‌های چت در اندروید استفاده کنید. شما برنامه JetChat ، یک برنامه چت ساده و غیر کاربردی که از Jetpack compose استفاده می‌کند را گسترش می‌دهید.

پیش‌نیازها

• دانش پایه در توسعه اندروید
• آشنایی اولیه با اعلان‌ها

آنچه خواهید ساخت

یک برنامه توسعه‌یافته JetChat که موارد زیر را انجام می‌دهد:

• اعلان‌هایی که نشان‌دهنده‌ی مکالمات هستند را در بخش مکالمه‌ی رزرو شده‌ی کشوی اعلان‌ها نمایش می‌دهد.
• منابع در این اعلان‌ها اهداف مشترکی دارند که به شما امکان می‌دهند در مکالمات برنامه خود به اشتراک بگذارید.
• بهترین شیوه‌ها را برای ایجاد این اشیاء اعمال می‌کند تا از تجربیات پیش‌فرض ارائه شده توسط سیستم که برنامه شما را بهبود می‌بخشد، بهره ببرد.

آنچه یاد خواهید گرفت

• نحوه نمایش اعلان‌های مربوط به مکالمه در بخش مکالمه رزرو شده از کشوی اعلان‌ها.
• چگونه می‌توان تجربیات مختلفی را که توسط APIهای پیام‌رسانی و افراد فراهم می‌شود، درک کرد.

آنچه نیاز دارید

• گیت
• اندروید استودیو
• یک حساب کاربری گیت‌هاب

۲. آماده شوید

نقطه شروع بر اساس برنامه JetChat است. کد آغازین، برنامه JetChat را بسط می‌دهد تا APIهای پیام‌رسانی و افراد را بهتر نمایش دهد.

کد شروع را دریافت کنید

برای دریافت کد شروع این codelab، مراحل زیر را دنبال کنید:

1. از خط فرمان خود، مخزن GitHub زیر را کلون کنید:

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

2. پروژه را در اندروید استودیو باز کنید و سپس روی ... کلیک کنید. برنامه را اجرا کنید . پنجره شبیه‌ساز ظاهر می‌شود و برنامه را نمایش می‌دهد.

برنامه توسعه یافته JetChat را کاوش کنید

1. در کادر متنی Message #composers برنامه، پیامی را وارد کنید و سپس روی «ارسال» ضربه بزنید.
2. از برنامه خارج شوید. پس از چند ثانیه، یک اعلان دریافت می‌کنید که حاوی پاسخی از طرف یکی از افراد حاضر در چت است.

توجه: پاسخ از یک شخص واقعی نیست. این برنامه طوری برنامه‌ریزی شده است که برای شبیه‌سازی یک تجربه چت، پاسخ دهد.

۳. اعلان‌های مکالمه ایجاد کنید

اندروید ۱۱ رابط‌های برنامه‌نویسی کاربردی (API) را معرفی کرد که به اعلان‌های مربوط به چت اجازه می‌دهد در بخش مشخصی در کشوی اعلان‌ها ظاهر شوند، که منحصراً برای مکالمات است.

اعلان باید از کلاس Notification.MessagingStyle باشد و به یک میانبر اشتراک‌گذاری با طول عمر بالا ارجاع دهد. در این بخش، یاد می‌گیرید که چگونه این الزامات API را برای نمایش این اعلان‌ها که نشان‌دهنده مکالمات در بخش مکالمه هستند، برآورده کنید.

برای ایجاد اعلان‌ها (notifications) از کلاس NotificationCompat.MessagingStyle ، مراحل زیر را دنبال کنید:

1. در تب Project در اندروید استودیو، روی app > java > com.example.compose.jetchat > conversation کلیک کنید و سپس روی ConversationFragment دوبار کلیک کنید.
2. در فایل ConversationFragment.kt ، کلاس ConversationFragment را پیدا کنید و سپس بلوک کد Notification تابع createNotification را که اعلان در آن ایجاد شده است، بیابید.
3. متد 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()
}

برنامه را اجرا کنید

1. برنامه را اجرا کنید.
2. در کادر متنی Message #composers برنامه، پیامی را وارد کنید و سپس روی «ارسال» ضربه بزنید.
3. از برنامه خارج شوید. دوباره یک اعلان دریافت می‌کنید، اما با سبکی متفاوت. شامل یک آواتار و سبکی متمایز برای پیام است. با این حال، قبل از اینکه اعلان‌های شما در جای مناسب خود ظاهر شوند، کارهای بیشتری باید انجام دهید.

۴. برای مکالمات، اهداف اشتراک‌گذاری ایجاد کنید

شما باید در اعلان، به یک میانبر اشتراک‌گذاری یا هدف اشتراک‌گذاری ارجاع دهید. اهداف اشتراک‌گذاری در فایل shortcuts.xml تعریف شده‌اند و نقاط ورودی برای مدیریت میانبرهایی هستند که به صورت برنامه‌نویسی تعریف شده‌اند. میانبرهایی که ایجاد می‌کنید، نشان‌دهنده مکالمات موجود در برنامه هستند و به شما امکان می‌دهند محتوا را در مکالمات خود به اشتراک بگذارید.

نکته: شما اهداف اشتراک‌گذاری مخصوص پیام‌های ورودی ایجاد می‌کنید که به صورت اعلان در دستگاه کاربر نمایش داده می‌شوند. همچنین باید اهداف اشتراک‌گذاری را برای پیام‌های خروجی ایجاد کنید، اما در این آزمایشگاه کد به آنها پرداخته نمی‌شود. با این حال، همان مراحل و نمونه‌های کدی که برای اهداف اشتراک‌گذاری برای پیام‌های ورودی اعمال می‌شوند، برای اهداف اشتراک‌گذاری برای پیام‌های خروجی نیز اعمال می‌شوند.

اهداف اشتراک‌گذاری را تعریف کنید

1. در تب Project ، روی دایرکتوری res کلیک راست کرده و سپس New > Directory را انتخاب کنید.
2. در کادر متن، xml را وارد کنید و سپس Enter (یا return در macOS) را فشار دهید.
3. روی پوشه xml کلیک راست کرده و سپس File را انتخاب کنید.
4. در کادر متن، عبارت shortcuts.xml را وارد کنید و سپس Enter (یا return در macOS) را فشار دهید.
5. در فایل shortcuts.xml ، هدف اشتراک‌گذاری را که اشتراک‌گذاری داده‌های از نوع text/plain را مدیریت می‌کند، تعریف کنید:

میانبرها.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>

6. در تب Project ، روی manifests کلیک کنید و سپس روی AndroidManifest.xml دوبار کلیک کنید.
7. در فایل 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>

8. در کامپوننت 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>
...

تعریف کلیدهای میانبر

برای هر اعلان، باید میانبر مربوطه را مرتبط کنید. شما فقط یک میانبر منحصر به فرد برای هر مکالمه تعریف می‌کنید زیرا میانبر منحصر به فرد نشان دهنده یک مخاطب است که باید با آن به اشتراک گذاشته شود.

برای ایجاد میانبر، مراحل زیر را دنبال کنید:

1. در تب Project ، روی app > java > com.example.compose.jetchat > conversation > util کلیک کنید و سپس روی ConversationUtil دوبار کلیک کنید.
2. در فایل 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 مورد نیاز برای مکالمه است. person مخاطب مرتبط با میانبر است و تنظیم long-lived روی مقدار true تضمین می‌کند که این میانبر توسط سیستم ذخیره شده و در سطوح مختلف رابط کاربری نمایش داده می‌شود.

به میانبر در اعلان مراجعه کنید

توجه: اهداف اشتراک‌گذاری منتشر شده برای پیام‌های خروجی به اعلان محدود نمی‌شوند زیرا پیام‌های خروجی معمولاً برای کاربری که پیام را ارسال می‌کند، اعلانی ایجاد نمی‌کنند.

شما باید در اعلان، به میانبر اشتراک‌گذاری اشاره کنید. با این حال، قبل از ارسال اعلان، باید میانبر را ایجاد کنید.

برای انجام این کار، این مراحل را دنبال کنید:

1. در فایل ConversationFragment.kt ، کلاس ConversationFragment را پیدا کنید.
2. قبل از فراخوانی متغیر notification ، یک متغیر shortcut ایجاد کنید که به میانبر تولید شده از ConversationUtil.generateShortcut اشاره کند.
3. در متد 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)
       ...
   }
}

4. در متد 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()
}

نکته: متد NotificationCompat.Builder#setShortcutInfo همچنین کلاس LocusId را روی میانبر تنظیم می‌کند، که اکیداً توصیه می‌شود. اگر سپس Activity مرتبط را با کلاس LocusId حاشیه‌نویسی کنید، سیگنال‌هایی را به هوش دستگاه ارسال می‌کنید که میانبر با آن مکالمه مرتبط است. این سیگنال‌ها برای رتبه‌بندی مکالمه بر این اساس استفاده می‌شوند، که تضمین می‌کند این مکالمه را بر اساس فعالیت کاربر به درستی نمایش دهید. برای اطلاعات بیشتر، به بهترین شیوه‌ها مراجعه کنید.

توجه: اهداف اشتراک‌گذاری مختص مکالمات نیستند. آن‌ها می‌توانند خارج از مکالمات نیز وجود داشته باشند. برای کسب اطلاعات بیشتر در مورد اهداف اشتراک‌گذاری، به API میانبرهای اشتراک‌گذاری مراجعه کنید .

میانبر را منتشر کنید

• برای انتشار میانبر، در تابع simulateResponseAsANotification قبل از متد notificationManager.notify ، متد pushDynamicShortcut را فراخوانی کنید:

ConversationFragment.kt

import androidx.core.content.pm.ShortcutManagerCompat

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

نکته: روش‌های مختلفی برای انتشار یک میانبر وجود دارد، اما متد pushDynamicShortcut از API reportShorcutUsed استفاده می‌کند که سیگنالی به هوش ماشین می‌دهد که این مخاطبی است که باید با او به اشتراک گذاشته شود. متد pushDynamicShortcut همچنین تضمین می‌کند که میانبرها بدون نیاز به مدیریت محدودیت تعداد میانبرها، به‌روزرسانی شوند.

توجه: لمس طولانی مدت اعلان MessagingStyle بدون میانبر ارجاعی، نشان می‌دهد که از ویژگی‌های مکالمه پشتیبانی نمی‌کند. با میانبر ارجاعی، می‌توانید اولویت و تنظیمات این اعلان را تنظیم کنید. برای اطلاعات بیشتر، به بخش «آزمایش اعلان‌ها و میانبرهای مکالمه» مراجعه کنید.

برنامه را اجرا کنید

1. برنامه را اجرا کنید.
2. در کادر متنی Message #composers برنامه، پیامی را وارد کنید و سپس روی «ارسال» ضربه بزنید.
3. از برنامه خارج شوید. دوباره یک اعلان دریافت می‌کنید، اما به طور مشخص‌تری به عنوان یک اعلان مربوط به مکالمه طراحی شده است. نماد آواتار برجسته‌تر شده و با نماد برنامه ادغام شده است. فرستنده، زمان و متن نیز ساده‌تر شده‌اند.

۵. اختیاری: فعال کردن حباب‌ها

حباب‌ها در اندروید ۹ معرفی شدند و در اندروید ۱۱ برای استفاده در زمینه مکالمات بهبود یافته و مجدداً مورد استفاده قرار گرفتند. حباب‌ها پوشش‌های دایره‌ای شکلی هستند که آواتار مکالمات شما محسوب می‌شوند. آن‌ها در لانچر برنامه ظاهر می‌شوند و به شما امکان می‌دهند به راحتی در یک حباب بزرگ به مکالمات پاسخ دهید. حتی در صورت پیاده‌سازی، حباب‌ها بسته به ترجیح کاربر اختیاری هستند.

برای فعال کردن حباب‌ها، مراحل زیر را دنبال کنید:

1. در فایل AndroidManifest.xml ، ویژگی‌های allowEmbedded و resizeableActivity را اضافه کنید و سپس هر کدام را روی مقدار true تنظیم کنید:

فایل AndroidManifest.xml

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

2. در کلاس 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()
    }

3. در فایل 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()
}

برنامه را اجرا کنید

1. برنامه را اجرا کنید.
2. در کادر متنی Message #composers برنامه، پیامی را وارد کنید و سپس روی «ارسال» ضربه بزنید.
3. از برنامه خارج شوید. پس از چند ثانیه، اعلانی از چت به شکل حباب دریافت خواهید کرد.
4. روی حباب ضربه بزنید. مکالمه از حباب شروع می‌شود.

۶. اختیاری: اشتراک‌گذاری یک لینک

شما اهداف اشتراک‌گذاری را اعلام کردید و در اعلان‌های خود به آنها اشاره کردید، که این امر همچنین امکان نمایش مخاطب شما در Sharesheet را فراهم کرد، یک جزء از پایین به بالا که هنگام ارسال یک ACTION intent) ظاهر می‌شود. اهداف اشتراک‌گذاری در بالای Sharesheet ظاهر می‌شوند و به شما امکان می‌دهند محتوای غنی را در مکالمات خود به اشتراک بگذارید.

برای فراخوانی Sharesheet، مراحل زیر را دنبال کنید:

1. در دستگاه خود، گوگل کروم را باز کنید و سپس به یک صفحه وب دلخواه مانند developer.android.com بروید.
2. در صورت لزوم، کلیک کنید بیشتر عمودی .
3. کلیک اشتراک‌گذاری . صفحه اشتراک‌گذاری در پایین صفحه نمایش داده می‌شود.

4. در صورت امکان، کلیک کنید جت‌چت . آدرس اینترنتی (URL) در چت به اشتراک گذاشته می‌شود.
5. اگر نمی بینی جت‌چت ، کلیک کنید برای فراخوانی صفحه اشتراک سیستم، روی «بیشتر» کلیک کنید، و سپس صفحه اشتراک را به بالا بکشید و کلیک کنید جت‌چت . آدرس اینترنتی (URL) در چت به اشتراک گذاشته می‌شود.

این یک مثال ساده است. انواع محتوای غنی‌تری برای اشتراک‌گذاری وجود دارد. برای اطلاعات بیشتر، به بخش بازیابی داده‌های ساده از برنامه‌های دیگر مراجعه کنید.

۷. تبریک

تبریک! حالا شما می‌دانید که چگونه با استفاده از APIهای Messaging و People، ویژگی‌های مرتبط با چت را به یک برنامه اندروید اضافه کنید. پیام‌رسانی خوبی داشته باشید!

بیشتر بدانید

• سازگاری ایموجی
• دریافت محتوای غنی
• کلاس PeopleManager
• آدم‌ها و گفتگوها