پیکربندی برنامه Wear OS برای «ارسال صفحه ساعت»

«ارسال صفحه ساعت» به برنامه شما امکان می‌دهد صفحه‌های ساعت را در دستگاه Wear OS مدیریت کند. این شامل افزودن، به‌روزرسانی، و برداشتن صفحه‌های ساعت، و همچنین تنظیم صفحه ساعت فعال می‌شود. برنامه Wear OS خود را پیکربندی کنید تا از Watch Face Push API استفاده کند.

راه‌اندازی

وابستگی androidx.wear.watchfacepush:watchfacepush را در فایل build.gradle.kts خود بگنجانید.

مورد زیر را به AndroidManifest.xml اضافه کنید:

<!-- Required to use the Watch Face Push API.  -->
<uses-permission android:name="com.google.wear.permission.PUSH_WATCH_FACES" />
AndroidManifest.xml

دریافت مرجع برای نمونه مدیر

نمونه‌ای از WatchFacePushManager را دریافت کنید:

val watchFacePushManager = WatchFacePushManagerFactory.createWatchFacePushManager(context)
WatchFacePush.kt

‫WatchFacePushManager دسترسی به همه روش‌های تعامل با «ارسال صفحه ساعت» را فراهم می‌کند.

کار با بخش‌های آزاد

مفهوم کلیدی هنگام کار با «ارسال صفحه ساعت» جایگاه‌ها است. شکاف‌ها روشی برای پرداختن به صفحه‌های ساعت نصب‌شده‌ای است که متعلق به برنامه شما است. سیستم حداکثر تعداد جایگاه‌هایی را که بازار می‌تواند داشته باشد تعیین می‌کند؛ در Wear OS 6، این محدودیت ۱ است.

هنگام به‌روزرسانی یا برداشتن صفحه ساعت، از slotId برای شناسایی صفحه ساعت استفاده می‌شود تا عملیات روی آن انجام شود.

فهرست صفحه‌های ساعت

برای فهرست کردن مجموعه صفحه‌های ساعت نصب‌شده، از listWatchFaces() استفاده کنید:

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
installedList.forEach {
    Log.i(TAG, "Installed watchface: ${it.packageName}")
}

val remainingSlots = response.remainingSlotCount
Log.i(TAG, "Remaining slots: $remainingSlots")
WatchFacePush.kt

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

suspend fun isInstalled(packageName: String) = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails.any { it.packageName == packageName }
WatchFacePush.kt

افزودن صفحه ساعت

اگر وقت آزاد وجود داشته باشد، همان‌طور که در listWatchFaces پاسخ مشخص شده است، باید از روش addWatchFace() استفاده شود:

try {
    // Supply the validation token along with the watch face package data itself.
    val slot = watchFacePushManager.addWatchFace(parcelFileDescriptor, token)
    Log.i(TAG, "${slot.packageName} (${slot.versionCode}) added in slot ${slot.slotId}")
} catch (e: WatchFacePushManager.AddWatchFaceException) {
    Log.e(TAG, "Something went wrong installing the watch face", e)
}
WatchFacePush.kt

به‌روزرسانی صفحه ساعت

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

// Replacing the com.example.watchfacepush.green watch face with
// com.example.watchfacepush.red
val slotId =
    watchFacePushManager.listWatchFaces().installedWatchFaceDetails
        .firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId
        ?: throw IllegalArgumentException("No green watch face found")
try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: WatchFacePushManager.UpdateWatchFaceException) {
    Log.e(TAG, "Something went wrong updating the watch face", e)
}
WatchFacePush.kt

برداشتن صفحه ساعت

برای برداشتن صفحه ساعت:

// Remove the com.example.watchfacepush.green watch face.
val slotId =
    watchFacePushManager.listWatchFaces().installedWatchFaceDetails
        .firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId
        ?: throw IllegalArgumentException("No green watch face found")

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: WatchFacePushManager.RemoveWatchFaceException) {
    Log.e(TAG, "Something went wrong removing the watch face", e)
}
WatchFacePush.kt

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

بررسی کنید صفحه ساعتتان فعال باشد

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

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

suspend fun hasActiveWatchFace() = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }
WatchFacePush.kt

صفحه ساعت پیش‌فرضی ارائه دهید

«ارسال صفحه ساعت» امکان نصب صفحه ساعت پیش‌فرض را هنگام نصب برنامه بازار شما فراهم می‌کند. این کار به‌خودی خود صفحه ساعت پیش‌فرض را به‌عنوان صفحه ساعت فعال تنظیم نمی‌کند (به تنظیم صفحه ساعت فعال مراجعه کنید)، اما صفحه ساعت شما را در انتخابگر صفحه ساعت سیستم دردسترس قرار می‌دهد.

برای استفاده کردن از این ویژگی:

1. در ساخت برنامه Wear OS، صفحه ساعت پیش‌فرض را در مسیر زیر اضافه کنید: assets/default_watchface.apk

2. ورودی زیر را به AndroidManifest.xml اضافه کنید

   <meta-data
       android:name="com.google.android.wearable.marketplace.DEFAULT_WATCHFACE_VALIDATION_TOKEN"
       android:value="@string/default_wf_token" />
   AndroidManifest.xml

تنظیم صفحه ساعت فعال

«ارسال صفحه ساعت» به برنامه بازار امکان می‌دهد صفحه ساعت فعال را تنظیم کند.

این یعنی به‌طور خاص، برنامه می‌تواند صفحه ساعت فعال را روی یکی از صفحه‌های ساعت متعلق به بازار تنظیم کند، درصورتی‌که صفحه ساعت فعال فعلی متعلق به بازار نباشد. توجه داشته باشید که درصورتی‌که بازار ازقبل صفحه ساعت فعال را داشته باشد، تغییر دادن آن به صفحه ساعت دیگر ازطریق تماس با updateWatchFace برای جایگزین کردن محتوای جایگاه صفحه ساعت با صفحه ساعت دیگر انجام می‌شود.

تنظیم صفحه ساعت فعال یک فرایند دو مرحله‌ای است:

1. «اجازه Android» موردنیاز برای تنظیم صفحه ساعت فعال را دریافت کنید.
2. روش setWatchFaceAsActive را فراخوانی کنید.

برای تنظیم صفحه ساعت فعال، اجازه‌ها را دریافت کنید

اجازه موردنیاز SET_PUSHED_WATCH_FACE_AS_ACTIVE است که باید به مانیفست شما اضافه شود:

<!-- Required to be able to call the setWatchFaceAsActive() method. -->
<uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />
AndroidManifest.xml

ازآنجایی‌که این اجازه زمان اجرا است، برنامه شما باید هنگام اجرای برنامه این اجازه را از کاربر درخواست کند (برای کمک در این زمینه، کتابخانه همراه را درنظر بگیرید).

تنظیم صفحه ساعت به‌عنوان فعال

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

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

خواندن فراداده‌های اضافی از فایل APK صفحه ساعت

شیء WatchFaceSlot همچنین ابزاری برای دریافت اطلاعات اضافی فراهم می‌کند که می‌توانید در صفحه ساعتتان اعلام کنید.

این کار به‌ویژه در شرایطی که انواع جزئی از صفحه ساعت یکسان دارید مفید است. برای مثال، می‌توانید صفحه ساعتی تعریف کنید که:

• نام بسته: com.myapp.watchfacepush.mywatchface
• نسخه بسته: 1.0.0

اما این صفحه ساعت ممکن است به‌صورت چهار APK مختلف ارائه شود که همه آن‌ها تقریباً دقیقاً یکسان هستند، اما با رنگ‌های پیش‌فرض متفاوت: قرمز، زرد، سبز و آبی، که در ColorConfiguration در «زبان نشانه‌گذاری توسعه‌پذیر قالب صفحه ساعت» تنظیم شده‌اند.

این تغییر جزئی در هریک از چهار فایل APK منعکس می‌شود:

<!-- For watch face com.myapp.watchfacepush.mywatchface -->
<property
    android:name="default_color"
    android:value="red" />
AndroidManifest.xml

استفاده از دارایی سفارشی به برنامه شما امکان می‌دهد تعیین کند کدام‌یک از این گونه‌ها نصب شده است:

val color = watchFaceDetails
    .getMetaData("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()
Log.i(TAG, "Default color: $color")
WatchFacePush.kt

ملاحظات

ملاحظات مهم هنگام پیاده‌سازی «ارسال صفحه ساعت» در برنامه شما شامل تمرکز بر مصرف برق، حافظه نهان، به‌روزرسانی صفحه‌های ساعت دسته‌ای، و ارائه صفحه ساعت پیش‌فرض نماینده است.

قدرت

مصرف انرژی یکی از ملاحظات اصلی برای هر برنامه‌ای است که در Wear OS اجرا می‌شود. برای عنصر Wear OS برنامه بازار شما:

1. برنامه شما باید تا حد امکان کم و به‌ندرت اجرا شود (مگر اینکه کاربر مستقیماً با آن تعامل داشته باشد). این شامل موارد زیر می‌شود:
   • کمینه کردن بیدار کردن برنامه از برنامه تلفن
   • کمینه کردن اجرای کارهای WorkManager
2. زمان‌بندی گزارش‌های تحلیلی برای زمانی که ساعت درحال شارژ است:
   1. اگر می‌خواهید آمار کاربرد را از برنامه Wear OS یا هر سنجه دیگری گزارش کنید، از WorkManager با محدودیت requiresCharging استفاده کنید.
3. به‌روزرسانی‌ها را برای زمانی که ساعت درحال شارژ است و از Wi-Fi استفاده می‌کند زمان‌بندی کنید:
   1. بهتر است نسخه‌های صفحه‌های ساعت نصب‌شده را بررسی کنید و آن‌ها را به‌طور خودکار به‌روزرسانی کنید. دوباره از محدودیت requiresCharging و نوع شبکه UNMETERED برای requiresNetworkType استفاده کنید.
   2. وقتی دستگاه درحال شارژ است، احتمالاً به Wi-Fi دسترسی دارد. درخواست Wi-Fi برای بارگیری سریع فایل‌های APK به‌روزشده، و پس‌از اتمام، شبکه را آزاد کنید.
   3. همین راهنمایی برای مواردی که بازار ممکن است صفحه ساعت روز را ارائه دهد نیز اعمال می‌شود؛ این صفحه را درحالی‌که ساعت درحال شارژ است پیش‌بارگیری کنید.
4. کارها برای بررسی صفحه ساعت فعال زمان‌بندی نشود:
   1. بررسی دوره‌ای اینکه بازارتان هنوز صفحه ساعت فعال را دارد یا نه و اینکه صفحه ساعت کدام است باعث مصرف باتری می‌شود. از این رویکرد اجتناب کنید.
5. از اعلان‌ها در ساعت استفاده نشود:
   1. اگر برنامه شما از اعلان‌ها استفاده می‌کند، این اعلان‌ها را روی تلفن متمرکز کنید، جایی که کنش کاربر برنامه تلفن را باز می‌کند تا سفر را ادامه دهد. اعلان‌ها را پیکربندی کنید تا بااستفاده از setLocalOnly به برنامه ساعت منتقل نشوند.

درحال ذخیره در حافظه پنهان

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

برای ارائه تجربه کاربری بهتر و صرفه‌جویی در توان بازانتقال، پیاده‌سازی حافظه نهان کوچک در دستگاه Wear OS را برای ذخیره کردن تعدادی APK درنظر بگیرید.

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

به‌همین ترتیب، از این ویژگی می‌توان برای پیش‌ذخیره‌سازی صفحه ساعت روز یا طرح‌های مشابهی که در آن‌ها صفحه‌های ساعت درحین شارژ شدن دستگاه Wear OS بارگیری می‌شوند استفاده کرد.

به‌روزرسانی صفحه‌های ساعت دسته‌بندی‌شده

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

برای مدیریت این وضعیت، برنامه بازار شما باید به MY_PACKAGE_REPLACED کنش همه‌فرستی گوش دهد و نیاز به به‌روزرسانی هر صفحه ساعت دسته‌ای از دارایی‌های بسته را بررسی کند.

صفحه ساعت پیش‌فرض نماینده

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

برخی‌از ملاحظات هنگام کار با صفحه‌های ساعت پیش‌فرض:

• اگر کاربر انتخاب کرد صفحه ساعتی را از برنامه بازار شما حذف نصب کند، از removeWatchFace استفاده نکنید. درعوض، در این مورد، بااستفاده از updateWatchFace، صفحه ساعت را به صفحه ساعت پیش‌فرض برگردانید. این کار به کاربران کمک می‌کند صفحه ساعت شما را پیدا کنند و آن را از گالری تنظیم کنند.
• صفحه ساعت پیش‌فرض را ساده و ازطریق نمانام و زمینه‌تان فوراً قابل‌شناسایی کنید. این کار به کاربران کمک می‌کند آن را در گالری صفحه ساعت پیدا کنند.

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

  1. عنصر Launch را به صفحه ساعت اضافه کنید تا هدف بااستفاده از برنامه Wear OS راه‌اندازی شود، برای مثال:

     <Launch target="com.myapp/com.myapp.LaunchOnPhoneActivity" />

  2. در LaunchOnPhoneActivity، برنامه تلفن را بااستفاده از RemoteActivityHelper راه‌اندازی کنید.