הוספת תכונות שקשורות לצ'אט לאפליקציה ל-Android באמצעות ממשקי ה-API להעברת הודעות ואנשים

1. לפני שמתחילים

קשה ליצור אפליקציית הודעות. למרות שחוויית המשתמש הכללית היא סובייקטיבית, מערכת Android מספקת את ממשקי ה-API להעברת הודעות ואנשים. ממשקים האלה משפרים ומפשטים את חוויית הצ'אט.

ב-Codelab הזה תלמדו איך להשתמש בממשקי ה-API האלה כדי ליצור סביבה עסקית מעניינת לאפליקציות צ'אט ב-Android. אתם מרחיבים את אפליקציית JetChat – אפליקציית צ'אט בסיסית ולא פונקציונלית שמשתמשת ב-Jetpack פיתוח נייטיב.

דרישות מוקדמות

• ידע בסיסי בפיתוח Android
• ידע בסיסי לגבי התראות

מה תפַתחו

אפליקציית JetChat מורחבת שמבצעת את הפעולות הבאות:

• הצגת התראות שמייצגות שיחות בקטע השיחה השמור בחלונית ההזזה להתראות.
• יעדי שיתוף של קובצי עזר בהתראות האלה מאפשרים לכם לשתף אותם בשיחות של האפליקציה.
• אוכף שיטות מומלצות ליצירת אובייקטים כדי לנצל את היתרונות של חוויות ברירת המחדל שמספקות המערכת ומשפרות את האפליקציה.

מה תלמדו

• איך להציג התראות שקשורות לשיחות בקטע השיחה השמור שבחלונית ההזזה להתראות.
• הסבר על החוויות השונות שמופעלות על ידי ממשקי ה-API של העברת הודעות ושל אנשים.

מה צריך להכין

• Git
• Android Studio
• חשבון GitHub

2. להגדרה

נקודת ההתחלה מבוססת על אפליקציית JetChat. הקוד לתחילת הפעולה מרחיב את אפליקציית JetChat כדי להציג בצורה טובה יותר את ממשקי ה-API של העברת הודעות ושל אנשים.

קבלת הקוד לתחילת הפעולה

כדי לקבל את הקוד לתחילת הפעולה עבור Codelab, פועלים לפי השלבים הבאים:

1. משכפלים משורת הפקודה את המאגר הבא של GitHub:

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

2. פותחים את הפרויקט ב-Android Studio ולוחצים על Run app. החלונית Emulator תופיע ותציג את האפליקציה.

היכרות עם אפליקציית JetChat המורחבת

1. בתיבת הטקסט Message #composers באפליקציה, מזינים הודעה ומקישים על שליחה.
2. ניווט אל מחוץ לאפליקציה. אחרי כמה שניות, תקבלו התראה עם תגובה ממישהו בצ'אט.

הערה: התשובה לא נשלחה מאדם אמיתי. האפליקציה מתוכנתת להגיב וכך לדמות חוויית צ'אט.

3. יצירת התראות על שיחות

ב-Android 11 הושקה ממשקי API שמאפשרים להציג התראות שקשורות לצ'אט בקטע ייעודי בחלונית ההזזה להתראות, שמיועדת רק לשיחות.

ההתראה חייבת להיות מהכיתה Notification.MessagingStyle ולהפנות לקיצור דרך לשיתוף לטווח ארוך. בקטע הזה נסביר איך למלא את דרישות ה-API האלה כדי להציג את ההתראות האלה שמייצגות שיחות בקטע השיחות.

כדי ליצור התראות לגבי הכיתה NotificationCompat.MessagingStyle, צריך לפעול לפי השלבים הבאים:

1. בכרטיסייה Project ב-Android Studio, לוחצים על app > java > com.example.compose.jetchat > conversation ואז לוחצים לחיצה כפולה על ConversationFragment.
2. בקובץ ConversationFragment.kt, מוצאים את המחלקה ConversationFragment ואז מוצאים את בלוק הקוד createNotification של הפונקציה Notification שבו נוצרה ההתראה.
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. ניווט אל מחוץ לאפליקציה. תוצג שוב התראה, אבל הסגנון שלה שונה. היא כוללת דמות וסגנון ייחודי להודעה. עם זאת, יש עוד עבודה לעשות כדי שההתראות יופיעו במקומות שבהם הן אמורות להופיע.

4. יצירת יעדי שיתוף לשיחות

עליכם להפנות לקיצור הדרך לשיתוף או ליעד השיתוף בהתראה. יעדי השיתוף מוגדרים בקובץ shortcuts.xml, והם נקודות הכניסה לטיפול בקיצורי דרך שהוגדרו באופן פרוגרמטי. מקשי הקיצור שאתם יוצרים מייצגים את השיחות באפליקציה ומאפשרים לכם לשתף תוכן בשיחות.

הערה: אתם יוצרים יעדי שיתוף ספציפיים להודעות נכנסות, שמוצגים כהתראות במכשיר של המשתמש. צריך גם ליצור יעדי שיתוף להודעות יוצאות, אבל הם לא מכוסים ב-Codelab הזה. עם זאת, אותם השלבים ודוגמאות הקוד שחלים על יעדי שיתוף של הודעות נכנסות חלים גם על יעדים לשיתוף של הודעות יוצאות.

הגדרה של יעדי שיתוף

1. בכרטיסייה Project, לוחצים לחיצה ימנית על הספרייה res ואז בוחרים באפשרות חדש > Google Directory.
2. בתיבת הטקסט, מזינים xml ואז מקישים על Enter (או על return ב-macOS).
3. לוחצים לחיצה ימנית על הספרייה xml ובוחרים באפשרות File.
4. בתיבת הטקסט, מזינים shortcuts.xml ואז מקישים על Enter (או על return ב-macOS).
5. בקובץ 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>

6. בכרטיסייה פרויקט, לוחצים על 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()
}

הפונקציה הזו מכילה את ה-methods setPerson ו-setLongLived הנדרשות לשיחה. המשתמש הוא איש הקשר שמשויך לקיצור הדרך, והגדרת ערך לטווח ארוך לערך true מבטיחה שקיצור הדרך הזה יישמר במטמון של המערכת ויוצג בפלטפורמות שונות בממשק המשתמש.

מידע על קיצור הדרך בהתראה

הערה: יעדי שיתוף שפורסמו להודעות יוצאות לא כפופות להתראה, מפני שהודעות יוצאות בדרך כלל לא מפעילות התראה למשתמש ששולח את ההודעה.

עליך להשתמש בקיצור הדרך לשיתוף בהתראה. עם זאת, חייבים ליצור את קיצור הדרך לפני שמעבירים את ההתראה.

לשם כך, בצע את הצעדים הבאים:

1. בקובץ ConversationFragment.kt, מחפשים את המחלקה ConversationFragment.
2. לפני הקריאה למשתנה notification, צריך ליצור משתנה shortcut שמפנה לקיצור הדרך שנוצר מ-ConversationUtil.generateShortcut.
3. ב-method 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, מוסיפים את ה-method 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 בקיצור הדרך, ומומלץ מאוד לעשות זאת. אם לאחר מכן מוסיפים הערות לפעילות המשויכת לכיתה LocusId, שולחים אותות ל-AI במכשיר שקיצור הדרך משויך לשיחה הזו. האותות האלה משמשים לדירוג השיחה בהתאם לפעילות המשתמשים, וכך להבטיח שהשיחה תוצג בצורה תקינה. מידע נוסף זמין במאמר שיטות מומלצות.

הערה: יעדי השיתוף הם לא ייחודיים לשיחות. הם יכולים להתקיים מחוץ לשיחות. למידע נוסף על יעדי שיתוף, ראו שיתוף קיצורי דרך API.

מפרסמים את קיצור הדרך

• כדי לפרסם את קיצור הדרך, בפונקציה simulateResponseAsANotification לפני ה-method notificationManager.notify, קוראים ל-method 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. ניווט אל מחוץ לאפליקציה. תקבלו שוב התראה, אבל הסגנון שלה דומה יותר כהתראה שקשורה לשיחה. סמל הדמות בולט יותר ומשלב את סמל האפליקציה. גם השולח, הזמן והטקסט פשוטים יותר.

5. אופציונלי: הפעלת בועות

התכונה 'בועות' הושקה ב-Android 9, שופרו והוספנו לשימוש בהקשר של שיחות ב-Android 11. בועות הן שכבות-על עגולות שמהוות דמות לשיחות שלכם. הם מופיעים במרכז האפליקציות ומאפשרים לכם להשיב בקלות לשיחות בבועה מורחבת. גם לאחר ההטמעה, השימוש בבועות הוא אופציונלי, בהתאם להעדפת המשתמש.

כדי להפעיל בועות:

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. מקישים על הבועה. השיחה תיפתח מהבועה.

6. אופציונלי: שיתוף קישור

הצהרת על יעדי שיתוף והתייחסת אליהם בהתראות. הפעולה הזו גם אפשרה את החשיפה של איש הקשר שלך בדף השיתוף, רכיב מלמטה למעלה שמופיע כשנשלחת Intent מסוג ACTION. שיתוף היעדים מופיע בחלק העליון של ה-Sharesheet ומאפשר לכם לשתף תוכן עשיר בשיחות.

כדי להפעיל את ה-Sharesheet:

1. במכשיר, פותחים את Google Chrome ולאחר מכן עוברים לדף אינטרנט לבחירתכם, כמו developer.android.com.
2. אם צריך, לוחצים על More vert.
3. לוחצים על שיתוף. הגיליון האלקטרוני יופיע בתחתית המסך.

4. אם אפשר, לוחצים על JetChat. כתובת ה-URL תשותף בצ'אט.
5. אם לא רואים את JetChat, לוחצים על עוד כדי להפעיל את גיליון השיתוף של המערכת, ואז מחליקים למעלה על ה-ShareSet ולוחצים על JetChat. כתובת ה-URL תשותף בצ'אט.

זוהי דוגמה פשוטה. יש סוגי תוכן עשירים יותר שאפשר לשתף. מידע נוסף זמין במאמר אחזור נתונים פשוטים מאפליקציות אחרות.

7. מזל טוב

מעולה! עכשיו אתם יודעים איך להוסיף תכונות שקשורות לצ'אט לאפליקציה ל-Android בעזרת ממשקי ה-API של העברת הודעות ושל אנשים. העברת הודעות בכיף!

מידע נוסף

• תאימות לאמוג'י
• קבלת תוכן עשיר
• הכיתה PeopleManager
• אנשים ושיחות