یک اعلان ایجاد کنید

اعلان ها اطلاعات کوتاه و به موقعی درباره رویدادهای برنامه شما در حالی که استفاده نمی شود ارائه می دهند. این سند به شما نشان می دهد که چگونه یک اعلان با ویژگی های مختلف ایجاد کنید. برای آشنایی با نحوه نمایش اعلان‌ها در Android، به نمای کلی اعلان‌ها مراجعه کنید. برای نمونه کدی که از اعلان‌ها استفاده می‌کند، به نمونه افراد در GitHub مراجعه کنید.

کد موجود در این صفحه از API های NotificationCompat از کتابخانه AndroidX استفاده می کند. این APIها به شما امکان می‌دهند ویژگی‌هایی را که فقط در نسخه‌های جدیدتر Android در دسترس هستند اضافه کنید، در حالی که همچنان با Android 9 (سطح API 28) سازگاری دارند. با این حال، برخی از ویژگی ها، مانند عمل پاسخ درون خطی، منجر به عدم امکان عملیات در نسخه های قبلی می شود.

کتابخانه هسته AndroidX را اضافه کنید

اگرچه اکثر پروژه‌های ایجاد شده با Android Studio وابستگی‌های لازم برای استفاده از NotificationCompat را دارند، بررسی کنید که فایل build.gradle در سطح ماژول شما وابستگی زیر را داشته باشد:

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

dependencies {
    implementation("androidx.core:core-ktx:2.2.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() تنظیم شده است. اولویت تعیین می‌کند که اعلان در اندروید 7.1 و نسخه‌های قدیمی‌تر چقدر سرزده باشد. برای Android 8.0 و بالاتر، در عوض اهمیت کانال را همانطور که در بخش بعدی نشان داده شده است تنظیم کنید.

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

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() یک اعلان قابل ارتقا را فعال کنید. به عنوان مثال، کد زیر یک ناحیه متن بزرگتر ایجاد می کند:

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)

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);

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

یک کانال ایجاد کنید و اهمیت را تعیین کنید

قبل از اینکه بتوانید اعلان را در اندروید 8.0 و بالاتر ارسال کنید، کانال اعلان برنامه خود را با ارسال نمونه ای از NotificationChannel به createNotificationChannel() در سیستم ثبت کنید. کد زیر توسط یک شرط در نسخه SDK_INT مسدود شده است:

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)
    }
}

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);
    }
}

از آنجایی که باید قبل از ارسال هر گونه اعلان در اندروید 8.0 و بالاتر، کانال اعلان ایجاد کنید، به محض شروع برنامه، این کد را اجرا کنید. تماس مکرر با آن بی خطر است، زیرا ایجاد یک کانال اعلان موجود هیچ عملیاتی را انجام نمی دهد.

سازنده NotificationChannel با استفاده از یکی از ثابت های کلاس NotificationManager به یک importance نیاز دارد. این پارامتر تعیین می کند که چگونه کاربر را برای هر اعلانی که به این کانال تعلق دارد قطع کند. همانطور که در مثال قبل نشان داده شده است، اولویت را با setPriority() برای پشتیبانی از اندروید 7.1 و قبل از آن تنظیم کنید.

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

برای اطلاعات بیشتر درباره معنای سطوح مختلف، در مورد سطوح اهمیت اعلان بخوانید.

عملکرد ضربه زدن اعلان را تنظیم کنید

هر اعلان باید به یک ضربه پاسخ دهد، معمولاً برای باز کردن فعالیتی در برنامه شما که مطابق با اعلان است. برای انجام این کار، یک محتوای intent تعریف شده با یک شی PendingIntent را مشخص کنید و آن را به setContentIntent() ارسال کنید.

قطعه زیر نحوه ایجاد یک هدف اساسی برای باز کردن یک فعالیت را هنگامی که کاربر روی اعلان ضربه می‌زند نشان می‌دهد:

// 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)

// 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() نشان داده شده در مثال قبل، تجربه ناوبری مورد انتظار کاربر را پس از باز کردن برنامه شما با استفاده از اعلان حفظ می کند. ممکن است بخواهید بسته به نوع فعالیتی که شروع می کنید از آن استفاده کنید، که می تواند یکی از موارد زیر باشد:

• فعالیتی که منحصراً برای پاسخ به اعلان وجود دارد. دلیلی وجود ندارد که کاربر در طول استفاده معمولی از برنامه به این فعالیت پیمایش کند، بنابراین فعالیت به جای اینکه به کار موجود برنامه شما و پشته پشتی اضافه شود، کار جدیدی را شروع می کند. این نوع قصد ایجاد شده در نمونه قبلی است.

• فعالیتی که در جریان برنامه عادی برنامه شما وجود دارد. در این حالت، شروع فعالیت یک پشته پشتی ایجاد می کند تا انتظارات کاربر از دکمه های Back و Up حفظ شود.

برای اطلاعات بیشتر درباره روش‌های مختلف پیکربندی هدف اعلان، به شروع یک فعالیت از یک اعلان مراجعه کنید.

اعلان را نشان دهید

برای نشان دادن اعلان، با NotificationManagerCompat.notify() تماس بگیرید و یک شناسه منحصر به فرد برای اعلان و نتیجه NotificationCompat.Builder.build() ارسال کنید. این در مثال زیر نشان داده شده است:

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())
}

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 که کاری را در پس‌زمینه انجام می‌دهد انجام دهید تا این عملکرد برنامه‌ای را که از قبل باز شده است، قطع نکند.

به عنوان مثال، کد زیر نحوه ارسال یک پخش به یک گیرنده خاص را نشان می دهد:

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)

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 برای اجرای کار پس‌زمینه، به نمای کلی Broadcasts مراجعه کنید.

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

یک اقدام پاسخ مستقیم اضافه کنید

عمل پاسخ مستقیم که در اندروید 7.0 (سطح API 24) معرفی شده است، به کاربران امکان می دهد متن را مستقیماً در اعلان وارد کنند. سپس متن بدون باز کردن فعالیت به برنامه شما تحویل داده می شود. برای مثال، می‌توانید از یک اقدام پاسخ مستقیم استفاده کنید تا به کاربران اجازه دهید به پیام‌های متنی پاسخ دهند یا لیست وظایف را از داخل اعلان به‌روزرسانی کنند.

شکل 4. ضربه زدن روی دکمه "پاسخ" ورودی متن را باز می کند.

عمل پاسخ مستقیم به عنوان یک دکمه اضافی در اعلان ظاهر می شود که ورودی متن را باز می کند. وقتی کاربر تایپ کردن را تمام کرد، سیستم پاسخ متنی را به هدفی که برای عمل اعلان مشخص کرده‌اید پیوست می‌کند و هدف را به برنامه شما ارسال می‌کند.

دکمه پاسخ را اضافه کنید

برای ایجاد یک کنش اعلان که از پاسخ مستقیم پشتیبانی می کند، این مراحل را دنبال کنید:

1. نمونه ای از RemoteInput.Builder ایجاد کنید که می توانید آن را به عملکرد اعلان خود اضافه کنید. سازنده این کلاس رشته ای را می پذیرد که سیستم از آن به عنوان کلید ورودی متن استفاده می کند. برنامه شما بعداً از آن کلید برای بازیابی متن ورودی استفاده می کند.

   کاتلین

     // 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()
     }
     

   جاوا

     // 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 برای عمل پاسخ ایجاد کنید.

   کاتلین

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

   جاوا

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

3. شی RemoteInput را با استفاده از addRemoteInput() به یک عمل وصل کنید.

   کاتلین

     // 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()
     

   جاوا

     // 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. اقدام را در یک اعلان اعمال کنید و اعلان را صادر کنید.

   کاتلین

     // 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)
     }
     

   جاوا

     // 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 خود را ارسال کنید:

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

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

پس از پردازش متن، با فراخوانی NotificationManagerCompat.notify() با همان شناسه و تگ، در صورت استفاده، اعلان را به روز کنید. این برای پنهان کردن رابط کاربری پاسخ مستقیم و تأیید اینکه پاسخ او به درستی دریافت و پردازش شده است، لازم است.

// 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)
}

// 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) استفاده کنید. پارامتر اول مقدار "کامل" است، مثلاً 100. دومی اینکه چقدر کامل است. آخرین نشان می دهد که این یک نوار پیشرفت مشخص است.

همانطور که عملیات شما ادامه دارد، به طور مداوم setProgress(max, progress, false) با یک مقدار به روز شده برای progress فراخوانی کنید و اعلان را مجدداً منتشر کنید، همانطور که در مثال زیر نشان داده شده است.

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())
}

...
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) فراخوانی کنید و سپس اعلان را به روز کنید تا نشانگر فعالیت حذف شود.

به یاد داشته باشید که متن اعلان را تغییر دهید تا نشان دهد عملیات کامل شده است.

یک دسته بندی در سطح سیستم تنظیم کنید

Android از دسته‌های از پیش تعریف‌شده در سراسر سیستم استفاده می‌کند تا مشخص کند وقتی کاربر حالت Do Not Disturb را فعال می‌کند، با یک اعلان خاص مزاحم کاربر شود یا خیر.

اگر اعلان شما در یکی از دسته‌های اعلان تعریف شده در NotificationCompat قرار می‌گیرد - مانند CATEGORY_ALARM ، CATEGORY_REMINDER ، CATEGORY_EVENT ، یا CATEGORY_CALL - با ارسال دسته‌بندی مناسب به setCategory() آن را به عنوان چنین اعلام کنید:

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)

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 مطابقت داشته باشد.

نمایش یک پیام فوری

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

هنگامی که اعلان فراخوانی می شود، بسته به وضعیت قفل دستگاه، کاربران یکی از موارد زیر را مشاهده می کنند:

• اگر دستگاه کاربر قفل باشد، یک فعالیت تمام صفحه ظاهر می شود که صفحه قفل را پوشش می دهد.
• اگر قفل دستگاه کاربر باز باشد، اعلان به شکل گسترده‌ای ظاهر می‌شود که شامل گزینه‌هایی برای مدیریت یا رد کردن اعلان است.

قطعه کد زیر نحوه مرتبط کردن اعلان خود را با یک هدف تمام صفحه نشان می دهد:

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)

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 را تنظیم می‌کنید، می‌توانید نسخه دیگری از محتوای اعلان را نیز ارائه دهید که جزئیات خاصی را پنهان می‌کند. به عنوان مثال، یک برنامه پیامک ممکن است اعلانی را نشان دهد که "شما 3 پیام متنی جدید دارید" را نشان می دهد، اما محتوای پیام و فرستنده ها را پنهان می کند. برای ارائه این اعلان جایگزین، ابتدا اعلان جایگزین را طبق معمول با NotificationCompat.Builder ایجاد کنید. سپس، اعلان جایگزین را با setPublicVersion() به اعلان معمولی پیوست کنید.

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

یک اعلان را به روز کنید

برای به روز رسانی یک اعلان پس از صدور آن، دوباره با NotificationManagerCompat.notify() تماس بگیرید و همان شناسه ای را که قبلا استفاده می کردید ارسال کنید. اگر اعلان قبلی رد شود، به جای آن یک اعلان جدید ایجاد می شود.

می‌توانید به‌صورت اختیاری setOnlyAlertOnce() را فراخوانی کنید تا اعلان شما با صدا، لرزش، یا سرنخ‌های بصری کاربر را قطع کند، فقط اولین باری که اعلان ظاهر می‌شود و نه برای به‌روزرسانی‌های بعدی.

یک اعلان را حذف کنید

اعلان‌ها تا زمانی که یکی از موارد زیر رخ ندهد قابل مشاهده می‌مانند:

• کاربر اعلان را رد می کند.
• اگر هنگام ایجاد اعلان، setAutoCancel() فراخوانی کنید، کاربر روی اعلان ضربه می زند.
• شما cancel() را برای شناسه اعلان خاصی فراخوانی می کنید. این روش همچنین اعلان های جاری را حذف می کند.
• شما cancelAll() را فراخوانی می‌کنید که تمام اعلان‌هایی را که قبلا صادر کرده‌اید حذف می‌کند.
• اگر در هنگام ایجاد اعلان، با استفاده از setTimeoutAfter() یک بازه زمانی تعیین کنید، مدت زمان مشخص شده سپری می شود. در صورت لزوم، می توانید قبل از سپری شدن مدت زمان تعیین شده، اعلان را لغو کنید.

بهترین روش ها برای برنامه های پیام رسانی

هنگام ایجاد اعلان برای برنامه‌های پیام‌رسانی و چت، بهترین روش‌های فهرست‌شده در اینجا را در نظر بگیرید.

از MessagingStyle استفاده کنید

با شروع Android 7.0 (سطح API 24)، Android یک الگوی سبک اعلان را به طور خاص برای محتوای پیام ارائه می دهد. با استفاده از کلاس NotificationCompat.MessagingStyle ، می توانید چندین برچسب نمایش داده شده در اعلان را تغییر دهید، از جمله عنوان مکالمه، پیام های اضافی و نمای محتوای اعلان.

قطعه کد زیر نحوه سفارشی کردن سبک اعلان را با استفاده از کلاس MessagingStyle نشان می دهد.

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()

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();

با شروع اندروید 9.0 (سطح API 28)، همچنین برای دریافت رندر بهینه از اعلان و آواتارهای آن، باید از کلاس Person استفاده کنید.

هنگام استفاده از NotificationCompat.MessagingStyle ، موارد زیر را انجام دهید:

• با MessagingStyle.setConversationTitle() تماس بگیرید تا عنوانی برای چت های گروهی با بیش از دو نفر تنظیم کنید. یک عنوان مکالمه خوب ممکن است نام چت گروهی یا، اگر نامی ندارد، فهرستی از شرکت کنندگان در گفتگو باشد. بدون این، پیام ممکن است به عنوان متعلق به یک مکالمه یک به یک با فرستنده جدیدترین پیام در مکالمه اشتباه گرفته شود.
• از روش MessagingStyle.setData() برای اضافه کردن پیام های رسانه ای مانند تصاویر استفاده کنید. انواع MIME تصویر الگو/* پشتیبانی می شوند.

از پاسخ مستقیم استفاده کنید

پاسخ مستقیم به کاربر این امکان را می دهد که به صورت درون خطی به یک پیام پاسخ دهد.

• پس از اینکه کاربر با عمل پاسخ درون خطی پاسخ داد، از MessagingStyle.addMessage() برای به روز رسانی اعلان MessagingStyle استفاده کنید و اعلان را پس نگیرید یا لغو نکنید. لغو نکردن اعلان به کاربر امکان می دهد چندین پاسخ از اعلان ارسال کند.
• برای سازگار کردن عملکرد پاسخ درون خطی با Wear OS، Action.WearableExtender.setHintDisplayInlineAction(true) را فراخوانی کنید.
• از متد addHistoricMessage() استفاده کنید تا با افزودن پیام‌های تاریخی به اعلان، زمینه یک مکالمه پاسخ مستقیم را فراهم کنید.

پاسخ هوشمند را فعال کنید

• برای فعال کردن Smart Reply، با setAllowGeneratedResponses(true) در عمل پاسخ تماس بگیرید. این باعث می‌شود وقتی اعلان به دستگاه Wear OS پل می‌شود، پاسخ‌های Smart Reply در دسترس کاربران قرار گیرد. پاسخ‌های Smart Reply توسط یک مدل یادگیری ماشین کاملاً روی ساعت و با استفاده از زمینه ارائه‌شده توسط اعلان NotificationCompat.MessagingStyle تولید می‌شوند و هیچ داده‌ای برای تولید پاسخ‌ها در اینترنت آپلود نمی‌شود.

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

• فراداده اعلان را اختصاص دهید تا به سیستم بگویید چگونه با اعلان‌های برنامه شما وقتی دستگاه در Do Not Disturb mode است کار کند. برای مثال، از متد addPerson() یا setCategory(Notification.CATEGORY_MESSAGE) برای لغو مزاحم نشوید استفاده کنید.