ایجاد اعلان

اعلان‌ها اطلاعات کوتاه و به‌موقعی درباره رویدادهای برنامه‌تان ارائه می‌دهند، درحالی‌که برنامه درحال استفاده نیست. این سند به شما نشان می‌دهد که چگونه با ویژگی‌های مختلف اعلان ایجاد کنید. برای آشنایی با نحوه نمایش اعلان‌ها در 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 نسخه ۷.۱ و قدیمی‌تر چقدر مزاحمت ایجاد می‌کند. برای Android نسخه ۸.۰ و بالاتر، به‌جای آن، اهمیت کانال را همان‌طور که در بخش بعدی نشان داده شده است تنظیم کنید.

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 نسخه ۸.۰ و بالاتر ارائه دهید، کانال اعلان برنامه‌تان را با ارسال نمونه‌ای از 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 8.0 و بالاتر ایجاد کنید، این کد را هنگام شروع برنامه اجرا کنید. فراخوانی مکرر آن بی‌خطر است زیرا ایجاد کانال موجود کاری انجام نمی‌دهد.

سازنده 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‏ ۲۴) معرفی شد، به کاربران اجازه می‌دهد نوشتار را مستقیماً در اعلان وارد کنند. سپس نوشتار بدون باز کردن فعالیت به برنامه‌تان ارسال می‌شود. برای مثال، می‌توانید از کنش پاسخ مستقیم استفاده کنید تا به کاربران اجازه دهید به پیام‌های نوشتاری پاسخ دهند یا فهرست‌های تکلیف را از داخل اعلان به‌روز کنند.

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

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

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

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

نمونه‌ای از 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 نسخه ۷.۰ (سطح API‏ ۲۴) به بعد، 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‏ ۲۸) به بعد، برای دریافت رندرینگ بهینه اعلان و چهرک‌های آن، استفاده از کلاس 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 تولید می‌شود، و هیچ داده‌ای برای تولید پاسخ‌ها در اینترنت بارگذاری نمی‌شود.

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