יצירת התראה

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

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

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

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

מגניב

dependencies {
    implementation "androidx.core:core:2.2.0"
}

Kotlin

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

הערה: ספריות אחרות בקבוצה androidx כוללות גם את core בתור של תלות טרנזית. אם אתם כבר משתמשים בממשקי Jetpack API אחרים, יכולים לגשת ל-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);

ה-constructor של NotificationCompat.Builder דורש ממך לספק ערוץ ID. צריך לעשות זאת לתאימות עם 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 ואילך, יש להריץ את הקוד הזה ברגע שהאפליקציה מופעלת מתחיל. אפשר לבצע את הקריאה הזו שוב ושוב, כי יצירת ערוץ התראות קיים לא מבצעת פעולה כלשהי.

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

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

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

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

כל התראה חייבת להגיב להקשה, בדרך כלל כדי לפתוח פעילות במכשיר האפליקציה שתואמת להתראה. כדי לעשות זאת, צריך לציין כוונת תוכן מוגדר באמצעות 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(), שמאפשר להסיר את ההתראה באופן אוטומטי כשהמשתמש מקייש עליה.

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

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

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

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

הצגת ההתראה

כדי שההתראה תופיע, צריך להתקשר 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. מקישים על 'תשובה'. הלחצן פותח את קלט הטקסט.

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

הוספת לחצן לתשובה

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

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

   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(). עם זאת, אם אתם מפתחים אפליקציית הודעות, צריך ליצור סגנון להעברת הודעות, התראה ומצרפים את הודעה חדשה לשיחה.

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

הוספת סרגל התקדמות

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

איור 5. סרגל ההתקדמות במהלך פעולה.

אם אתם יכולים להעריך את מידת ההתקדמות של הפעולה בכל שלב, תוכלו להשתמש בפורמט 'החלטתי' של האינדיקטור – כפי שמוצג באיור 5 – על ידי קריאה ל-setProgress(max, progress, false). הפרמטר הראשון הוא הערך של 'complete', למשל 100. השנייה היא כמה הושלם. האפשרות האחרונה מציינת שזו התקדמות ידועה בר.

תוך כדי ביצוע הפעולה, יש להתקשר ברציפות אל setProgress(max, progress, false) עם ערך מעודכן עבור progress ולהנפיק מחדש את ההתראה, בהתאם אפשר לראות בדוגמה הבאה.

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

Kotlin

val builder = NotificationCompat.Builder(this, CHANNEL_ID).apply {
    setContentTitle("Picture Download")
    setContentText("Download in progress")
    setSmallIcon(R.drawable.ic_notification)
    setPriority(NotificationCompat.PRIORITY_LOW)
}
val PROGRESS_MAX = 100
val PROGRESS_CURRENT = 0
NotificationManagerCompat.from(this).apply {
    // Issue the initial notification with zero progress.
    builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false)
    notify(notificationId, builder.build())

    // Do the job that tracks the progress here.
    // Usually, this is in a worker thread.
    // To show progress, update PROGRESS_CURRENT and update the notification with:
    // builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false);
    // notificationManager.notify(notificationId, builder.build());

    // When done, update the notification once more to remove the progress bar.
    builder.setContentText("Download complete")
            .setProgress(0, 0, false)
    notify(notificationId, builder.build())
}

Java

...
NotificationManagerCompat notificationManager = NotificationManagerCompat.from(this);
NotificationCompat.Builder builder = new NotificationCompat.Builder(this, CHANNEL_ID);
builder.setContentTitle("Picture Download")
        .setContentText("Download in progress")
        .setSmallIcon(R.drawable.ic_notification)
        .setPriority(NotificationCompat.PRIORITY_LOW);

// Issue the initial notification with zero progress.
int PROGRESS_MAX = 100;
int PROGRESS_CURRENT = 0;
builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false);
notificationManager.notify(notificationId, builder.build());

// Do the job that tracks the progress here.
// Usually, this is in a worker thread.
// To show progress, update PROGRESS_CURRENT and update the notification with:
// builder.setProgress(PROGRESS_MAX, PROGRESS_CURRENT, false);
// notificationManager.notify(notificationId, builder.build());

// When done, update the notification once more to remove the progress bar.
builder.setContentText("Download complete")
        .setProgress(0,0,false);
notificationManager.notify(notificationId, builder.build());

בסוף הפעולה, הערך של progress חייב להיות שווה ל-max. אפשר להשאיר את סרגל התקדמות כדי להראות שהפעולה הסתיימה או כדי להסיר אותה. בכל מקרה, מעדכנים את טקסט ההתראה כדי להראות שהפעולה הושלמה. כדי להסיר: בסרגל ההתקדמות, קוראים לפונקציה setProgress(0, 0, false).

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

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

הערה: אם אתם צריכים להוריד קובץ, מומלץ להשתמש ב-DownloadManager, שמציג התראה משלו למעקב אחר התקדמות ההורדה.

הגדרת קטגוריה ברמת המערכת

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

אם ההתראה שלכם נכללת באחת מקטגוריות ההתראות שמוגדרות ב-NotificationCompat, כמו CATEGORY_ALARM,‏ CATEGORY_REMINDER,‏ CATEGORY_EVENT או CATEGORY_CALL, תוכלו להצהיר על כך על ידי העברת הקטגוריה המתאימה ל-setCategory():

Kotlin

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

Java

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

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

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

ייתכן שהאפליקציה תצטרך להציג הודעה דחופה ודחופה, כמו שיחת טלפון נכנסת או התראה מצלצלת. במצבים כאלה, ניתן לשייך 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 של הדפוס התמונה/* נתמכים.

איך משתמשים בתכונה 'תשובה ישירה'

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

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

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

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

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

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