סנכרון פריטי נתונים עם ה-API של שכבת הנתונים

DataItem מגדיר את הממשק שהמערכת משתמשת בו כדי לסנכרן נתונים בין מכשירים ניידים לבין מכשירים לבישים. DataItem בדרך כלל כולל את הרכיבים הבאים:

• המטען הייעודי (Payload): מערך בייטים שאפשר להגדיר עם נתונים, וכך לבצע סריאליזציה ודה-סריאליזציה של אובייקטים. גודל המטען מוגבל ל-100KB.
• נתיב: מחרוזת ייחודית שחייבת להתחיל בלוכסן, כמו "/path/to/data".

הערה: Data Layer API יכול לשלוח הודעות ולסנכרן נתונים רק עם טלפונים עם Android או עם שעוני Wear OS. אם מכשיר Wear OS שלכם משויך למכשיר iOS, ה-API של שכבת הנתונים לא יפעל.

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

בדרך כלל לא מטמיעים את DataItem ישירות. במקום זאת, צריך לבצע את הפעולות האלה:

1. יוצרים אובייקט PutDataRequest ומציינים מחרוזת של נתיב כדי לזהות את הפריט באופן ייחודי.
2. מתקשרים אל setData() כדי להגדיר את המטען הייעודי (payload).
3. אם עיכוב בסנכרון ישפיע לרעה על חוויית המשתמש, צריך להתקשר אל setUrgent().
4. משתמשים בשיטה putDataItem של המחלקה DataClient כדי לבקש מהמערכת ליצור את פריט הנתונים.

כשמבקשים פריטי נתונים, המערכת מחזירה אובייקטים שמטמיעים כראוי את הממשק DataItem. עם זאת, במקום לעבוד עם בייטים גולמיים באמצעות setData(), מומלץ להשתמש במיפוי נתונים, שחושף פריט נתונים עם ממשק שדומה ל-Bundle.

מידע נוסף זמין באפליקציה DataLayer Sample.

סנכרון נתונים עם מפת נתונים

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

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

1. יוצרים אובייקט PutDataMapRequest ומגדירים את הנתיב של פריט הנתונים.

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

2. מתקשרים אל PutDataMapRequest.getDataMap() כדי לקבל מיפוי נתונים שאפשר להגדיר בו ערכים.
3. מגדירים ערכים למיפוי הנתונים באמצעות שיטות put...(), כמו putString().
4. אם עיכוב בסנכרון ישפיע לרעה על חוויית המשתמש, צריך להתקשר אל setUrgent().
5. מתקשרים אל PutDataMapRequest.asPutDataRequest() כדי לקבל אובייקט PutDataRequest.
6. משתמשים בשיטה putDataItem של המחלקה DataClient כדי לבקש מהמערכת ליצור את פריט הנתונים.

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

בדוגמה הבאה אפשר לראות איך יוצרים מיפוי נתונים ומכניסים אליו נתונים באמצעות המתודה increaseCounter():

private fun increaseCounter() {
    val putDataReq: PutDataRequest = PutDataMapRequest.create("/count").run {
        dataMap.putInt(COUNT_KEY, count++)
        asPutDataRequest()
    }
    val putDataTask: Task<DataItem> = dataClient.putDataItem(putDataReq)
}
DataLayerActivity.kt

מידע נוסף על טיפול ב Tasks מופיע ב מאמרי העזרה.

זהירות: לפני שמשתמשים ב-Wearable Data Layer API, צריך לבדוק שהוא זמין במכשיר. אחרת, תתרחש חריגה. משתמשים במחלקה GoogleApiAvailability כפי שהיא מוטמעת ב-Horologist.

הגדרת העדיפות של DataItem

‫ DataClient API מאפשר לשלוח בקשות דחופות לסנכרון של אובייקטים של DataItem. בדרך כלל, המערכת מעכבת את העברת פריטי הנתונים לרשת Wear OS כדי לשפר את חיי הסוללה של מכשירי המשתמשים, אבל אם עיכוב בסנכרון פריטי הנתונים פוגע בחוויית המשתמש, אפשר לסמן אותם כדחופים. לדוגמה, באפליקציית שלט רחוק שבה המשתמש מצפה שהפעולות שלו ישתקפו באופן מיידי, אפשר להגדיר שהמערכת תסנכרן את פריטי הנתונים באופן מיידי על ידי קריאה ל- setUrgent().

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

האזנה לאירועים של פריטי נתונים

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

קטע הקוד בדוגמה הבאה מודיע לאפליקציה כשהערך של המונה שהוגדר בדוגמה הקודמת משתנה:

override fun onDataChanged(dataEvents: DataEventBuffer) {

    dataEvents.forEach { event ->
        // DataItem changed
        if (event.type == DataEvent.TYPE_CHANGED) {
            event.dataItem.also { item ->
                if (item.uri.path?.compareTo("/count") == 0) {
                    DataMapItem.fromDataItem(item).dataMap.apply {
                        updateCount(getInt(COUNT_KEY))
                    }
                }
            }
        } else if (event.type == DataEvent.TYPE_DELETED) {
            // DataItem deleted
        }
    }
}
DataLayerActivity.kt

הפעילות הזו מיישמת את הממשק DataClient.OnDataChangedListener. הפעילות מוסיפה את עצמה כ-listener לאירועים של פריטי נתונים בתוך השיטה onResume() ומסירה את ה-listener בשיטה onPause(). כדי לראות הטמעה באמצעות תמונות, תצוגות מקדימות ושירותים, אפשר לעיין באפליקציית DataLayer Sample.

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