ضبط تطبيق 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

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

التحقّق مما إذا كانت خلفية شاشة الساعة نشطة

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

لتحديد ما إذا كان السوق قد ضبط خلفية شاشة الساعة النشطة، استخدِم المنطق التالي:

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

توفير خلفية تلقائية لشاشة الساعة

توفّر ميزة "إرسال خلفية شاشة الساعة" إمكانية تثبيت خلفية شاشة ساعة تلقائية عند تثبيت تطبيقك على Marketplace. لا يؤدي ذلك، في حد ذاته، إلى ضبط خلفية شاشة الساعة التلقائية هذه كخلفية نشطة (راجِع قسم ضبط خلفية شاشة الساعة النشطة)، ولكنّه يتيح استخدام خلفية شاشة الساعة في أداة اختيار خلفية شاشة الساعة في النظام.

لاستخدام هذه الميزة، اتّبِع الخطوات التالية:

في إصدار تطبيق Wear OS، أدرِج خلفية شاشة الساعة التلقائية في المسار: assets/default_watchface.apk

أضِف الإدخال التالي إلى 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 الوسائل اللازمة لتطبيق Marketplace من أجل ضبط خلفية شاشة الساعة النشطة.

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

تتكوّن عملية ضبط خلفية شاشة الساعة النشطة من مرحلتَين:

الحصول على إذن Android المطلوب لضبط خلفية شاشة الساعة النشطة
استدعِ الطريقة 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

الاعتبارات

تشمل الاعتبارات المهمة عند تنفيذ ميزة "إرسال خلفية شاشة الساعة" في تطبيقك التركيز على استهلاك الطاقة والتخزين المؤقت وتعديل خلفيات شاشة الساعة المجمّعة وتوفير خلفية شاشة ساعة تلقائية تمثيلية.

الطاقة

يُعدّ استهلاك الطاقة من الاعتبارات الرئيسية لأي تطبيق يعمل على Wear OS. بالنسبة إلى مكوّن Wear OS في تطبيقك على Marketplace، اتّبِع الخطوات التالية:

يجب أن يعمل تطبيقك بأقل قدر ممكن وبأقل معدّل تكرار ممكن (إلا إذا كان المستخدم يتفاعل معه مباشرةً). ويشمل ذلك:
- تقليل عدد المرات التي يتم فيها تنشيط التطبيق من خلال تطبيق "الهاتف"
- تقليل عدد مرات تنفيذ مهام WorkManager
جدولة أي تقارير إحصائية لوقت شحن الساعة:
1. إذا أردت تسجيل إحصاءات الاستخدام من تطبيق Wear OS أو أي مقاييس أخرى، استخدِم WorkManager مع القيد requiresCharging.
جدولة التحديثات عندما تكون الساعة قيد الشحن واستخدام شبكة Wi-Fi:
1. ننصحك بالتحقّق من إصدارات خلفيات شاشة الساعة المثبَّتة وتحديثها تلقائيًا. مرة أخرى، استخدِم القيد requiresCharging ونوع الشبكة UNMETERED للسمة requiresNetworkType.
2. عندما يكون الجهاز قيد الشحن، من المحتمل أن يكون بإمكانه الاتصال بشبكة Wi-Fi. اطلب الاتصال بشبكة Wi-Fi لتنزيل حِزم APK المعدَّلة بسرعة، ثم أوقِف الاتصال بالشبكة عند الانتهاء.
3. تنطبق الإرشادات نفسها على الحالات التي قد يقدّم فيها السوق خلفية شاشة جديدة كل يوم، لذا ننصحك بتنزيلها مسبقًا أثناء شحن الساعة.
عدم جدولة مهام للتحقّق من خلفية شاشة الساعة النشطة:
1. يؤدي التحقّق بشكل دوري مما إذا كان السوق لا يزال يعرض خلفية شاشة الساعة النشطة ونوعها إلى استنزاف البطارية. تجنَّب هذا الأسلوب.
عدم استخدام الإشعارات على الساعة:
1. إذا كان تطبيقك يستخدم الإشعارات، ركِّز على عرضها على الهاتف، حيث يفتح إجراء المستخدم تطبيق الهاتف لمواصلة الرحلة. اضبط الإشعارات على عدم الانتقال إلى تطبيق الساعة باستخدام setLocalOnly.

تخزين مؤقت

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

لتقديم تجربة أفضل للمستخدمين والحفاظ على طاقة إعادة الإرسال، ننصحك بتنفيذ ذاكرة تخزين مؤقت صغيرة في جهاز Wear OS لتخزين عدد قليل من حِزم APK.

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

وبالمثل، يمكن استخدام هذه الميزة في التخزين المؤقت المسبق لخلفية شاشة الساعة اليومية أو المخططات المشابهة التي يتم فيها تنزيل خلفيات شاشة الساعة أثناء شحن جهاز Wear OS.

تحديث خلفيات شاشة الساعة المجمّعة

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

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

خلفية شاشة الساعة التلقائية التمثيلية

تُعدّ خلفية شاشة الساعة التلقائية طريقة رائعة لمساعدة المستخدمين في العثور على السوق واستخدامه، إذ يتم تثبيت خلفية شاشة الساعة عند تثبيت السوق، ما يتيح للمستخدمين العثور عليها في معرض خلفيات شاشة الساعة.

بعض الاعتبارات عند استخدام خلفيات شاشة الساعة التلقائية:

لا تستخدِم removeWatchFace إذا اختار المستخدم إلغاء تثبيت خلفية شاشة الساعة من تطبيق Marketplace، بل عليك في هذه الحالة إعادة خلفية شاشة الساعة إلى خلفية شاشة الساعة التلقائية باستخدام updateWatchFace. يساعد ذلك المستخدمين في العثور على خلفية شاشة الساعة وضبطها من المعرض.
اجعل خلفية شاشة الساعة التلقائية بسيطة ويمكن التعرّف عليها فورًا من خلال شعارك ومظهرك. يساعد ذلك المستخدمين في العثور عليها في معرض خلفيات شاشة الساعة.
أضِف زرًا إلى خلفية الساعة التلقائية لفتح تطبيق الهاتف. ويمكن إجراء ذلك على مرحلتين:
1. أضِف عنصر Launch إلى خلفية شاشة الساعة لتفعيل هدف باستخدام تطبيق Wear OS، على سبيل المثال:
  
  <Launch target="com.myapp/com.myapp.LaunchOnPhoneActivity" />
2. في LaunchOnPhoneActivity، شغِّل تطبيق الهاتف باستخدام RemoteActivityHelper.