חשיפת נתונים לסיבוכים

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

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

יצירת פרויקט של ספק נתונים

כדי ליצור פרויקט ב-Android Studio עבור האפליקציה של ספק הנתונים, מבצעים את השלבים הבאים:

  1. לוחצים על קובץ > חדש > פרויקט חדש.
  2. בחלון Project Template (תבנית פרויקט), לוחצים על הכרטיסייה Wear OS ובוחרים באפשרות אין פעילות ולוחצים על הבא.
  3. בחלון Configure Your Project, נותנים שם לפרויקט וממלאים את של הפרויקט הרגיל, ולוחצים על Finish.
  4. מערכת Android Studio יוצרת פרויקט עם מודול אפליקציה עבור ספק הנתונים. לקבלת מידע נוסף מידע על פרויקטים ב-Android Studio: יוצרים פרויקט.
  5. כדי להתחיל את השימוש באפליקציה של ספק הנתונים, צריך ליצור מחלקה חדשה שנשמרת BroadcastReceiver המטרה של הכיתה היא להקשיב בקשות לעדכון רכיבים ממערכת Wear OS. בנוסף, יוצרים כיתה חדשה שנפתחת ComplicationProviderService כדי לספק נתונים בהתאם לרכיבים המתאימים. למידע נוסף, קראו את המאמרים הבאים:

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

הטמעת שיטה לבקשות עדכון

כשיש צורך בנתונים של רכיבים, מערכת Wear OS שולחת בקשות עדכון לנתונים ספק. הבקשות מתקבלות על ידי BroadcastReceiver כדי להגיב לבקשות העדכון: שספק הנתונים צריך להטמיע onComplicationUpdate() של הComplicationProviderService בכיתה.

מערכת Wear OS שולחת קריאה ל-onComplicationUpdate() כשהיא צריכה נתונים מ- בספק – לדוגמה, כשתכונה נוספת של משתמשים בספק הופכת פעיל או כשחולף פרק זמן קבוע. הוא עובר ComplicationManager כפרמטר של onComplicationUpdate, שמשמש לשליחת נתונים חזרה למערכת.

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

קטע הקוד הבא מציג הטמעה לדוגמה של אמצעי תשלום אחד (onComplicationUpdate):

Kotlin

override fun onComplicationUpdate(
    complicationId: Int, dataType: Int, complicationManager: ComplicationManager) {

    Log.d(TAG, "onComplicationUpdate() id: $complicationId")

    // Used to create a unique key to use with SharedPreferences for this complication.
    val thisProvider = ComponentName(this, javaClass)

    // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
    val preferences = getSharedPreferences(ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0)

    val number = preferences.getInt(
            ComplicationTapBroadcastReceiver.getPreferenceKey(
                    thisProvider, complicationId),
                    0)
    val numberText = String.format(Locale.getDefault(), "%d!", number)

    var complicationData: ComplicationData? = null

    when (dataType) {
        ComplicationData.TYPE_SHORT_TEXT -> complicationData = ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                .setShortText(ComplicationText.plainText(numberText))
                .build()
        else -> if (Log.isLoggable(TAG, Log.WARN)) {
                    Log.w(TAG, "Unexpected complication type $dataType")
                }
    }

    if (complicationData != null) {
        complicationManager.updateComplicationData(complicationId, complicationData)
    } else {
        // If no data is sent, we still need to inform the ComplicationManager, so
        // the update job can finish and the wake lock isn't held any longer.
        complicationManager.noUpdateRequired(complicationId)
    }
}

Java

@Override
public void onComplicationUpdate(
       int complicationId, int dataType, ComplicationManager complicationManager) {

   Log.d(TAG, "onComplicationUpdate() id: " + complicationId);

   // Used to create a unique key to use with SharedPreferences for this complication.
   ComponentName thisProvider = new ComponentName(this, getClass());

   // Retrieves your data; in this case, grabs an incrementing number from SharedPrefs.
   SharedPreferences preferences =
     getSharedPreferences( ComplicationTapBroadcastReceiver.COMPLICATION_PROVIDER_PREFERENCES_FILE_KEY, 0);

   int number =
           preferences.getInt(
                   ComplicationTapBroadcastReceiver.getPreferenceKey(
                           thisProvider, complicationId),
                   0);
   String numberText = String.format(Locale.getDefault(), "%d!", number);

   ComplicationData complicationData = null;

   switch (dataType) {
       case ComplicationData.TYPE_SHORT_TEXT:
           complicationData =
                   new ComplicationData.Builder(ComplicationData.TYPE_SHORT_TEXT)
                           .setShortText(ComplicationText.plainText(numberText))
                           .build();
           break;
       default:
           if (Log.isLoggable(TAG, Log.WARN)) {
               Log.w(TAG, "Unexpected complication type " + dataType);
           }
   }

   if (complicationData != null) {
       complicationManager.updateComplicationData(complicationId, complicationData);

   } else {
       // If no data is sent, we still need to inform the ComplicationManager, so
       // the update job can finish and the wake lock isn't held any longer.
       complicationManager.noUpdateRequired(complicationId);
   }
}

הצהרות והרשאות במניפסט

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

במניפסט של האפליקציה צריך להצהיר על השירות ולהוסיף מסנן Intent של בקשת עדכון. כמו כן, המניפסט צריך להגן על השירות על ידי הוספת BIND_COMPLICATION_PROVIDER כדי להבטיח שרק מערכת Wear OS תוכל לקשר לשירותי הספק.

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

הנה דוגמה: 

<service
    android:name=".provider.IncrementingNumberComplicationProviderService"
    android:icon="@drawable/icn_complications"
    android:label="@string/complications_provider_incrementing_number"
    android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER">
    <intent-filter>
        <action
         android:name="android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST"/>
    </intent-filter>
</service>

ציון רכיבי המטא-נתונים

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

<meta-data
    android:name="android.support.wearable.complications.SUPPORTED_TYPES"
    android:value="RANGED_VALUE,SHORT_TEXT,LONG_TEXT" />

<meta-data
    android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
    android:value="300" />

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

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

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

הוספת פעילות של מערך הגדרות אישיות

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

<meta-data
    android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION"
    android:value="PROVIDER_CONFIG_ACTION"/>

הערך יכול להיות כל פעולה.

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

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

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

כדי להצהיר שתצוגות השעון בטוחות, הספק מוסיף מטא-נתונים עם מפתח של android.support.wearable.complications.SAFE_WATCH_FACES ערך מטא נתונים הוא רשימה מופרדת בפסיקים של WatchFaceService שמות של רכיבים, שניתנו כאילו מתבצעת שיחה אל ComponentName.flattenToString(), או שמות של חבילות אפליקציות, במקרה כזה, כל תצוגת שעון אפליקציה ספציפית נחשבת בטוחה. המערכת מתעלמת מרווחים לבנים ברשימת הערכים. לדוגמה: 

<meta-data
       android:name="android.support.wearable.complications.SAFE_WATCH_FACES"
       android:value="
          com.app.watchface/com.app.watchface.MyWatchFaceService,
          com.anotherapp.anotherwatchface/com.something.WatchFaceService,
          com.something.text"/>

הוספת תמונות בטוחות בצריבה

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

כשמציינים סמל באמצעות ComplicationData.Builder#setIcon, כולל גרסה בטוחה שצריבה באמצעות ComplicationData.Builder#setBurnInProtectionIcon

כשמציינים תמונה באמצעות ComplicationData.Builder#setSmallImage, כולל גרסה בטוחה שצריבה באמצעות ComplicationData.Builder#setBurnInProtectionSmallImage

שימוש בעדכוני Push

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

זהירות: כדי להאריך את חיי הסוללה, אל תקראו ל-requestUpdate() מהמופע של ComplicationDataSourceUpdateRequester בתדירות גבוהה יותר מאשר כל 5 דקות ביום בממוצע.

מספקים ערכים דינמיים

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

שדות לדוגמה כוללים שדה הערך הדינמי של GoalProgressComplicationData, וגם DynamicComplicationText, ואפשר להשתמש בו בכל שדה ComplicationText. הערכים הדינמיים האלה מבוססים על androidx.wear.protolayout.expression.

במצבים מסוימים, הפלטפורמה לא יכולה להעריך ערכים דינמיים:

ציינו ערכים תלויי זמן

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

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

שיעור העדכון של הרכיבים

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