הגדרת אפליקציית Wear OS להעברה של תצוגות שעון

התכונה 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 הוא משבצות. משבצות הן דרך להתייחס לתצוגות שעון מותקנות ששייכות לאפליקציה שלכם. המערכת מגדירה מספר מקסימלי של משבצות ששוק יכול להכיל. ב-WearOS 6, המגבלה היא 1.

כשמעדכנים או מסירים את תצוגת השעון, נעשה שימוש ב-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

בגישה הזו, תצוגת השעון תמיד תופיע בכלי לבחירת תצוגת השעון של המערכת. אתם יכולים להציג את הלוגו שלכם בצורה בולטת, ואפילו להציג לחצן להפעלת אפליקציית Marketplace בטלפון.

איך בודקים אם תצוגת השעון פעילה

חשוב לבדוק אם תצוגת השעון הפעילה מוגדרת ב-Marketplace כדי שהמשתמש ייהנה מחוויה חלקה: אם תצוגת השעון הפעילה כבר מוגדרת ב-Marketplace, המשתמש צריך רק להחליף אותה באפליקציית Marketplace כדי לבחור תצוגת שעון אחרת. עם זאת, אם תצוגת השעון הפעילה לא מוגדרת בחנות, אפליקציית הטלפון צריכה להציע למשתמש הדרכה נוספת. בקטע על אפליקציית הטלפון מוסבר איך לטפל בחוויית המשתמש הזו.

כדי לקבוע אם תצוגת השעון הפעילה מוגדרת בזירת המסחר, משתמשים בלוגיקה הבאה:

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

הוספת תצוגת שעון שמוגדרת כברירת מחדל

התכונה 'העברה של תצוגת שעון' מאפשרת להתקין תצוגת שעון שמוגדרת כברירת מחדל כשמתקינים את האפליקציה שלכם בזירת המסחר. הפעולה הזו לא מגדירה את תצוגת השעון הזו כפעילה (ראו הגדרת תצוגת השעון הפעילה), אבל היא מאפשרת לבחור את תצוגת השעון הזו במערכת.

כדי להשתמש בתכונה הזו:

1. בגרסת ה-build של אפליקציית 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

הגדרת תצוגת השעון הפעילה

ההרשאה 'העברת תצוגת שעון' מאפשרת לאפליקציה מ-Marketplace להגדיר את תצוגת השעון הפעילה.

המשמעות הספציפית היא שהאפליקציה יכולה להגדיר את תצוגת השעון הפעילה לאחת ששייכת ל-Marketplace, במקרה שתצוגת השעון הפעילה הנוכחית לא שייכת ל-Marketplace. שימו לב: אם תצוגת השעון הפעילה כבר קיימת בחנות, כדי להחליף אותה בתצוגת שעון אחרת צריך לבצע קריאה אל updateWatchFace כדי להחליף את התוכן של משבצת תצוגת השעון בתצוגת שעון אחרת.

הגדרת תצוגת השעון הפעילה היא תהליך דו-שלבי:

1. קבלת הרשאת Android שנדרשת להגדרת תצוגת השעון הפעילה.
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 של Watch Face Format.

השוני הקל הזה משתקף בכל אחד מארבעת קובצי ה-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:

1. האפליקציה צריכה לפעול כמה שפחות ובאינטרוולים כמה שיותר ארוכים (אלא אם המשתמש מקיים איתה אינטראקציה ישירה). הם כוללים:
   • מזעור ההפעלה של האפליקציה מאפליקציית הטלפון
   • צמצום ההרצה של משימות WorkManager
2. תזמון של דיווח Analytics בזמן שהשעון בטעינה:
   1. אם רוצים לדווח על נתוני שימוש מאפליקציית Wear OS או על מדדים אחרים, צריך להשתמש ב-WorkManager עם האילוץ requiresCharging.
3. קביעת עדכונים מתוזמנים לזמן הטעינה של השעון ושימוש ב-Wi-Fi:
   1. כדאי לבדוק את הגרסאות של תצוגות השעון המותקנות ולעדכן אותן באופן אוטומטי. שוב, משתמשים באילוץ requiresCharging ובסוג הרשת UNMETERED בשביל requiresNetworkType.
   2. בזמן הטעינה, סביר להניח שיש למכשיר גישה ל-Wi-Fi. מבקשים להשתמש ב-Wi-Fi כדי להוריד במהירות את קובצי ה-APK המעודכנים, ומשחררים את הרשת בסיום.
   3. אותן הנחיות חלות גם אם הפלטפורמה מציעה רקע לשעון של היום. כדאי להוריד אותו מראש בזמן שהשעון נטען.
4. אל תתזמנו משימות לבדיקת תצוגת השעון הפעילה:
   1. בדיקה תקופתית אם תצוגת השעון עדיין פעילה בשוק ומהי תצוגת השעון גורמת לניקוז הסוללה. מומלץ להימנע מהגישה הזו.
5. לא להשתמש בהתראות בשעון:
   1. אם האפליקציה משתמשת בהתראות, כדאי להתמקד בהצגת ההתראות בטלפון, כי פעולת המשתמש פותחת את האפליקציה בטלפון כדי להמשיך את התהליך. הגדרת הודעות שלא יועברו לאפליקציית השעון באמצעות setLocalOnly.

הופך לקובץ שמור

בדוגמה של זירת מסחר קנונית, תצוגות השעון מועברות מהטלפון לשעון. החיבור הזה הוא בדרך כלל חיבור Bluetooth, שיכול להיות איטי מאוד.

כדי לשפר את חוויית המשתמש ולחסוך בצריכת החשמל של השידור החוזר, כדאי להטמיע מטמון קטן במכשיר Wear OS כדי לאחסן כמה קובצי APK.

אם המשתמש מנסה להשתמש בלוח שעון אחר אבל מחליט לחזור ללוח השעון הקודם, הפעולה הזו מתבצעת כמעט באופן מיידי.

באופן דומה, אפשר להשתמש בזה כדי לבצע אחסון במטמון מראש של תצוגת השעון של היום או של תוכניות דומות שבהן תצוגות השעון מורדות בזמן שמכשיר Wear OS נטען.

עדכון של תצוגות שעון בחבילה

יכול להיות שהאפליקציה שלך כוללת נכס של תצוגת שעון שמוגדר כברירת מחדל, כפי שמתואר למעלה. חשוב להבין שגם אם פני השעון האלה מותקנים במערכת כשמתקינים את אפליקציית השוק, הם לא מתעדכנים אם גרסה חדשה יותר מצורפת לעדכון של אפליקציית השוק.

כדי לטפל במצב הזה, אפליקציית המרקטפלייס צריכה להאזין לפעולת השידור MY_PACKAGE_REPLACED ולבדוק אם צריך לעדכן תצוגת שעון שצורפה מנכסי החבילה.

תצוגת שעון מייצגת שמוגדרת כברירת מחדל

תצוגת שעון שמוגדרת כברירת מחדל היא דרך מצוינת לעזור למשתמשים לגלות את המרקטפלייס שלכם ולהשתמש בו: תצוגת השעון מותקנת כשהמרקטפלייס מותקן, כך שהמשתמשים יכולים למצוא אותה בגלריה של תצוגות השעון.

כמה דברים שכדאי לדעת כשמשתמשים בלוחות שעון שמוגדרים כברירת מחדל:

• אל תשתמשו ב-removeWatchFace אם המשתמש בוחר להסיר תצוגת שעון מאפליקציית Marketplace שלכם. במקרה כזה, צריך להחזיר את תצוגת השעון לתצוגת ברירת המחדל באמצעות updateWatchFace. כך המשתמשים יכולים למצוא את תצוגת השעון ולהגדיר אותה מהגלריה.
• תצוגת השעון שמוגדרת כברירת מחדל צריכה להיות פשוטה וניתנת לזיהוי מיידי באמצעות הלוגו והעיצוב שלכם. כך המשתמשים יכולים למצוא את תצוגת השעון בגלריה.

• להוסיף כפתור לתצוגת השעון שמוגדרת כברירת מחדל כדי לפתוח את אפליקציית הטלפון. אפשר לעשות את זה בשני שלבים:

  1. כדי להפעיל intent באמצעות אפליקציית Wear OS, מוסיפים רכיב Launch לתצוגת השעון, למשל:

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

  2. ב-LaunchOnPhoneActivity, מפעילים את אפליקציית הטלפון באמצעות RemoteActivityHelper.