ضبط تطبيق Wear OS لعرض خلفية شاشة الساعة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يتيح لك 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.

العمل مع الفتحات

من المفاهيم الأساسية عند العمل مع ميزة "عرض الساعة" هي المنافذ. وتعدّ الفتحات طريقة لتحديد خلفيات شاشة الساعة المثبَّتة التي تنتمي إلى تطبيقك. يحدّد النظام الحد الأقصى لعدد الفتحات التي يمكن أن يتضمّنها السوق. في 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" />
   

ضبط خلفية شاشة الساعة النشطة

توفّر ميزة "إرسال خلفية شاشة الساعة" وسيلة لتطبيق السوق لضبط خلفية شاشة الساعة النشطة.

ويعني ذلك تحديدًا أنّه يمكن للتطبيق ضبط خلفية شاشة الساعة النشطة على خلفية تنتمي إلى السوق في حال عدم انتماء خلفية شاشة الساعة النشطة الحالية إلى السوق. يُرجى العلم أنّه في حال كان السوق يحتوي على خلفية شاشة ساعة نشطة، يتم تغييرها إلى خلفية شاشة ساعة أخرى من خلال طلب 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>

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

ضبط خلفية شاشة الساعة كخلفية نشطة

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

watchFacePushManager.setWatchFaceAsActive(slotId)

بعد استخدام هذه الطريقة، من المفترض أن يقدّم تطبيق الهاتف بدلاً من ذلك guidance على كيفية ضبط خلفية شاشة الساعة النشطة يدويًا.

قراءة البيانات الوصفية الإضافية من حزمة 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" />

يتيح استخدام خاصيّة مخصّصة لتطبيقك تحديد الصيغ التالية التي تم تثبيتها:

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

الاعتبارات

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

الطاقة

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

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.