برنامه Wear OS خود را برای Watch Face Push پیکربندی کنید

Watch Face Push به برنامه شما اجازه می‌دهد تا واچ فیس‌ها را در دستگاه 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 دسترسی به تمام روش‌های تعامل با Watch Face Push را فراهم می‌کند.

کار با اسلات‌ها

یک مفهوم کلیدی هنگام کار با Watch Face Push، اسلات‌ها هستند. اسلات‌ها راهی برای آدرس‌دهی به واچ فیس‌های نصب‌شده‌ای هستند که متعلق به برنامه شما هستند. سیستم حداکثر تعداد اسلات‌هایی را که یک بازار می‌تواند داشته باشد، تعیین می‌کند؛ با 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

اضافه کردن صفحه ساعت

اگر اسلات‌هایی (slots) موجود باشد، همانطور که توسط پاسخ 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

یک واچ فیس پیش‌فرض ارائه دهید

قابلیت Watch Face Push این امکان را فراهم می‌کند که هنگام نصب برنامه فروشگاه، یک واچ فیس پیش‌فرض نصب کنید. این کار به خودی خود آن واچ فیس پیش‌فرض را فعال نمی‌کند (به تنظیم واچ فیس فعال مراجعه کنید)، اما واچ فیس شما را در انتخابگر واچ فیس سیستم در دسترس قرار می‌دهد.

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

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

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

قابلیت Watch Face Push به اپلیکیشن فروشگاه اجازه می‌دهد تا واچ فیس فعال را تنظیم کند.

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

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

1. مجوز اندروید مورد نیاز برای تنظیم صفحه ساعت فعال را دریافت کنید.
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

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

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

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

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

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

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

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

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

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

این تغییر جزئی سپس در هر یک از چهار 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

ملاحظات

ملاحظات مهم هنگام پیاده‌سازی Watch Face Push در برنامه شما شامل تمرکز بر مصرف برق، ذخیره‌سازی در حافظه پنهان، به‌روزرسانی واچ فیس‌های همراه و ارائه یک واچ فیس پیش‌فرض نماینده است.

قدرت

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

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

ذخیره سازی

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

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

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

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

به‌روزرسانی واچ فیس‌های همراه

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

برای مدیریت این وضعیت، برنامه‌ی فروشگاه شما باید به اکشن پخش MY_PACKAGE_REPLACED گوش دهد و بررسی کند که آیا نیاز به به‌روزرسانی هرگونه واچ فیس همراه از دارایی‌های بسته وجود دارد یا خیر.

چهره ساعت پیش فرض نماینده

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

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

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

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

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

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

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