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

تتيح ميزة "إرسال خلفية شاشة الساعة" لتطبيقك إدارة خلفيات شاشة الساعة على جهاز Wear OS. ويشمل ذلك إضافة خلفيات شاشة الساعة وتعديلها وإزالتها، بالإضافة إلى ضبط خلفية شاشة الساعة النشطة. اضبط تطبيق Wear OS لاستخدام واجهة برمجة التطبيقات Watch Face Push API.

ضبط إعدادات الميزة

أدرِج العناصر التابعة اللازمة:

implementation("androidx.wear.watchfacepush:watchfacepush:1.0.0-alpha01")

أضِف ما يلي إلى 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 = WatchFacePushManagerFactory.createWatchFacePushManager(context)

توفّر الفئة WatchFacePushManager إمكانية الوصول إلى جميع طرق التفاعل مع خدمة Watch Face Push.

العمل باستخدام الخانات

عند استخدام ميزة "إرسال خلفيات شاشة الساعة"، يجب التعرّف على المفهوم الأساسي للفترات الزمنية. الفتحات هي طريقة لتحديد خلفيات شاشة الساعة المثبَّتة التي تخص تطبيقك. يحدّد النظام الحد الأقصى لعدد المساحات المتوفّرة في السوق، ويبلغ هذا الحد 1 مساحة في الإصدار Wear OS 6.

عند تعديل خلفية شاشة الساعة أو إزالتها، يتم استخدام 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.
}

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

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

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

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

ملاحظة: يجب تحديد ما إذا كان تطبيقك بحاجة إلى استدعاء removeWatchFace على الإطلاق. بدلاً من ذلك، عندما ينقر المستخدم على تطبيقك في السوق لإزالة خلفية شاشة الساعة، يمكنك استبدالها بخلفية شاشة ساعة تلقائية.

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

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

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

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

val hasActiveWatchFace = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }

تحذير: عند الاتصال بالرقم updateWatchFace()، لا تتصل بالرقم isWatchFaceActive() مباشرةً بعد ذلك لأنّ ذلك قد يؤدي إلى نتائج غير متوقّعة. قد يستغرق اكتمال عملية تبديل خلفية شاشة الساعة بعض الوقت.

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

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

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

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

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

ملاحظة: يتضمّن نمط الإنشاء النموذجي إنشاء default_watchface.apk كجزء من عملية إنشاء التطبيق بشكل عام كخطوة مسبقة. يمكنك استخدام ذلك لتعبئة قيمة ملف البيان الخاص برمز التحقّق من الصحة من خلال جعل عملية إنشاء خلفية شاشة الساعة التلقائية تعرض ملف XML إضافيًا لموارد Android وتضمين مسار الموارد هذا كمسار موارد إضافي في تطبيقك الرئيسي. هذه الطريقة أبسط من محاولة تعديل ملف البيان نفسه أثناء عملية الإنشاء.

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

توفّر خدمة Watch Face Push الوسائل اللازمة لتطبيق Marketplace من أجل ضبط خلفية شاشة الساعة النشطة.

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

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

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

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

watchFacePushManager.setWatchFaceAsActive(slotId)

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

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

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

ملاحظة: في المثال السابق، كان يجب توفير مساحة الاسم للخاصية لأنّ none تم تعريفه على الخاصية. إذا كانت السمة تتضمّن نقطة (.)، لا يكون ذلك ضروريًا، وبالتالي يمكن استرداد سمة باسم abc.def باستخدام getMetaDataValues("abc.def").

الاعتبارات

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

الطاقة

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

• أضِف زرًا إلى خلفية شاشة الساعة التلقائية لفتح تطبيق الهاتف. يمكن إجراء ذلك على مرحلتَين:

  1. أضِف عنصر Launch إلى خلفية شاشة الساعة لتفعيل هدف باستخدام تطبيق Wear OS، على سبيل المثال:

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

  2. في LaunchOnPhoneActivity، شغِّل تطبيق الهاتف باستخدام RemoteActivityHelper.