ایجاد اعلان

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

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

ایجاد اعلان پایه

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

شکل ۱. اعلان با نماد، عنوان، و مقداری نوشتار.

برای جزئیات بیشتر درباره هر بخش از اعلان، درباره ساختار اعلان بخوانید.

اعلام اجازه زمان اجرا

‫Android 13 (سطح میانای برنامه‌سازی کاربردی ۳۳) و نسخه‌های بالاتر از اجازه زمان اجرا برای پست کردن اعلان‌های غیرمعاف (ازجمله «سرویس‌های پیش‌زمینه‌ای» (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 و نسخه‌های جدیدتر، اهمیت کانال را همان‌طور که در بخش بعدی نشان داده شده است تنظیم کنید.

val textTitle = "Title"
val textContent = "Content"
val builder = NotificationCompat.Builder(context, CHANNEL_ID)
    .setSmallIcon(R.drawable.ic_logo)
    .setContentTitle(textTitle)
    .setContentText(textContent)
    .setPriority(NotificationCompat.PRIORITY_DEFAULT)

سازنده NotificationCompat.Builder از شما می‌خواهد شناسه کانال ارائه دهید. این کار برای سازگاری با Android 8.0 (سطح میانای برنامه‌سازی کاربردی ۲۶) و نسخه‌های جدیدتر الزامی است، اما نسخه‌های قدیمی‌تر آن را نادیده می‌گیرند.

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

شکل ۲. اعلان ازهم بازشدنی در حالت‌های جمع‌شده و ازهم بازشده.

اگر می‌خواهید اعلان شما طولانی‌تر باشد، می‌توانید با افزودن الگوی سبک با setStyle()، اعلان ازهم بازشدنی را فعال کنید. برای مثال، کد زیر ناحیه نوشتاری بزرگ‌تری ایجاد می‌کند:

val builder = NotificationCompat.Builder(context, CHANNEL_ID)
    .setSmallIcon(R.drawable.ic_logo)
    .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)

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

ایجاد کانال و تنظیم اهمیت

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

fun createNotificationChannel(context: Context) {
    // 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 = context.getString(R.string.channel_name)
        val descriptionText = context.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 =
            context.getSystemService(NotificationManager::class.java) as NotificationManager
        notificationManager.createNotificationChannel(channel)
    }
}

ازآنجایی‌که باید کانال اعلان را قبل‌از پست کردن اعلان‌ها در Android نسخه ۸.۰ و بالاتر ایجاد کنید، این کد را هنگام شروع برنامه اجرا کنید. تماس مکرر بی‌خطر است زیرا ایجاد کانال موجود هیچ کاری انجام نمی‌دهد.

سازنده NotificationChannel به سطح اهمیت بااستفاده از ثابت NotificationManager نیاز دارد. این تنظیم مشخص می‌کند که چگونه کاربر وقفه ایجاد کند. برای پشتیبانی از Android 7.1 و نسخه‌های پایین‌تر، اولویت را نیز با setPriority() همان‌طور که در مثال قبلی نشان داده شده است تنظیم کنید.

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

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

تنظیم کنش تک‌ضرب اعلان

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

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

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

val builder = NotificationCompat.Builder(context, CHANNEL_ID)
    .setSmallIcon(R.drawable.ic_logo)
    .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() به آن ارسال کنید. این در مثال زیر نشان داده شده است:

with(NotificationManagerCompat.from(context)) {
    if (ActivityCompat.checkSelfPermission(
            context,
            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(notificationId, builder.build())

شناسه اعلانی را که به NotificationManagerCompat.notify() ارسال می‌کنید ذخیره کنید، زیرا وقتی بخواهید اعلان را به‌روز کنید یا بردارید به آن نیاز دارید.

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

افزودن دکمه‌های کنش

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

شکل ۳. اعلانی با یک دکمه کنش.

برای افزودن دکمه کنش، PendingIntent را به روش addAction() ارسال کنید. این کار مثل تنظیم کنش پیش‌فرض ضربه اعلان است، با این تفاوت که به‌جای راه‌اندازی فعالیت، می‌توانید کارهای دیگری انجام دهید، مثلاً BroadcastReceiver راه‌اندازی کنید که کاری را در پس‌زمینه انجام می‌دهد تا کنش باعث مختل شدن برنامه‌ای که ازقبل باز است نشود.

برای مثال، کد زیر نشان می‌دهد که چگونه یک همه‌فرستی را به یک گیرنده خاص ارسال کنید:

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

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

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

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

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

شکل ۴. با تک‌ضرب زدن روی دکمه «پاسخ»، ورودی نوشتار باز می‌شود.

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

افزودن دکمه پاسخ

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

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

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

برای کنش پاسخ، PendingIntent ایجاد کنید.

// Build a PendingIntent for the reply action to trigger.
val replyPendingIntent: PendingIntent =
    PendingIntent.getBroadcast(context,
        conversationId,
        getMessageReplyIntent(conversationId),
        PendingIntent.FLAG_MUTABLE)

نادیده گرفته می‌شود.

شیء RemoteInput را بااستفاده از addRemoteInput() به کنشی پیوست کنید.

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

کنش را روی اعلان اعمال کنید و اعلان را صادر کنید.

// Build the notification and add the action.
val newMessageNotification = NotificationCompat.Builder(context, CHANNEL_ID)
    .setSmallIcon(R.drawable.ic_message)
    .setContentTitle(context.getString(R.string.title))
    .setContentText(context.getString(R.string.content))
    .addAction(action)
    .build()

// Issue the notification.
NotificationManagerCompat.from(context).notify(notificationId, newMessageNotification)

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

دریافت درونداد کاربر از پاسخ

برای دریافت ورودی کاربر از واسط کاربر پاسخ اعلان، RemoteInput.getResultsFromIntent() را فراخوانی کنید و Intent دریافتی از BroadcastReceiver خود را به آن ارسال کنید:

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

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

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

// Issue the new notification.
NotificationManagerCompat.from(context).notify(notificationId, repliedNotification)

بازیابی داده‌های دیگر

اداره کردن انواع دیگر داده‌ها به‌طور مشابه با RemoteInput کار می‌کند. مثال زیر از تصویر به‌عنوان ورودی استفاده می‌کند.

val replyLabel: String = context.resources.getString(R.string.reply_label)
val remoteInput: RemoteInput = RemoteInput.Builder(KEY_REPLY).run {
    setLabel(replyLabel)
    // Allow for image data types in the input.
    // This method can be used again to allow for other data types.
    setAllowDataType("image/*", true)
    build()
}

با RemoteInput#getDataResultsFromIntent تماس بگیر و داده‌های مربوطه را استخراج کن.

class ReplyReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        val dataResults = RemoteInput.getDataResultsFromIntent(intent, KEY_REPLY)
        val imageUri: Uri? = dataResults?.get("image/*") as? Uri

        if (imageUri != null) {
            // Extract the image
            context.contentResolver.openInputStream(imageUri)?.use { inputStream ->
                val bitmap = BitmapFactory.decodeStream(inputStream)
                // Display the image
                // ...
            }
        }
    }

    companion object {
        const val KEY_REPLY = "key_reply"
        const val KEY_TEXT_REPLY = "key_text_reply"
    }
}

هنگام کار با این اعلان جدید، از زمینه‌ای که به روش onReceive() گیرنده ارسال می‌شود استفاده کنید.

با فراخوانی setRemoteInputHistory()، پاسخ را به پایین اعلان اضافه کنید. بااین‌حال، اگر درحال ساختن برنامه پیام‌رسانی هستید، اعلان سبک پیام‌رسانی ایجاد کنید و پیام جدید را به مکالمه پیوست کنید.

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

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

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

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

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

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

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

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

تنظیم رؤیت‌پذیری قفل صفحه

برای کنترل سطح جزئیات قابل‌مشاهده در اعلان از صفحه قفل، با setVisibility() تماس بگیرید و یکی از مقادیر زیر را مشخص کنید:

  • VISIBILITY_PUBLIC: محتوای کامل اعلان در صفحه قفل نشان داده می‌شود.

  • VISIBILITY_SECRET: هیچ بخشی از اعلان در صفحه قفل نشان داده نمی‌شود.

  • VISIBILITY_PRIVATE: فقط اطلاعات پایه، مثل نماد اعلان و عنوان محتوا، در صفحه قفل نشان داده می‌شود. محتوای کامل اعلان نشان داده نمی‌شود.

وقتی VISIBILITY_PRIVATE را تنظیم می‌کنید، می‌توانید نسخه جایگزینی از محتوای اعلان ارائه دهید که جزئیات خاصی را پنهان می‌کند. برای مثال، برنامه پیامک ممکن است اعلانی نمایش دهد که می‌گوید «۳ پیامک جدید دارید»، اما محتوای پیام و فرستندگان را پنهان می‌کند. برای ارائه این اعلان جایگزین، ابتدا اعلان جایگزین را با NotificationCompat.Builder طبق معمول ایجاد کنید. سپس اعلان جایگزین را با setPublicVersion() به اعلان عادی پیوست کنید.

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

به‌روزرسانی اعلان

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

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

برداشتن اعلان

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

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

روال‌های مطلوب برای برنامه‌های پیام‌رسانی

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

استفاده از MessagingStyle

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

تکه‌کد زیر نشان می‌دهد که چگونه بااستفاده از کلاس MessagingStyle سبک اعلان را سفارشی‌سازی کنید.

val message1 = NotificationCompat.MessagingStyle.Message(
    messages[0].text,
    messages[0].time,
    messages[0].sender
)
val message2 = NotificationCompat.MessagingStyle.Message(
    messages[1].text,
    messages[1].time,
    messages[1].sender
)
notification = NotificationCompat.Builder(context, CHANNEL_ID)
    .setSmallIcon(R.drawable.ic_logo)
    .setStyle(
        NotificationCompat.MessagingStyle(Person.Builder().setName("Me").build())
            .addMessage(message1)
            .addMessage(message2)
    )
    .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) تماس بگیرید. این کار باعث می‌شود پاسخ‌های «پاسخ هوشمند» برای کاربران دردسترس باشد وقتی اعلان به دستگاه Wear OS منتقل می‌شود. پاسخ‌های «پاسخ هوشمند» توسط مدل یادگیری ماشین کاملاً درون‌ساعتی بااستفاده از زمینه ارائه‌شده توسط اعلان NotificationCompat.MessagingStyle تولید می‌شود، و هیچ داده‌ای برای تولید پاسخ‌ها در اینترنت بارگذاری نمی‌شود.

افزودن فراداده اعلان