إنشاء إشعار

إضافة أزرار الإجراءات

يمكن أن يقدّم الإشعار ما يصل إلى ثلاثة أزرار إجراءات تتيح للمستخدم الردّ بسرعة، مثل تأجيل تذكير أو الردّ على رسالة نصية. ولكن يجب ألا تكرّر أزرار الإجراءات هذه الإجراء الذي يتم تنفيذه عندما ينقر المستخدم على الإشعار.

الشكل 3: إشعار يتضمّن زر إجراء واحد

لإضافة زر إجراء، مرِّر 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.notification_icon)
        .setContentTitle("My notification")
        .setContentText("Hello World!")
        .setPriority(NotificationCompat.PRIORITY_DEFAULT)
        .setContentIntent(pendingIntent)
        .addAction(R.drawable.ic_snooze, context.getString(R.string.snooze),
                snoozePendingIntent)

لمزيد من المعلومات حول إنشاء BroadcastReceiver لتشغيل العمل في الخلفية ، يُرجى الاطّلاع على نظرة عامة على عمليات البث.

إذا كنت تحاول بدلاً من ذلك إنشاء إشعار يتضمّن أزرار تشغيل الوسائط، مثل إيقاف المسارات مؤقتًا وتخطّيها، يُرجى الاطّلاع على كيفية إنشاء إشعار يتضمّن عناصر التحكّم في الوسائط.

إضافة إجراء ردّ مباشر

يتيح إجراء الردّ المباشر، الذي تم تقديمه في الإصدار 7.0 من Android (مستوى واجهة برمجة التطبيقات 24)، للمستخدمين إدخال نص مباشرةً في الإشعار. يتم بعد ذلك تسليم النص إلى تطبيقك بدون فتح نشاط. على سبيل المثال، يمكنك استخدام إجراء الردّ المباشر للسماح للمستخدمين بالردّ على الرسائل النصية أو تعديل قوائم المهام من داخل الإشعار.

الشكل 4: يؤدي النقر على الزر "ردّ" إلى فتح حقل إدخال النص.

يظهر إجراء الردّ المباشر كزر إضافي في الإشعار يفتح حقل إدخال نص. عندما ينتهي المستخدم من الكتابة، يرفق النظام الردّ النصي بالـ intent الذي تحدّده لإجراء الإشعار ويرسل الـ intent إلى تطبيقك.

إضافة زر "ردّ"

لإنشاء إجراء إشعار يتيح الردّ المباشر، اتّبِع الخطوات التالية:

أنشئ مثيلاً من RemoteInput.Builder يمكنك إضافته إلى إجراء الإشعار. تقبل الدالة الإنشائية لهذه الفئة سلسلة يستخدمها النظام كمفتاح لحقل إدخال النص. يستخدم تطبيقك لاحقًا هذا المفتاح لاسترداد نص الإدخال.

// Key for the string that's delivered in the action's intent.
private val KEY_TEXT_REPLY = "key_text_reply"
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,
        conversation.getConversationId(),
        getMessageReplyIntent(conversation.getConversationId()),
        PendingIntent.FLAG_MUTABLE)

أرفِق الكائن RemoteInput بإجراء باستخدام addRemoteInput().

// Create the reply action and add the remote input.
val action: NotificationCompat.Action =
    NotificationCompat.Action.Builder(R.drawable.ic_reply_icon,
        context.getString(R.string.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)

يطلب النظام من المستخدم إدخال ردّ عندما يبدأ إجراء الإشعار، كما هو موضّح في الشكل 4.

استرداد بيانات أدخلها المستخدم من الردّ

لتلقّي بيانات أدخلها المستخدم من واجهة مستخدم الردّ في الإشعار، استدعِ 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.ic_message)
        .setContentText(context.getString(R.string.replied))
        .build()

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

استرداد بيانات أخرى

تعمل معالجة أنواع البيانات الأخرى بطريقة مشابهة باستخدام RemoteInput. يستخدم المثال التالي صورة كإدخال.

val KEY_REPLY = "key_reply"
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
            try {
                val inputStream = context.contentResolver.openInputStream(imageUri)
                val bitmap = BitmapFactory.decodeStream(inputStream)
                // Display the image
                // ...
            } catch (e: Exception) {
                Log.e("ReplyReceiver", "Failed to process image URI", e)
            }
        }
    }
}

عند استخدام هذا الإشعار الجديد، استخدِم السياق الذي يتم تمريره إلى طريقة 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.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

بدءًا من الإصدار 7.0 من Android (مستوى واجهة برمجة التطبيقات 24)، يوفّر Android نموذج نمط إشعار مخصّصًا لمحتوى المراسلة. باستخدام فئة NotificationCompat.MessagingStyle، يمكنك تغيير العديد من التصنيفات المعروضة في الإشعار، بما في ذلك عنوان المحادثة، الرسائل الإضافية، وعرض المحتوى للإشعار.

يوضّح مقتطف الرمز البرمجي التالي كيفية تخصيص نمط الإشعار باستخدام فئة MessagingStyle.

val user = Person.Builder()
    .setIcon(userIcon)
    .setName(userName)
    .build()

val notification = NotificationCompat.Builder(context, 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()

بدءًا من الإصدار 9.0 من Android (مستوى واجهة برمجة التطبيقات 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، ولا يتم تحميل أي بيانات إلى الإنترنت لإنشاء الردود.

إضافة بيانات وصفية للإشعار

• عيِّن بيانات وصفية للإشعار لإخبار النظام بكيفية التعامل مع إشعارات تطبيقك عندما يكون الجهاز في وضع عدم الإزعاج. على سبيل المثال، استخدِم طريقة addPerson() أو setCategory(Notification.CATEGORY_MESSAGE) لتجاهل وضع "عدم الإزعاج".