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

התכונה Watch Face Push מאפשרת לאפליקציה לנהל את תצוגות השעון במכשיר 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.

עבודה עם משבצות

מושג מרכזי כשעובדים עם 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 בטלפון.

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

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

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

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

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

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

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

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

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

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

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

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

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

השוני הקל הזה משתקף בכל אחת מארבע חבילות ה-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. מתזמנים את כל הדיווחים של 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. מוסיפים רכיב Launch לתצוגת השעון כדי להפעיל intent באמצעות אפליקציית Wear OS, לדוגמה:

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

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