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

با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

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

راه اندازی

وابستگی های لازم را شامل شود:

implementation("androidx.wear.watchface:watchface-push:1.3.0-alpha07")

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

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

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

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

</manifest>

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

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

val manager = WatchFacePushManager(context)

WatchFacePushManager دسترسی به تمام روش‌های تعامل با Watch Face Push را فراهم می‌کند.

با اسلات کار کنید

یک مفهوم کلیدی هنگام کار با Watch Face Push، اسلات ها است. اسلات‌ها راهی برای آدرس‌دهی صفحه‌های ساعت نصب‌شده‌ای هستند که متعلق به برنامه شما هستند. این سیستم حداکثر تعداد اسلات هایی را که یک بازار می تواند داشته باشد را تعیین می کند. با Wear OS 6، محدودیت 1 است.

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

چهره‌های ساعت را فهرست کنید

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

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
val remainingSlots = response.remainingSlots

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

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

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

اگر اسلات های موجود وجود داشته باشد، همانطور که توسط پاسخ 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: AddWatchFaceException) {
    // Something went wrong adding the watch face.
}

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

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

// 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

try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: UpdateWatchFaceException) {
    // Something went wrong updating the watch face.
}

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

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

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

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: RemoveWatchFaceException) {
    // Something went wrong removing the watch face.
}

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

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

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

برای تعیین اینکه آیا بازار دارای صفحه ساعت فعال است یا خیر:

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

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

برای استفاده از این قابلیت:

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

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

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

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

Watch Face Push ابزاری را برای برنامه بازار فراهم می کند تا صفحه ساعت فعال را تنظیم کند.

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

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

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    ...
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />
</manifest>

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

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

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

watchFacePushManager.setWatchFaceAsActive(slotId)

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

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

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

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

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

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

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

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

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

watchFaceDetails
    .getMetaDataValues("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()

ملاحظات

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

قدرت

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

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

ذخیره سازی

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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