הגדרת אפליקציית 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.
}

הערה: אל תשמרו ערכים של 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 שלכם, כדאי להחליף אותה בתצוגת שעון שמוגדרת כברירת מחדל.

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

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

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

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

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

אזהרה: כשמתקשרים אל updateWatchFace(), לא מומלץ להתקשר אל isWatchFaceActive() מיד לאחר מכן, כי זה עלול להוביל לתוצאות לא צפויות. יכול להיות שיעבור קצת זמן עד שתצוגת השעון תתחלף.

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

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

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

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

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

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

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

ההרשאה 'העברת תצוגת שעון' מאפשרת לאפליקציה מ-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).

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

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

אחרי שמעניקים את ההרשאה, מתקשרים אל setWatchFaceAsActive עם מזהה המשבצת של פני השעון שצריך להיות פעיל:

watchFacePushManager.setWatchFaceAsActive(slotId)

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

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

קריאת מטא-נתונים נוספים מקובץ ה-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()

הערה: בדוגמה הקודמת, היה צריך לציין את מרחב השמות של המאפיין כי none הוגדר במאפיין. אם הנכס כולל נקודה (.), אין צורך בכך, ולכן אפשר לאחזר נכס בשם abc.def באמצעות getMetaDataValues("abc.def").

שיקולים

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

כוח

צריכת החשמל היא שיקול חשוב בכל אפליקציה שפועלת ב-Wear OS. לרכיב Wear OS של אפליקציית ה-Marketplace:

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