فعالیت های در حال انجام

دستگاه‌های Wear OS اغلب برای تجربه‌های طولانی مدت، مانند پیگیری تمرین استفاده می‌شوند. این یک چالش تجربه کاربر را ارائه می دهد: اگر کاربر یک کار را شروع کند و سپس به صفحه ساعت برود، چگونه می تواند برگردد؟ بازگشت به برنامه با استفاده از لانچر می تواند دشوار باشد، به خصوص در حین حرکت و ایجاد اصطکاک غیر ضروری.

راه حل این است که یک اعلان در حال انجام را با یک OngoingActivity جفت کنید. این به دستگاه امکان می دهد اطلاعات مربوط به فعالیت طولانی مدت را در رابط کاربری نمایش دهد و ویژگی هایی مانند نماد قابل لمس در پایین صفحه ساعت را فعال می کند. این کار کاربران را از کار پس‌زمینه آگاه می‌کند و راهی برای بازگشت به برنامه با یک ضربه فراهم می‌کند.

به عنوان مثال، در این برنامه تمرینی، اطلاعات می توانند روی صفحه ساعت کاربر به عنوان یک نماد در حال ضربه زدن ظاهر شوند:

شکل 1. نشانگر فعالیت.

یک اعلان در حال انجام نیز اطلاعاتی را در بخش Recents در راه‌انداز برنامه جهانی نشان می‌دهد. این مکان مناسب دیگری را برای کاربران فراهم می کند تا وضعیت کار خود را ببینند و دوباره با برنامه درگیر شوند:

شکل 2. پرتاب کننده جهانی.

موارد زیر شرایط خوبی برای استفاده از یک اعلان مداوم مرتبط با یک فعالیت در حال انجام است:

شکل 3. تایمر: به طور فعال زمان را شمارش معکوس می کند و با توقف یا توقف تایمر به پایان می رسد.

شکل 4. پیمایش چرخش با نوبت: مسیرها را به مقصد اعلام می کند. زمانی که کاربر به مقصد برسد یا ناوبری را متوقف کند پایان می یابد.

شکل 5. رسانه: موسیقی را در طول یک جلسه پخش می کند. بلافاصله پس از توقف کاربر جلسه پایان می یابد.

Wear فعالیت‌های مداوم را به‌طور خودکار برای برنامه‌های رسانه ایجاد می‌کند.

برای مثالی عمیق از ایجاد فعالیت‌های در حال انجام برای انواع دیگر برنامه‌ها، به آزمایشگاه کد فعالیت در حال انجام مراجعه کنید.

راه اندازی

برای شروع استفاده از API فعالیت مداوم در برنامه خود، وابستگی های زیر را به فایل build.gradle برنامه خود اضافه کنید:

dependencies {
  implementation "androidx.wear:wear-ongoing:1.1.0"
  implementation "androidx.core:core:1.17.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!
AlwaysOnService.kt

OngoingActivity را ایجاد کنید

در مرحله بعد، یک نمونه از OngoingActivity را با استفاده از سازنده آن ایجاد کنید. OngoingActivity.Builder به Context ، شناسه اعلان و NotificationCompat.Builder نیاز دارد که در مرحله قبل ایجاد کردید.

ویژگی های کلیدی را که در سطوح جدید UI نمایش داده می شوند پیکربندی کنید:

• نمادهای متحرک و ایستا : نمادهایی را ارائه می دهد که در حالت فعال و محیطی روی صفحه ساعت نمایش داده می شوند.
• Touch intent : یک PendingIntent که کاربر را با ضربه زدن روی نماد فعالیت در حال انجام به برنامه شما برمی گرداند. می توانید از Indent 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()
AlwaysOnService.kt

برای اطلاع رسانی و ارسال درخواست کنید

مرحله آخر این است که OngoingActivity را با اعلان پیوند دهید و سپس آن را پست کنید. متد ongoingActivity.apply() سازنده اعلان اصلی را تغییر می دهد و داده های لازم را اضافه می کند تا سیستم بتواند آن را روی سطوح اضافی نمایش دهد. پس از اعمال آن، می توانید طبق معمول اعلان را بسازید و ارسال کنید.

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

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

متن وضعیت پویا را به راه‌انداز اضافه کنید

کد قبلی نماد قابل لمس را به صفحه ساعت اضافه می کند. برای ارائه به‌روزرسانی‌های غنی‌تر و بی‌درنگ در بخش Recents راه‌انداز، یک شی Status ایجاد کنید و آن را به OngoingActivity خود متصل کنید. اگر Status سفارشی ارائه نکنید، سیستم پیش‌فرض از متن محتوای اعلان استفاده می‌کند (تنظیم با setContentText() ).

برای نمایش متن پویا، از Status.Builder استفاده کنید. شما می توانید یک رشته الگو را با متغیرهایی تعریف کنید و اشیاء Status.Part را برای پر کردن آن مکان ها ارائه کنید. Status.Part می تواند پویا باشد، مانند کرونومتر یا تایمر.

مثال زیر نحوه ایجاد وضعیتی را نشان می دهد که "اجرا برای [یک تایمر کرونومتر]" را نمایش دهد:

// 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()
AlwaysOnService.kt

در نهایت، با فراخوانی setStatus() در OngoingActivity.Builder ، این Status به OngoingActivity خود پیوند دهید.

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

سفارشی سازی های اضافی

فراتر از Status ، می‌توانید فعالیت یا اعلان‌های جاری خود را به روش‌های زیر سفارشی کنید. با این حال، این سفارشی‌سازی‌ها ممکن است بر اساس اجرای OEM مورد استفاده قرار نگیرند.

اطلاع رسانی در حال انجام

• مجموعه دسته بندی اولویت فعالیت در حال انجام را تعیین می کند.
  • CATEGORY_CALL : تماس صوتی یا تصویری ورودی یا درخواست ارتباط همزمان مشابه
  • CATEGORY_NAVIGATION : یک نقشه یا ناوبری گام به گام
  • CATEGORY_TRANSPORT : کنترل انتقال رسانه برای پخش
  • CATEGORY_ALARM : زنگ هشدار یا تایمر
  • CATEGORY_WORKOUT : یک تمرین
  • CATEGORY_LOCATION_SHARING : دسته اشتراک‌گذاری موقت موقعیت مکانی)
  • CATEGORY_STOPWATCH : کرونومتر

فعالیت در حال انجام

• نماد متحرک: یک وکتور سیاه و سفید، ترجیحا با پس‌زمینه شفاف. روی صفحه ساعت در حالت فعال نمایش داده می شود. اگر نماد متحرک ارائه نشده باشد، از نماد اعلان پیش فرض استفاده می شود. نماد اعلان پیش فرض برای هر برنامه متفاوت است.

• نماد استاتیک: یک نماد برداری با پس زمینه شفاف. روی صفحه ساعت در حالت محیطی نمایش داده می شود. اگر نماد متحرک تنظیم نشده باشد، نماد ثابت روی صفحه ساعت در حالت فعال استفاده می شود. اگر این مورد ارائه نشده باشد، از نماد اعلان استفاده می شود. اگر هیچ کدام تنظیم نشده باشد، یک استثنا پرتاب می شود. (راه‌انداز برنامه همچنان از نماد برنامه استفاده می‌کند.)

• وضعیت در حال فعالیت: متن ساده یا Chronometer . در بخش Recents راه‌انداز برنامه نمایش داده می‌شود. در صورت عدم ارائه، از اعلان "متن متن" استفاده می شود.

• Intent را لمس کنید: یک PendingIntent برای بازگشت به برنامه اگر کاربر روی نماد فعالیت در حال انجام ضربه بزند استفاده می‌شود. روی صفحه ساعت یا روی آیتم راه‌انداز نمایش داده می‌شود. می تواند با هدف اصلی استفاده شده برای راه اندازی برنامه متفاوت باشد. اگر ارائه نشده باشد، از هدف محتوای اعلان استفاده می شود. اگر هیچ کدام تنظیم نشده باشد، یک استثنا پرتاب می شود.

• LocusId : شناسه‌ای که میانبر راه‌اندازی را که فعالیت در حال انجام با آن مطابقت دارد، اختصاص می‌دهد. در حالی که فعالیت در حال انجام است، در لانچر در بخش Recents نمایش داده می شود. اگر ارائه نشده باشد، راه‌انداز همه موارد برنامه را در بخش Recents از همان بسته پنهان می‌کند و فقط فعالیت در حال انجام را نشان می‌دهد.

• شناسه فعالیت در حال انجام: شناسه برای رفع ابهام تماس‌ها از fromExistingOngoingActivity() استفاده می‌شود، زمانی که یک برنامه بیش از یک فعالیت در حال انجام دارد.

یک فعالیت در حال انجام را به روز کنید

در بیشتر موارد، توسعه‌دهندگان در صورت نیاز به به‌روزرسانی داده‌های روی صفحه، یک اعلان جدید و یک فعالیت در حال انجام جدید ایجاد می‌کنند. با این حال، اگر می‌خواهید نمونه‌ای را به جای ایجاد مجدد، حفظ کنید، API در حال فعالیت روش‌های کمکی برای به‌روزرسانی یک OngoingActivity ارائه می‌کند.

اگر برنامه در پس‌زمینه اجرا می‌شود، می‌تواند به‌روزرسانی‌ها را به API فعالیت مداوم ارسال کند. با این حال، این کار را خیلی مکرر انجام ندهید، زیرا روش به روز رسانی تماس هایی را که خیلی نزدیک به یکدیگر هستند نادیده می گیرد. چند به روز رسانی در دقیقه منطقی است.

برای به روز رسانی فعالیت در حال انجام و اعلان ارسال شده، از شی ای که قبلا ایجاد کرده اید استفاده کنید و update() فراخوانی کنید، همانطور که در مثال زیر نشان داده شده است:

ongoingActivity.update(context, newStatus)

به عنوان یک راحتی، یک روش ثابت برای ایجاد یک فعالیت مداوم وجود دارد.

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

یک فعالیت مداوم را متوقف کنید

وقتی برنامه به عنوان یک فعالیت در حال اجرا به پایان رسید، فقط باید اعلان در حال انجام را لغو کند.

همچنین می‌توانید وقتی نوتیفیکیشن یا فعالیت در حال انجام در پیش‌زمینه به میان می‌آید لغو کنید، سپس هنگام بازگشت به پس‌زمینه آن‌ها را دوباره ایجاد کنید، اما این مورد الزامی نیست.

توقف یک فعالیت در حال انجام

اگر برنامه شما یک کنش توقف صریح دارد، پس از توقف موقت، فعالیت در حال انجام را ادامه دهید. برای برنامه‌ای بدون عمل توقف صریح، فعالیت را زمانی که موقتاً متوقف شده است، پایان دهید.

بهترین شیوه ها

هنگام کار با API فعالیت مداوم موارد زیر را به خاطر بسپارید:

• با استفاده از اعلان ، یک نماد ثابت برای فعالیت در حال انجام خود، به طور صریح یا به صورت بازگشتی تنظیم کنید. اگر این کار را نکنید، یک IllegalArgumentException دریافت می کنید.

• از آیکون های وکتور سیاه و سفید با پس زمینه شفاف استفاده کنید.

• با استفاده از اعلان، یک هدف لمسی را برای فعالیت در حال انجام خود، به طور صریح یا به عنوان بازگشتی تنظیم کنید. اگر این کار را نکنید، یک IllegalArgumentException دریافت می کنید.

• اگر برنامه شما بیش از یک فعالیت MAIN LAUNCHER اعلام شده در مانیفست دارد، یک میانبر پویا منتشر کنید و با استفاده از LocusId آن را با فعالیت در حال انجام خود مرتبط کنید.

هنگام پخش رسانه در دستگاه‌های Wear OS، اعلان‌های رسانه را منتشر کنید

اگر محتوای رسانه در دستگاه Wear OS در حال پخش است، یک اعلان رسانه منتشر کنید . این به سیستم اجازه می دهد تا فعالیت در حال انجام مربوطه را ایجاد کند.

اگر از Media3 استفاده می کنید، اعلان به صورت خودکار منتشر می شود. اگر اعلان خود را به صورت دستی ایجاد کنید، باید از MediaStyleNotificationHelper.MediaStyle استفاده کند و MediaSession مربوطه باید دارای فعالیت جلسه باشد.