יצירת התראה

ההתראות מספקות מידע קצר ועדכני על אירועים באפליקציה בזמן שהיא לא בשימוש. במאמר הזה מוסבר איך ליצור התראה עם תכונות שונות. בסקירה הכללית על התראות מוסבר איך התראות מופיעות ב-Android. קוד לדוגמה שמשתמש בהתראות זמין בדוגמה של SociaLite ב-GitHub.

הקוד בדף הזה משתמש בממשקי NotificationCompat API מהספרייה AndroidX. ממשקי ה-API האלה מאפשרים להוסיף תכונות שזמינות רק בגרסאות חדשות יותר של Android, ועדיין לספק תאימות עד Android 9 (רמת API‏ 28). עם זאת, חלק מהתכונות, כמו פעולת התשובה בתוך השורה, לא פועלות בגרסאות קודמות.

הוספה של ספריית הליבה של AndroidX

למרות שרוב הפרויקטים שנוצרו באמצעות Android Studio כוללים את התלות הדרושה לשימוש ב-NotificationCompat, כדאי לוודא שהקובץ build.gradle ברמת המודול כולל את התלות הבאה:

מגניב

dependencies {
    implementation "androidx.core:core-ktx:1.16.0"
}

Kotlin

dependencies {
    implementation("androidx.core:core-ktx:1.16.0")
}

הערה: ספריות אחרות בקבוצה androidx כוללות גם את core כתלות טרנזיטיבית. אם אתם כבר משתמשים בממשקי API אחרים של Jetpack, יכול להיות שיש לכם גישה אל NotificationCompat בלי שתצטרכו את התלות הספציפית הזו.

יצירת התראה בסיסית

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

איור 1. התראה עם סמל, כותרת וטקסט.

לפרטים נוספים על כל חלק בהתראה, אפשר לקרוא על המבנה של ההתראה.

הצהרה על הרשאה בזמן ריצה

ב-Android 13 (רמת API‏ 33) ומעלה יש הרשאה בזמן ריצה לפרסום התראות באפליקציה שלא פטורות (כולל שירותים שפועלים בחזית (FGS)).

ההרשאה שצריך להצהיר עליה בקובץ המניפסט של האפליקציה מופיעה בקטע הקוד הבא:

<manifest ...>
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
    <application ...>
        ...
    </application>
</manifest>

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

הגדרת תוכן ההתראה

כדי להתחיל, מגדירים את התוכן ואת הערוץ של ההתראה באמצעות אובייקט NotificationCompat.Builder. בדוגמה הבאה אפשר לראות איך יוצרים התראה עם הפרטים הבאים:

• סמל קטן, שהוגדר על ידי setSmallIcon(). זהו התוכן היחיד שגלוי למשתמשים שנדרש.

• שם, שהוגדר על ידי setContentTitle().

• הטקסט בגוף ההודעה, שמוגדר על ידי setContentText().

• העדיפות של ההתראה, שהוגדרה על ידי setPriority(). העדיפות קובעת עד כמה ההתראה פולשנית ב-Android 7.1 ובגרסאות קודמות. ב-Android מגרסה 8.0 ואילך, צריך להגדיר את חשיבות הערוץ כמו שמוסבר בקטע הבא.

Kotlin

var builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle(textTitle)
        .setContentText(textContent)
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)

Java

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle(textTitle)
        .setContentText(textContent)
        .setPriority(NotificationCompat.PRIORITY_DEFAULT);

הקונסטרוקטור NotificationCompat.Builder מחייב לספק מזהה ערוץ. ההגדרה הזו נדרשת לצורך תאימות ל-Android מגרסה 8.0 (רמת API‏ 26) ואילך, אבל המערכות בגרסאות קודמות מתעלמות ממנה.

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

איור 2. התראה שאפשר להרחיב, במצב מכווץ ובמצב מורחב.

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

Kotlin

var builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Much longer text that cannot fit one line...")
        .setStyle(NotificationCompat.BigTextStyle()
                .bigText("Much longer text that cannot fit one line..."))
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)

Java

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Much longer text that cannot fit one line...")
        .setStyle(new NotificationCompat.BigTextStyle()
                .bigText("Much longer text that cannot fit one line..."))
        .setPriority(NotificationCompat.PRIORITY_DEFAULT);

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

יצירת ערוץ והגדרת רמת החשיבות

כדי להציג את ההתראה ב-Android מגרסה 8.0 ואילך, צריך לרשום את ערוץ ההתראות של האפליקציה במערכת על ידי העברת מופע של NotificationChannel אל createNotificationChannel(). הקוד הבא נחסם על ידי תנאי בגרסה SDK_INT:

Kotlin

private fun createNotificationChannel() {
    // Create the NotificationChannel, but only on API 26+ because
    // the NotificationChannel class is not in the Support Library.
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        val name = getString(R.string.channel_name)
        val descriptionText = getString(R.string.channel_description)
        val importance = NotificationManager.IMPORTANCE_DEFAULT
        val channel = NotificationChannel(CHANNEL_ID, name, importance).apply {
            description = descriptionText
        }
        // Register the channel with the system.
        val notificationManager: NotificationManager =
            getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
        notificationManager.createNotificationChannel(channel)
    }
}

Java

private void createNotificationChannel() {
    // Create the NotificationChannel, but only on API 26+ because
    // the NotificationChannel class is not in the Support Library.
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        CharSequence name = getString(R.string.channel_name);
        String description = getString(R.string.channel_description);
        int importance = NotificationManager.IMPORTANCE_DEFAULT;
        NotificationChannel channel = new NotificationChannel(CHANNEL_ID, name, importance);
        channel.setDescription(description);
        // Register the channel with the system; you can't change the importance
        // or other notification behaviors after this.
        NotificationManager notificationManager = getSystemService(NotificationManager.class);
        notificationManager.createNotificationChannel(channel);
    }
}

מכיוון שצריך ליצור את ערוץ ההתראות לפני שמפרסמים התראות ב-Android 8.0 ואילך, צריך להריץ את הקוד הזה ברגע שהאפליקציה מתחילה לפעול. אפשר לקרוא לפונקציה הזו שוב ושוב, כי יצירה של ערוץ התראות קיים לא מבצעת פעולה.

הקונסטרוקטור NotificationChannel דורש importance, באמצעות אחת מהקבועים מהמחלקה NotificationManager. הפרמטר הזה קובע איך להפריע למשתמש בכל התראה ששייכת לערוץ הזה. מגדירים את העדיפות באמצעות setPriority() כדי לתמוך ב-Android 7.1 ומגרסאות קודמות, כמו בדוגמה הקודמת.

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

מידע נוסף על רמות החשיבות של ההתראות

הגדרת פעולת ההקשה של ההתראה

כל התראה צריכה להגיב להקשה, בדרך כלל כדי לפתוח פעילות באפליקציה שתואמת להתראה. כדי לעשות זאת, מציינים כוונת תוכן שמוגדרת באמצעות אובייקט PendingIntent ומעבירים אותו אל setContentIntent().

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

Kotlin

// Create an explicit intent for an Activity in your app.
val intent = Intent(this, AlertDetails::class.java).apply {
    flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK
}
val pendingIntent: PendingIntent = PendingIntent.getActivity(this, 0, intent, PendingIntent.FLAG_IMMUTABLE)

val builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        // Set the intent that fires when the user taps the notification.
        .setContentIntent(pendingIntent)
        .setAutoCancel(true)

Java

// Create an explicit intent for an Activity in your app.
Intent intent = new Intent(this, AlertDetails.class);
intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK);
PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, intent, PendingIntent.FLAG_IMMUTABLE);

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        // Set the intent that fires when the user taps the notification.
        .setContentIntent(pendingIntent)
        .setAutoCancel(true);

הקוד הזה קורא ל-setAutoCancel(), שמסיר את ההתראה באופן אוטומטי כשהמשתמש מקיש עליה.

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

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

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

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

הצגת ההתראה

כדי שההתראה תופיע, מתקשרים אל NotificationManagerCompat.notify(), ומעבירים לה מזהה ייחודי של ההתראה ואת התוצאה של NotificationCompat.Builder.build(). כך זה נראה בדוגמה הבאה:

Kotlin

with(NotificationManagerCompat.from(this)) {
    if (ActivityCompat.checkSelfPermission(
            this@MainActivity,
            Manifest.permission.POST_NOTIFICATIONS
        ) != PackageManager.PERMISSION_GRANTED
    ) {
        // TODO: Consider calling
        // ActivityCompat#requestPermissions
        // here to request the missing permissions, and then overriding
        // public fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>,
        //                                        grantResults: IntArray)
        // to handle the case where the user grants the permission. See the documentation
        // for ActivityCompat#requestPermissions for more details.

        return@with
    }
    // notificationId is a unique int for each notification that you must define.
    notify(NOTIFICATION_ID, builder.build())
}

Java

with(NotificationManagerCompat.from(this)) {
   if (ActivityCompat.checkSelfPermission(
           this@MainActivity,
           Manifest.permission.POST_NOTIFICATIONS
       ) != PackageManager.PERMISSION_GRANTED
   ) {
       // TODO: Consider calling
       // ActivityCompat#requestPermissions
       // here to request the missing permissions, and then overriding
       // public void onRequestPermissionsResult(int requestCode, String[] permissions,
       //                                        int[] grantResults)
       // to handle the case where the user grants the permission. See the documentation
       // for ActivityCompat#requestPermissions for more details.

       return
   }
   // notificationId is a unique int for each notification that you must define.
   notify(NOTIFICATION_ID, builder.build())
}

שומרים את מזהה ההתראה שמעבירים אל NotificationManagerCompat.notify(), כי תצטרכו אותו כשתרצו לעדכן או להסיר את ההתראה.

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

הערה: החל מ-Android 8.1 (API ברמה 27), אפליקציות לא יכולות להשמיע צליל התראה יותר מפעם אחת בשנייה. אם האפליקציה שולחת כמה התראות בשנייה אחת, כולן יופיעו כמו שצריך, אבל רק ההתראה הראשונה בכל שנייה תפיק צליל.

הוספת כפתורי פעולה

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

איור 3. התראה עם כפתור פעולה אחד.

כדי להוסיף לחצן פעולה, מעבירים PendingIntent לשיטה addAction(). זה דומה להגדרת פעולת ברירת המחדל של ההתראה בלחיצה, אבל במקום להפעיל פעילות, אפשר לבצע פעולות אחרות, כמו הפעלה של BroadcastReceiver שמבצעת עבודה ברקע כדי שהפעולה לא תשבש את האפליקציה שכבר פתוחה.

לדוגמה, הקוד הבא מראה איך לשלוח שידור למקלט ספציפי:

Kotlin

val ACTION_SNOOZE = "snooze"

val snoozeIntent = Intent(this, MyBroadcastReceiver::class.java).apply {
    action = ACTION_SNOOZE
    putExtra(EXTRA_NOTIFICATION_ID, 0)
}
val snoozePendingIntent: PendingIntent =
    PendingIntent.getBroadcast(this, 0, snoozeIntent, 0)
val builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setContentIntent(pendingIntent)
        .addAction(R.drawable.ic_snooze, getString(R.string.snooze),
                snoozePendingIntent)

Java

String ACTION_SNOOZE = "snooze"

Intent snoozeIntent = new Intent(this, MyBroadcastReceiver.class);
snoozeIntent.setAction(ACTION_SNOOZE);
snoozeIntent.putExtra(EXTRA_NOTIFICATION_ID, 0);
PendingIntent snoozePendingIntent =
        PendingIntent.getBroadcast(this, 0, snoozeIntent, 0);

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setContentIntent(pendingIntent)
        .addAction(R.drawable.ic_snooze, getString(R.string.snooze),
                snoozePendingIntent);

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

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

הערה: ב-Android 10 (רמת API‏ 29) ואילך, הפלטפורמה יוצרת באופן אוטומטי לחצני פעולה של התראות אם האפליקציה לא מספקת לחצנים משלה. אם אתם לא רוצים שההתראות של האפליקציה יציגו הצעות לתשובות או לפעולות, אתם יכולים להשבית את התשובות והפעולות שנוצרות על ידי המערכת באמצעות setAllowGeneratedReplies() ו-setAllowSystemGeneratedContextualActions().

הוספת פעולה של תגובה ישירה

פעולת התגובה הישירה, שהוצגה ב-Android 7.0 (רמת API‏ 24), מאפשרת למשתמשים להזין טקסט ישירות בהתראה. הטקסט מועבר לאפליקציה בלי לפתוח פעילות. לדוגמה, אפשר להשתמש בפעולת תגובה ישירה כדי לאפשר למשתמשים להשיב להודעות טקסט או לעדכן רשימות משימות מתוך ההתראה.

איור 4. הקשה על הלחצן 'תשובה' פותחת את שדה הזנת הטקסט.

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

הוספת כפתור התשובה

כדי ליצור פעולת התראה שתומכת בתשובה ישירה, פועלים לפי השלבים הבאים:

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

   Kotlin

     // Key for the string that's delivered in the action's intent.
     private val KEY_TEXT_REPLY = "key_text_reply"
     var replyLabel: String = resources.getString(R.string.reply_label)
     var remoteInput: RemoteInput = RemoteInput.Builder(KEY_TEXT_REPLY).run {
         setLabel(replyLabel)
         build()
     }
     

   Java

     // Key for the string that's delivered in the action's intent.
     private static final String KEY_TEXT_REPLY = "key_text_reply";
   
     String replyLabel = getResources().getString(R.string.reply_label);
     RemoteInput remoteInput = new RemoteInput.Builder(KEY_TEXT_REPLY)
             .setLabel(replyLabel)
             .build();
     

2. יוצרים PendingIntent לפעולת התשובה.

   Kotlin

     // Build a PendingIntent for the reply action to trigger.
     var replyPendingIntent: PendingIntent =
         PendingIntent.getBroadcast(applicationContext,
             conversation.getConversationId(),
             getMessageReplyIntent(conversation.getConversationId()),
             PendingIntent.FLAG_UPDATE_CURRENT)
     

   Java

     // Build a PendingIntent for the reply action to trigger.
     PendingIntent replyPendingIntent =
             PendingIntent.getBroadcast(getApplicationContext(),
                     conversation.getConversationId(),
                     getMessageReplyIntent(conversation.getConversationId()),
                     PendingIntent.FLAG_UPDATE_CURRENT);
     

   חשוב לשים לב: אם משתמשים שוב ב-PendingIntent, יכול להיות שהוא יענה לשיחה אחרת מזו שהוא התכוון אליה. צריך לספק קוד בקשה שונה לכל שיחה, או לספק כוונה שלא מחזירה true כשקוראים ל-equals() בכוונה של תשובה לשיחה אחרת. מזהה השיחה מועבר לעיתים קרובות כחלק מחבילת התוספים של הכוונה, אבל המערכת מתעלמת ממנו כשמבצעים קריאה ל-equals().
3. מצרפים את האובייקט RemoteInput לפעולה באמצעות addRemoteInput().

   Kotlin

     // Create the reply action and add the remote input.
     var action: NotificationCompat.Action =
         NotificationCompat.Action.Builder(R.drawable.ic_reply_icon,
             getString(R.string.label), replyPendingIntent)
             .addRemoteInput(remoteInput)
             .build()
     

   Java

     // Create the reply action and add the remote input.
     NotificationCompat.Action action =
             new NotificationCompat.Action.Builder(R.drawable.ic_reply_icon,
                     getString(R.string.label), replyPendingIntent)
                     .addRemoteInput(remoteInput)
                     .build();
     

4. החלת הפעולה על ההתראה ושליחת ההתראה.

   Kotlin

     // Build the notification and add the action.
     val newMessageNotification = Notification.Builder(context, CHANNEL_ID)
             .setSmallIcon(R.drawable.ic_message)
             .setContentTitle(getString(R.string.title))
             .setContentText(getString(R.string.content))
             .addAction(action)
             .build()
   
     // Issue the notification.
     with(NotificationManagerCompat.from(this)) {
         notificationManager.notify(notificationId, newMessageNotification)
     }
     

   Java

     // Build the notification and add the action.
     Notification newMessageNotification = new Notification.Builder(context, CHANNEL_ID)
             .setSmallIcon(R.drawable.ic_message)
             .setContentTitle(getString(R.string.title))
             .setContentText(getString(R.string.content))
             .addAction(action)
             .build();
   
     // Issue the notification.
     NotificationManagerCompat notificationManager = NotificationManagerCompat.from(this);
     notificationManager.notify(notificationId, newMessageNotification);
     

המערכת מבקשת מהמשתמש להזין תגובה כשהוא מפעיל את פעולת ההתראה, כמו שמוצג באיור 4.

אחזור קלט משתמש מהתשובה

כדי לקבל קלט משתמש מממשק המשתמש של התשובה להתראה, קוראים ל-RemoteInput.getResultsFromIntent() ומעבירים לו את Intent שמתקבל על ידי BroadcastReceiver:

Kotlin

private fun getMessageText(intent: Intent): CharSequence? {
    return RemoteInput.getResultsFromIntent(intent)?.getCharSequence(KEY_TEXT_REPLY)
}

Java

private CharSequence getMessageText(Intent intent) {
    Bundle remoteInput = RemoteInput.getResultsFromIntent(intent);
    if (remoteInput != null) {
        return remoteInput.getCharSequence(KEY_TEXT_REPLY);
    }
    return null;
 }

אחרי שמבצעים את העיבוד של הטקסט, מעדכנים את ההתראה באמצעות הקריאה ל-NotificationManagerCompat.notify() עם אותו מזהה ותג, אם נעשה בהם שימוש. הפעולה הזו נדרשת כדי להסתיר את ממשק המשתמש של התגובה הישירה ולוודא שהמשתמש יודע שהתגובה שלו התקבלה ועברה עיבוד בצורה תקינה.

Kotlin

// Build a new notification, which informs the user that the system
// handled their interaction with the previous notification.
val repliedNotification = Notification.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.ic_message)
        .setContentText(getString(R.string.replied))
        .build()

// Issue the new notification.
NotificationManagerCompat.from(this).apply {
    notificationManager.notify(notificationId, repliedNotification)
}

Java

// Build a new notification, which informs the user that the system
// handled their interaction with the previous notification.
Notification repliedNotification = new Notification.Builder(context, CHANNEL_ID)
        .setSmallIcon(R.drawable.ic_message)
        .setContentText(getString(R.string.replied))
        .build();

// Issue the new notification.
NotificationManagerCompat notificationManager = NotificationManagerCompat.from(this);
notificationManager.notify(notificationId, repliedNotification);

כשעובדים עם ההתראה החדשה הזו, צריך להשתמש בהקשר שמועבר לשיטה onReceive() של הנמען.

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

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

הצגת הודעה דחופה

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

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

כשמוצגת ההתראה, המשתמשים רואים אחת מהאפשרויות הבאות, בהתאם לסטטוס הנעילה של המכשיר:

• אם המכשיר של המשתמש נעול, מוצגת פעילות במסך מלא שמכסה את מסך הנעילה.
• אם המכשיר של המשתמש לא נעול, ההתראה תופיע בצורה מורחבת עם אפשרויות לטיפול בהתראה או לסגירה שלה.

הערה: אם האפליקציה מטרגטת Android 10 (רמת API‏ 29) ואילך, צריך לבקש את ההרשאה USE_FULL_SCREEN_INTENT בקובץ המניפסט של האפליקציה כדי שהמערכת תפעיל את הפעילות במסך מלא שמשויכת להתראה הדחופה.

קטע הקוד הבא מדגים איך לשייך את ההתראה ל-Intent במסך מלא:

Kotlin

val fullScreenIntent = Intent(this, ImportantActivity::class.java)
val fullScreenPendingIntent = PendingIntent.getActivity(this, 0,
    fullScreenIntent, PendingIntent.FLAG_UPDATE_CURRENT)

var builder = NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setFullScreenIntent(fullScreenPendingIntent, true)

Java

Intent fullScreenIntent = new Intent(this, ImportantActivity.class);
PendingIntent fullScreenPendingIntent = PendingIntent.getActivity(this, 0,
        fullScreenIntent, PendingIntent.FLAG_UPDATE_CURRENT);

NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID)
        .setSmallIcon(R.drawable.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setFullScreenIntent(fullScreenPendingIntent, true);

הגדרת סטטוס השיתוף של מסך הנעילה

כדי לשלוט ברמת הפירוט שמוצגת בהתראה במסך הנעילה, צריך להתקשר אל setVisibility() ולציין אחד מהערכים הבאים:

• ‫VISIBILITY_PUBLIC: התוכן המלא של ההתראה מוצג במסך הנעילה.

• ‫VISIBILITY_SECRET: אף חלק מההתראה לא מוצג במסך הנעילה.

• ‫VISIBILITY_PRIVATE: במסך הנעילה מוצגים רק פרטים בסיסיים, כמו הסמל של ההתראה וכותרת התוכן. התוכן המלא של ההתראה לא מוצג.

כשמגדירים את הערך VISIBILITY_PRIVATE, אפשר גם לספק גרסה חלופית של תוכן ההתראה שבה פרטים מסוימים מוסתרים. לדוגמה, אפליקציית SMS עשויה להציג התראה עם הכיתוב 'יש לך 3 הודעות טקסט חדשות', אבל להסתיר את תוכן ההודעות ואת השולחים. כדי לספק את ההתראה החלופית הזו, צריך קודם ליצור את ההתראה החלופית באמצעות NotificationCompat.Builder כרגיל. לאחר מכן, מצרפים את ההתראה החלופית להתראה הרגילה באמצעות setPublicVersion().

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

עדכון התראה

כדי לעדכן התראה אחרי ששולחים אותה, צריך להתקשר שוב אל NotificationManagerCompat.notify() ולהעביר לה את אותו מזהה שבו השתמשתם קודם. אם ההתראה הקודמת נסגרה, נוצרת במקומה התראה חדשה.

אפשר להפעיל את הפונקציה setOnlyAlertOnce() כדי שההתראה תפריע למשתמש – באמצעות צליל, רטט או רמזים ויזואליים – רק בפעם הראשונה שההתראה מופיעה ולא בעדכונים מאוחרים יותר.

שימו לב: מערכת Android מגבילה את קצב העדכון של התראות. אם אתם מפרסמים עדכונים להתראה בתדירות גבוהה מדי – הרבה עדכונים בפחות משנייה אחת – המערכת עשויה להפסיק את העדכונים.

הסרת התראה

ההתראות יוצגו עד שאחד מהדברים הבאים יקרה:

• המשתמש סוגר את ההתראה.
• המשתמש מקיש על ההתראה, אם קוראים ל-setAutoCancel() כשיוצרים את ההתראה.
• אתם קוראים ל-cancel() עבור מזהה התראה ספציפי. השיטה הזו מוחקת גם התראות שמתקבלות בזמן אמת.
• אתם מתקשרים אל cancelAll(), שמסיר את כל ההתראות שהוצאתם בעבר.
• אם הגדרתם פסק זמן כשיוצרים את ההתראה באמצעות setTimeoutAfter(), ההתראה תפוג אחרי משך הזמן שצוין. אם צריך, אפשר לבטל התראה לפני שחלף פרק הזמן שצוין להפסקת הפעולה.

שיטות מומלצות לשימוש באפליקציות להעברת הודעות

כדאי לפעול לפי השיטות המומלצות שמפורטות כאן כשיוצרים התראות לאפליקציות של הודעות וצ'אט.

שימוש ב-MessagingStyle

החל מ-Android 7.0 (רמת API‏ 24), ‏ Android מספק תבנית של סגנון התראה שמתאימה במיוחד לתוכן של הודעות. באמצעות המחלקה NotificationCompat.MessagingStyle אפשר לשנות כמה מהתוויות שמוצגות בהתראה, כולל שם השיחה, הודעות נוספות ותצוגת התוכן של ההתראה.

קטע הקוד הבא מדגים איך להתאים אישית את הסגנון של התראה באמצעות המחלקה MessagingStyle.

Kotlin

val user = Person.Builder()
    .setIcon(userIcon)
    .setName(userName)
    .build()

val notification = NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("2 new messages with $sender")
    .setContentText(subject)
    .setSmallIcon(R.drawable.new_message)
    .setStyle(NotificationCompat.MessagingStyle(user)
        .addMessage(messages[1].getText(), messages[1].getTime(), messages[1].getPerson())
        .addMessage(messages[2].getText(), messages[2].getTime(), messages[2].getPerson())
    )
    .build()

Java

Person user = new Person.Builder()
    .setIcon(userIcon)
    .setName(userName)
    .build();

Notification notification = new NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("2 new messages with " + sender)
    .setContentText(subject)
    .setSmallIcon(R.drawable.new_message)
    .setStyle(new NotificationCompat.MessagingStyle(user)
        .addMessage(messages[1].getText(), messages[1].getTime(), messages[1].getPerson())
        .addMessage(messages[2].getText(), messages[2].getTime(), messages[2].getPerson())
    )
    .build();

החל מ-Android 9.0 (רמת API‏ 28), נדרש גם להשתמש במחלקה Person כדי לקבל עיבוד אופטימלי של ההתראה והאווטרים שלה.

כשמשתמשים ב-NotificationCompat.MessagingStyle, מבצעים את הפעולות הבאות:

• שיחה MessagingStyle.setConversationTitle() כדי להגדיר שם לצ'אטים קבוצתיים עם יותר משני אנשים. שם טוב לשיחה יכול להיות השם של הצ'אט הקבוצתי, או אם אין לו שם, רשימה של המשתתפים בשיחה. בלי זה, יכול להיות שההודעה תזוהה בטעות כהודעה בשיחה ישירה עם השולח של ההודעה האחרונה בשיחה.
• משתמשים בשיטה MessagingStyle.setData() כדי לכלול הודעות מדיה כמו תמונות. יש תמיכה בסוגי MIME של התבנית image/* ‎.

איך משתמשים בתשובה ישירה

התכונה 'תשובה ישירה' מאפשרת למשתמשים להוסיף תשובה בשרשור.

• אחרי שהמשתמש משיב באמצעות הפעולה 'תשובה מוטבעת', צריך להשתמש ב-MessagingStyle.addMessage() כדי לעדכן את ההתראה MessagingStyle, ולא לבטל או למחוק את ההתראה. אם לא מבטלים את ההתראה, המשתמש יכול לשלוח כמה תשובות מההתראה.
• כדי שהפעולה של התשובה בתוך ההודעה תהיה תואמת ל-Wear OS, צריך להפעיל את הפונקציה Action.WearableExtender.setHintDisplayInlineAction(true).
• אפשר להשתמש בשיטה addHistoricMessage() כדי להוסיף הודעות קודמות להתראה וכך לספק הקשר לשיחה ישירה.

הפעלת התכונה 'תשובה מהירה'

• כדי להפעיל את התשובה המהירה, קוראים לפונקציה setAllowGeneratedResponses(true) בפעולת התשובה. כתוצאה מכך, התשובות המהירות זמינות למשתמשים כשההתראה מועברת למכשיר WearOS. התשובות של 'תשובות חכמות' נוצרות על ידי מודל למידת מכונה שפועל כולו בשעון, על סמך ההקשר שמופיע בNotificationCompat.MessagingStyleהתראה, ולא מתבצעת העלאה של נתונים לאינטרנט כדי ליצור את התשובות.

הוספת מטא-נתונים של התראות

• הקצאת מטא-נתונים של התראות כדי להגדיר למערכת איך לטפל בהתראות של האפליקציה כשמצב המכשיר הוא Do Not Disturb mode. לדוגמה, אפשר להשתמש בשיטה addPerson() או בשיטה setCategory(Notification.CATEGORY_MESSAGE) כדי לבטל את המצב 'נא לא להפריע'.