استخدام فقاعات المحادثات للسماح للمستخدمين بالمشاركة في المحادثات

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

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

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

فقاعات المحادثات هي ميزة يمكنك إيقافها. عندما يعرض تطبيق الفقاعة الأولى، يوفّر مربّع حوار الأذونات خيارَين:

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

واجهة برمجة التطبيقات الخاصة بالفقاعات

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

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

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

<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 وتمت إضافة 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 التجريبي هو تطبيق محادثة يستخدم الفقاعات. لأغراض توضيحية، يستخدم هذا التطبيق روبوتات محادثة. في التطبيقات الواقعية، استخدِم الفقاعات للرسائل التي يرسلها أشخاص.