استخدام فقاعات الإشعارات للمحادثات

تسهّل فقاعات الإشعارات على المستخدمين الاطّلاع على المحادثات والمشاركة فيها.

تظهر الفقاعات فوق محتوى التطبيقات الأخرى، ويمكن للمستخدمين توسيعها للاطّلاع على محتوى التطبيق والتفاعل معه، ويمكنهم تصغيرها عندما لا يستخدمونها.

عندما يكون الجهاز مقفلاً أو تكون ميزة "تشغيل الشاشة دائمًا" مفعّلة، تظهر الفقاعات كالإشعارات العادية.

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

يمكن للمستخدمين إجراء ما يلي:

• حظر جميع فقاعات الإشعارات من تطبيقك: لا يتم حظر الإشعارات، ولكنها لا تظهر أبدًا كفقاعات.
• السماح بفقاعات إشعارات محدّدة من تطبيقك: يتم عرض الإشعارات في فقاعات باستخدام زر الفقاعة، وتُعد هذه الإشعارات "محدّدة".
• السماح بجميع فقاعات الإشعارات من تطبيقك: تظهر جميع الإشعارات المُرسَلة باستخدام BubbleMetadata كفقاعات.

واجهة برمجة التطبيقات Notification Bubble API

يتم إنشاء فقاعات الإشعارات باستخدام واجهة برمجة التطبيقات للإشعارات. إذا كنت تريد أن يظهر إشعارك كفقاعة، أرفِق به بيانات إضافية.

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

يوضّح الرمز التالي كيفية تنفيذ فقاعة:

<activity
  android:name=".bubbles.BubbleActivity"
  android:theme="@style/AppTheme.NoActionBar"
  android:label="@string/title_activity_bubble"
  android:allowEmbedded="true"
  android:resizeableActivity="true"
/>

إذا كان تطبيقك يعرض فقاعات متعددة من النوع نفسه، مثل محادثات متعددة مع جهات اتصال مختلفة، يجب أن يكون النشاط قادرًا على تشغيل عدة مثيلات. على الأجهزة التي تعمل بالإصدار 10 من نظام التشغيل Android والإصدارات الأقدم، لا تظهر الإشعارات كفقاعات إلا إذا ضبطت documentLaunchMode بشكل صريح على "always". اعتبارًا من الإصدار 11 من نظام التشغيل Android، لن تحتاج إلى ضبط هذه القيمة بشكل صريح، لأنّ النظام يضبط تلقائيًا لجميع المحادثات documentLaunchMode على "always".

لإرسال إشعار منبثق، اتّبِع الخطوات التالية:

1. أنشئ إشعارًا كالمعتاد.
2. استخدِم BubbleMetadata.Builder(PendingIntent, Icon) أو BubbleMetadata.Builder(String) لإنشاء عنصر BubbleMetadata.
3. استخدِم setBubbleMetadata() لإضافة البيانات الوصفية إلى الإشعار.
4. إذا كنت تستهدف الإصدار 11 من نظام التشغيل Android أو الإصدارات الأحدث، تأكَّد من أنّ البيانات الوصفية للفقاعة أو الإشعار تشير إلى اختصار ميزة المشاركة.
5. عدِّل تطبيقك بحيث لا يلغي الإشعارات التي تظهر كفقاعات. للتأكّد مما إذا تم تشغيل نشاط الإشعار كفقاعة، استخدِم Activity#isLaunchedFromBubble(). يؤدي إلغاء الإشعار إلى إزالة الفقاعة من الشاشة. يؤدي فتح فقاعة إلى إخفاء الإشعار المرتبط بها تلقائيًا.

تظهر هذه الخطوات في المثال التالي:

// Create a bubble intent.
val target = Intent(context, BubbleActivity::class.java)
val bubbleIntent = PendingIntent.getActivity(context, 0, target, 0 /* flags */)
val category = "com.example.category.IMG_SHARE_TARGET"

val chatPartner = Person.Builder()
    .setName("Chat partner")
    .setImportant(true)
    .build()

// Create a sharing shortcut.
val shortcutId = generateShortcutId()
val shortcut =
   ShortcutInfo.Builder(mContext, shortcutId)
       .setCategories(setOf(category))
       .setIntent(Intent(Intent.ACTION_DEFAULT))
       .setLongLived(true)
       .setShortLabel(chatPartner.name)
       .build()

// Create a bubble metadata.
val bubbleData = Notification.BubbleMetadata.Builder(bubbleIntent,
            Icon.createWithResource(context, R.drawable.icon))
    .setDesiredHeight(600)
    .build()

// Create a notification, referencing the sharing shortcut.
val builder = Notification.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(smallIcon)
    .setBubbleMetadata(bubbleData)
    .setShortcutId(shortcutId)
    .addPerson(chatPartner)

// Create a bubble intent.
Intent target = new Intent(mContext, BubbleActivity.class);
PendingIntent bubbleIntent =
    PendingIntent.getActivity(mContext, 0, target, 0 /* flags */);

private val CATEGORY_TEXT_SHARE_TARGET =
    "com.example.category.IMG_SHARE_TARGET"

Person chatPartner = new Person.Builder()
        .setName("Chat partner")
        .setImportant(true)
        .build();

// Create a sharing shortcut.
private String shortcutId = generateShortcutId();
ShortcutInfo shortcut =
   new ShortcutInfo.Builder(mContext, shortcutId)
       .setCategories(Collections.singleton(CATEGORY_TEXT_SHARE_TARGET))
       .setIntent(Intent(Intent.ACTION_DEFAULT))
       .setLongLived(true)
       .setShortLabel(chatPartner.getName())
       .build();

// Create a bubble metadata.
Notification.BubbleMetadata bubbleData =
    new Notification.BubbleMetadata.Builder(bubbleIntent,
            Icon.createWithResource(context, R.drawable.icon))
        .setDesiredHeight(600)
        .build();

// Create a notification, referencing the sharing shortcut.
Notification.Builder builder =
    new Notification.Builder(mContext, CHANNEL_ID)
        .setContentIntent(contentIntent)
        .setSmallIcon(smallIcon)
        .setBubbleMetadata(bubbleData)
        .setShortcutId(shortcutId)
        .addPerson(chatPartner);

إذا كان تطبيقك في المقدّمة عند إرسال فقاعة، يتم تجاهل مستوى الأهمية وتظهر الفقاعة دائمًا، ما لم يحظر المستخدم الفقاعات أو الإشعارات من تطبيقك.

إنشاء فقاعة موسّعة

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

هناك طريقتان يمكنك استخدامهما لضبط العلامات التي تفعِّل هذه السلوكيات: setAutoExpandBubble() و setSuppressNotification().

يوضّح المثال التالي كيفية ضبط فقاعة لعرضها تلقائيًا في حالة موسّعة:

val bubbleMetadata = Notification.BubbleMetadata.Builder()
    .setDesiredHeight(600)
    .setIntent(bubbleIntent)
    .setAutoExpandBubble(true)
    .setSuppressNotification(true)
    .build()

Notification.BubbleMetadata bubbleData =
    new Notification.BubbleMetadata.Builder()
        .setDesiredHeight(600)
        .setIntent(bubbleIntent)
        .setAutoExpandBubble(true)
        .setSuppressNotification(true)
        .build();

دورة حياة محتوى الفقاعة

عند توسيع فقاعة، يمرّ نشاط المحتوى بدورة حياة العملية العادية، ما يؤدي إلى أن يصبح التطبيق عملية في المقدّمة، إذا لم يكن كذلك من قبل.

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

حالات ظهور الفقاعات

للحدّ من مقاطعة المستخدم، لا تظهر الفقاعات إلا في ظروف معيّنة.

إذا كان التطبيق يستهدف الإصدار 11 من نظام التشغيل Android أو الإصدارات الأحدث، لا يظهر الإشعار كفقاعة إلا إذا استوفى متطلبات المحادثة. إذا كان التطبيق يستهدف الإصدار 10 من نظام التشغيل Android أو الإصدارات الأقدم، لا يظهر الإشعار كفقاعة إلا إذا استوفى شرطًا واحدًا أو أكثر من الشروط التالية:

• يستخدم الإشعار MessagingStyle وتمت إضافة a Person إليه.
• الإشعار ناتج عن طلب Service.startForeground، وله category بقيمة CATEGORY_CALL، وتمت إضافة Person إليه.
• يكون التطبيق في المقدّمة عند إرسال الإشعار.

إذا لم يتم استيفاء أي من هذه الشروط، يظهر الإشعار بدلاً من الفقاعة.

تشغيل الأنشطة من الفقاعات

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

لتشغيل نشاط جديد في المهمة نفسها التي تم عرضها في فقاعة: 1. استخدِم سياق النشاط عند تشغيل النوايا، activity.startActivity(intent), و 1. لا تضبط العلامة FLAG_ACTIVITY_NEW_TASK على النية.

بخلاف ذلك، يتم تشغيل النشاط الجديد في مهمة جديدة ويتم تصغير الفقاعة.

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

أفضل الممارسات

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

عندما تتلقّى فقاعة مصغّرة رسالة معدَّلة، تعرض الفقاعة رمز شارة للإشارة إلى وجود رسالة غير مقروءة. عندما يفتح المستخدم الرسالة في التطبيق المرتبط بها، اتّبِع الخطوات التالية:

• عدِّل BubbleMetadata لإيقاف الإشعار. استخدِم BubbleMetadata.Builder.setSuppressNotification(). يؤدي ذلك إلى إزالة رمز الشارة للإشارة إلى أنّ المستخدم تفاعل مع الرسالة.
• اضبط Notification.Builder.setOnlyAlertOnce() على true لإيقاف الصوت أو الاهتزاز المصاحبَين لتعديل BubbleMetadata.

نموذج التطبيق

تطبيق SociaLite النموذجي هو نموذج تطبيق محادثة يستخدم فقاعات المحادثات. لأغراض العرض التوضيحي، يستخدم هذا التطبيق برامج الدردشة الآلية. في التطبيقات الواقعية، استخدِم الفقاعات للرسائل التي يرسلها المستخدمون.