ההתראות מספקות מידע קצר ועדכני על אירועים באפליקציה בזמן שהיא לא בשימוש. במאמר הזה מוסבר איך ליצור התראה עם תכונות שונות. בסקירה הכללית על התראות מוסבר איך התראות מופיעות ב-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") }
יצירת התראה בסיסית
ההתראה בפורמט הבסיסי והקומפקטי ביותר שלה – שנקרא גם פורמט מכווץ – מציגה סמל, כותרת וכמות קטנה של תוכן טקסט. בקטע הזה מוסבר איך ליצור התראה שהמשתמש יכול להקיש עליה כדי להפעיל פעילות באפליקציה.
איור 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 ואילך, צריך להפעיל את ההתראות באופן ידני או ליצור תיבת דו-שיח לבקשת התראות.
הוספת כפתורי פעולה
התראה יכולה להציע עד שלושה לחצני פעולה שמאפשרים למשתמש להגיב במהירות, למשל להעביר תזכורת למצב נודניק או להשיב להודעת טקסט. אבל לחצני הפעולה האלה לא יכולים לשכפל את הפעולה שמתבצעת כשמשתמש מקיש על ההתראה.
איור 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 7.0 (רמת API 24), מאפשרת למשתמשים להזין טקסט ישירות בהתראה. הטקסט מועבר לאפליקציה בלי לפתוח פעילות. לדוגמה, אפשר להשתמש בפעולת תגובה ישירה כדי לאפשר למשתמשים להשיב להודעות טקסט או לעדכן רשימות משימות מתוך ההתראה.
איור 4. הקשה על הלחצן 'תשובה' פותחת את שדה הזנת הטקסט.
פעולת התשובה הישירה מופיעה כלחצן נוסף בהתראה, שפותח שדה להזנת טקסט. כשהמשתמש מסיים להקליד, המערכת מצרפת את תגובת הטקסט ל-Intent שציינתם לפעולת ההתראה ושולחת את ה-Intent לאפליקציה.
הוספת כפתור התשובה
כדי ליצור פעולת התראה שתומכת בתשובה ישירה, פועלים לפי השלבים הבאים:
- יוצרים מופע של
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();
- יוצרים
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);
- מצרפים את האובייקט
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();
- החלת הפעולה על ההתראה ושליחת ההתראה.
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 במסך מלא:
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()
כדי שההתראה תפריע למשתמש – באמצעות צליל, רטט או רמזים ויזואליים – רק בפעם הראשונה שההתראה מופיעה ולא בעדכונים מאוחרים יותר.
הסרת התראה
ההתראות יוצגו עד שאחד מהדברים הבאים יקרה:
- המשתמש סוגר את ההתראה.
- המשתמש מקיש על ההתראה, אם קוראים ל-
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)
כדי לבטל את המצב 'נא לא להפריע'.