סנכרון פריטי נתונים עם ה-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() מראה איך ליצור מיפוי נתונים ולהוסיף אליו נתונים:

Kotlin

private const val COUNT_KEY = "com.example.key.count"

class MainActivity : Activity() {

    private lateinit var dataClient: DataClient
    private var count = 0
    ...
    // Create a data map and put data in it
    private fun increaseCounter() {
        val putDataReq: PutDataRequest = PutDataMapRequest.create("/count").run {
            dataMap.putInt(COUNT_KEY, count++)
            asPutDataRequest()
        }
        val putDataTask: Task<DataItem> = dataClient.putDataItem(putDataReq)
    }
    ...
}

Java

public class MainActivity extends Activity {
    private static final String COUNT_KEY = "com.example.key.count";
    private DataClient dataClient;
    private int count = 0;
    ...
    // Create a data map and put data in it
    private void increaseCounter() {
        PutDataMapRequest putDataMapReq = PutDataMapRequest.create("/count");
        putDataMapReq.getDataMap().putInt(COUNT_KEY, count++);
        PutDataRequest putDataReq = putDataMapReq.asPutDataRequest();
        Task<DataItem> putDataTask = dataClient.putDataItem(putDataReq);
    }
  ...
}

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

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

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

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

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

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

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

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

Kotlin

private const val COUNT_KEY = "com.example.key.count"

class MainActivity : Activity(), DataClient.OnDataChangedListener {

    private var count = 0

    override fun onResume() {
        super.onResume()
        Wearable.getDataClient(this).addListener(this)
    }

    override fun onPause() {
        super.onPause()
        Wearable.getDataClient(this).removeListener(this)
    }

    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
            }
        }
    }

    // Method to update the count
    private fun updateCount(int: Int) { ... }
    ...
}

Java

public class MainActivity extends Activity implements DataClient.OnDataChangedListener {
    private static final String COUNT_KEY = "com.example.key.count";
    private int count = 0;

    @Override
    protected void onResume() {
        super.onResume();
        Wearable.getDataClient(this).addListener(this);
    }

    @Override
    protected void onPause() {
        super.onPause();
        Wearable.getDataClient(this).removeListener(this);
    }

    @Override
    public void onDataChanged(DataEventBuffer dataEvents) {
        for (DataEvent event : dataEvents) {
            if (event.getType() == DataEvent.TYPE_CHANGED) {
                // DataItem changed
                DataItem item = event.getDataItem();
                if (item.getUri().getPath().compareTo("/count") == 0) {
                    DataMap dataMap = DataMapItem.fromDataItem(item).getDataMap();
                    updateCount(dataMap.getInt(COUNT_KEY));
                }
            } else if (event.getType() == DataEvent.TYPE_DELETED) {
                // DataItem deleted
            }
        }
    }

    // Method to update the count
    private void updateCount(int c) { ... }
    ...
}

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

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