عرض الأنشطة الجارية

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

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

تُبقي "الأنشطة الجارية" تطبيقك مرئيًا لفترة أطول، ما يمنع النظام من الرجوع إلى خلفية شاشة الساعة بعد فترة من عدم النشاط. لمزيد من المعلومات، يُرجى الاطّلاع على إبقاء تطبيقك مرئيًا على Wear.

على سبيل المثال، في تطبيق التمارين الرياضية هذا، يمكن أن تظهر المعلومات على خلفية شاشة الساعة على شكل رمز قابل للنقر عليه:

running-icon

الشكل 1: مؤشر النشاط

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

launcher

الشكل 2: مشغّل عالمي

في ما يلي بعض الحالات التي يكون فيها من المناسب استخدام إشعار بنشاط مستمر في الخلفية مرتبط بـ "نشاط مستمر في الخلفية":

موقّت

الشكل 3: الموقّت: يتم احتساب الوقت بشكل نشط ويتم إيقافه مؤقتًا أو إيقافه نهائيًا.

خريطة

الشكل 4. التنقّل خطوة بخطوة: تعلن هذه الميزة عن الاتّجاهات المؤدية إلى وجهة معيّنة. تنتهي عندما يصل المستخدم إلى الوجهة أو يتوقّف عن التنقّل.

الموسيقى

الشكل 5. الوسائط: تشغيل الموسيقى طوال الجلسة تنتهي الجلسة فورًا بعد أن يوقفها المستخدم مؤقتًا.

تنشئ Wear "الأنشطة الجارية" تلقائيًا لتطبيقات الوسائط.

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

الإعداد

لبدء استخدام واجهة برمجة التطبيقات Ongoing Activity API في تطبيقك، أضِف التبعيات التالية إلى ملف build.gradle في تطبيقك:

dependencies {
  implementation "androidx.wear:wear-ongoing:1.1.0"
  implementation "androidx.core:core:1.18.0"
}

إنشاء نشاط مستمر

تتضمّن العملية ثلاث خطوات:

  1. أنشئ NotificationCompat.Builder عادية واضبطها على مستمرة.
  2. أنشئ كائن OngoingActivity واضبطه، مع تمرير أداة إنشاء الإشعارات إليه.
  3. طبِّق "النشاط الجاري" على أداة إنشاء الإشعارات وانشر الإشعار الناتج.

إنشاء الإشعار وضبطه

ابدأ بإنشاء NotificationCompat.Builder. الخطوة الأساسية هي استدعاء setOngoing(true) لتصنيفها كإشعار بنشاط مستمر في الخلفية. يمكنك أيضًا ضبط خصائص أخرى للإشعارات في هذه المرحلة، مثل الرمز الصغير والفئة.

// Create a PendingIntent to pass to the notification builder
val pendingIntent =
    PendingIntent.getActivity(
        this,
        0,
        Intent(this, AlwaysOnActivity::class.java).apply {
            flags = Intent.FLAG_ACTIVITY_SINGLE_TOP
        },
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
    )

val notificationBuilder = NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("Always On Service")
    .setContentText("Service is running in background")
    .setSmallIcon(R.drawable.animated_walk)
    // Category helps the system prioritize the ongoing activity
    .setCategory(NotificationCompat.CATEGORY_WORKOUT)
    .setContentIntent(pendingIntent)
    .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
    .setOngoing(true) // Important!

إنشاء OngoingActivity

بعد ذلك، أنشِئ مثيلاً من OngoingActivity باستخدام أداة الإنشاء الخاصة به. يتطلّب OngoingActivity.Builder Context ومعرّف إشعار وNotificationCompat.Builder الذي أنشأته في الخطوة السابقة.

اضبط خصائص المفتاح التي سيتم عرضها على مساحات العرض الجديدة في واجهة المستخدم:

  • الرموز المتحركة والثابتة: قدِّم رموزًا يتم عرضها على خلفية شاشة الساعة في الوضعَين النشط والاستراحة.
  • نية اللمس: هي PendingIntent تعيد المستخدم إلى تطبيقك عندما ينقر على رمز "النشاط الجاري". يمكنك إعادة استخدام pendingIndent الذي تم إنشاؤه في الخطوة السابقة.

val ongoingActivity =
    OngoingActivity.Builder(applicationContext, NOTIFICATION_ID, notificationBuilder)
        // Sets the icon that appears on the watch face in active mode.
        .setAnimatedIcon(R.drawable.animated_walk)
        // Sets the icon that appears on the watch face in ambient mode.
        .setStaticIcon(R.drawable.ic_walk)
        // Sets the tap target to bring the user back to the app.
        .setTouchIntent(pendingIntent)
        .build()

تطبيق الإشعار على المنشور

الخطوة الأخيرة هي ربط OngoingActivity بالإشعار ثم نشره. تعدّل الطريقة ongoingActivity.apply() أداة إنشاء الإشعارات الأصلية، وتضيف البيانات اللازمة ليتمكّن النظام من عرضها على المساحات الإضافية. بعد تطبيقها، يمكنك إنشاء الإشعار ونشره كالمعتاد.

// This call modifies notificationBuilder to include the ongoing activity data.
ongoingActivity.apply(applicationContext)

// Post the notification.
startForeground(NOTIFICATION_ID, notificationBuilder.build())

إضافة نص حالة ديناميكي إلى مشغّل التطبيقات

يضيف الرمز السابق الرمز القابل للنقر إلى خلفية الساعة. لتقديم إشعارات أكثر تفصيلاً في الوقت الفعلي في قسم الأحداث الأخيرة ضمن مشغّل التطبيقات، أنشئ عنصر Status وأرفِقه بـ OngoingActivity. إذا لم توفّر Status مخصّصة، سيستخدم النظام تلقائيًا نص محتوى الإشعار (الذي تم ضبطه باستخدام setContentText()). لعرض نص ديناميكي، استخدِم Status.Builder. يمكنك تحديد سلسلة نموذجية تتضمّن عناصر نائبة وتوفير Status.Part لتعبئة هذه العناصر النائبة. يمكن أن يكون Status.Part ديناميكيًا، مثل ساعة الإيقاف أو المؤقّت.

يوضّح المثال التالي كيفية إنشاء حالة تعرض "الركض لمدة [a stopwatch timer]":

// Define a template with placeholders for the activity type and the timer.
val statusTemplate = "#type# for #time#"

// Set the start time for a stopwatch.
// Use SystemClock.elapsedRealtime() for time-based parts.
val runStartTime = SystemClock.elapsedRealtime()

val ongoingActivityStatus = Status.Builder()
    // Sets the template string.
    .addTemplate(statusTemplate)
    // Fills the #type# placeholder with a static text part.
    .addPart("type", Status.TextPart("Run"))
    // Fills the #time# placeholder with a stopwatch part.
    .addPart("time", Status.StopwatchPart(runStartTime))
    .build()

أخيرًا، اربط هذا الرقم Status بحسابك OngoingActivity من خلال الاتصال بالرقم setStatus() على OngoingActivity.Builder.

val ongoingActivity =
    OngoingActivity.Builder(applicationContext, NOTIFICATION_ID, notificationBuilder)
        // ...
        // Add the status to the OngoingActivity.
        .setStatus(ongoingActivityStatus)
        .build()

تخصيصات إضافية

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

الإشعار المستمر

  • تحدّد فئة مجموعة الأنشطة الجارية الأولوية.
    • CATEGORY_CALL: مكالمة صوتية أو مكالمة فيديو واردة أو طلب مماثل للتواصل بشكل متزامن
    • CATEGORY_NAVIGATION: خريطة أو اتجاهات مفصّلة
    • CATEGORY_TRANSPORT: عنصر التحكّم في نقل الوسائط لتشغيلها
    • CATEGORY_ALARM: منبّه أو موقّت
    • CATEGORY_WORKOUT: تمرين
    • CATEGORY_LOCATION_SHARING: فئة مشاركة الموقع الجغرافي المؤقتة
    • CATEGORY_STOPWATCH: ساعة توقّف

النشاط الجاري

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

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

  • OngoingActivityStatus: نص عادي أو Chronometer يظهر في قسم التطبيقات الحديثة ضمن مشغّل التطبيقات. في حال عدم توفيرها، يتم استخدام "نص السياق" للإشعار.

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

  • ‫LocusId: هو رقم التعريف الذي يحدّد اختصار مشغّل التطبيقات الذي يتوافق مع النشاط الجاري. يظهر على مشغّل التطبيقات في قسم عمليات البحث الأخيرة أثناء استمرار النشاط. في حال عدم توفيرها، سيخفي مشغّل التطبيقات جميع عناصر التطبيق في قسم النشاطات الأخيرة من الحزمة نفسها ولن يعرض سوى "النشاط الجاري".

  • معرّف النشاط الجاري: هو المعرّف المستخدَم لتمييز طلبات fromExistingOngoingActivity() عندما يكون لدى التطبيق أكثر من نشاط جارٍ واحد.

تعديل نشاط مستمر

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

ongoingActivity.update(context, newStatus)

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

OngoingActivity.recoverOngoingActivity(context)
    ?.update(context, newStatus)

إيقاف "نشاط قيد التقدّم"

عندما ينتهي التطبيق من العمل كنشاط مستمر في الخلفية، ما عليه سوى إلغاء إشعار بنشاط مستمر في الخلفية.

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

إيقاف نشاط جارٍ مؤقتًا

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

الاعتبارات الأساسية

يُرجى تذكُّر ما يلي عند استخدام Ongoing Activity API:

  • اضبط رمزًا ثابتًا لـ "النشاط الجاري"، إما بشكل صريح أو كبديل باستخدام الإشعار. إذا لم تفعل ذلك، ستحصل على IllegalArgumentException.

  • استخدِم رموزًا متّجهة باللونين الأبيض والأسود مع خلفيات شفافة.

  • اضبط هدفًا عند اللمس لـ "النشاط الجاري"، إما بشكل صريح أو كإجراء احتياطي باستخدام الإشعار. إذا لم تفعل ذلك، ستحصل على IllegalArgumentException.

  • إذا كان تطبيقك يتضمّن أكثر من نشاط MAIN LAUNCHER واحد تم تحديده في ملف البيان، عليك نشر اختصار ديناميكي وربطه بنشاطك المستمر باستخدام LocusId.

نشر إشعارات الوسائط عند تشغيل الوسائط على أجهزة Wear OS

إذا كان يتم تشغيل محتوى وسائط على جهاز Wear OS، انشر إشعارًا بالوسائط. يتيح ذلك للنظام إنشاء النشاط الجاري المقابل.

إذا كنت تستخدم Media3، سيتم نشر الإشعار تلقائيًا. إذا أنشأت إشعارك يدويًا، يجب أن يستخدم MediaStyleNotificationHelper.MediaStyle، ويجب أن يتم ملء نشاط الجلسة في MediaSession المقابل.