موارد داده را با Data Layer API همگام سازی کنید

یک DataItem رابطی را تعریف می‌کند که سیستم برای همگام‌سازی داده‌ها بین دستگاه‌های دستی و پوشیدنی از آن استفاده می‌کند. یک DataItem عموماً از اجزای زیر تشکیل شده است:

• بار مفید (Payload): یک آرایه بایتی که می‌توانید با داده‌ها تنظیم کنید و به شما امکان می‌دهد سریال‌سازی و از سریال‌زدایی اشیاء خود را انجام دهید. اندازه بار مفید به ۱۰۰ کیلوبایت محدود شده است.
• مسیر: یک رشته منحصر به فرد که باید با یک اسلش شروع شود، مانند "/path/to/data" .

توجه: رابط برنامه‌نویسی کاربردی لایه داده (Data Layer API) فقط می‌تواند با گوشی‌های اندروید یا ساعت‌های هوشمند Wear OS پیام ارسال کند و داده‌ها را همگام‌سازی کند. اگر دستگاه Wear OS شما با یک دستگاه iOS جفت شده باشد، رابط برنامه‌نویسی کاربردی لایه داده (Data Layer API) کار نخواهد کرد.

به همین دلیل، از API لایه داده به عنوان روش اصلی برای ارتباط با شبکه استفاده نکنید. در عوض، از همان الگوی یک برنامه تلفن همراه، با برخی تفاوت‌های جزئی ، پیروی کنید.

شما معمولاً DataItem مستقیماً پیاده‌سازی نمی‌کنید. در عوض، موارد زیر را انجام می‌دهید:

1. یک شیء PutDataRequest ایجاد کنید و یک مسیر رشته‌ای برای شناسایی منحصر به فرد آیتم مشخص کنید.
2. برای تنظیم payload، تابع setData() را فراخوانی کنید.
3. اگر تأخیر در همگام‌سازی تأثیر منفی بر تجربه کاربر می‌گذارد، تابع setUrgent() را فراخوانی کنید.
4. از متد putDataItem از کلاس DataClient برای درخواست ایجاد آیتم داده توسط سیستم استفاده کنید.

هنگام درخواست اقلام داده، سیستم اشیاء را برمی‌گرداند که رابط DataItem را به درستی پیاده‌سازی می‌کنند. با این حال، به جای کار با بایت‌های خام با استفاده از setData() ، توصیه می‌کنیم از یک نقشه داده استفاده کنید که یک قلم داده را با رابطی شبیه به Bundle در معرض نمایش قرار می‌دهد.

برای اطلاعات بیشتر، به برنامه نمونه DataLayer مراجعه کنید.

همگام‌سازی داده‌ها با یک نقشه داده

در صورت امکان، از کلاس DataMap استفاده کنید. این رویکرد به شما امکان می‌دهد با اقلام داده در قالب یک Android Bundle کار کنید، بنابراین سیستم سریال‌سازی و از سریال‌زدایی اشیاء را برای شما انجام می‌دهد و می‌توانید داده‌ها را با جفت‌های کلید-مقدار دستکاری کنید.

برای استفاده از نقشه داده:

1. یک شیء PutDataMapRequest ایجاد کنید و مسیر آیتم داده را تنظیم کنید.

   نکته: رشته مسیر، یک شناسه منحصر به فرد برای آیتم داده است که به شما امکان دسترسی به آن را از هر دو طرف اتصال می‌دهد. مسیر باید با یک اسلش (/) شروع شود. اگر در برنامه خود از داده‌های سلسله مراتبی استفاده می‌کنید، یک طرح مسیر ایجاد کنید که با ساختار داده‌ها مطابقت داشته باشد.

2. برای دریافت یک نقشه داده که می‌توانید روی آن مقادیری تنظیم کنید، تابع PutDataMapRequest.getDataMap() را فراخوانی کنید.
3. با استفاده از متدهای put...() مانند putString() ، مقادیر مربوط به نقشه داده‌ها را تنظیم کنید.
4. اگر تأخیر در همگام‌سازی تأثیر منفی بر تجربه کاربر می‌گذارد، تابع setUrgent() را فراخوانی کنید.
5. برای دریافت یک شیء PutDataRequest تابع PutDataMapRequest.asPutDataRequest() را فراخوانی کنید.
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 ، به مستندات مرجع مراجعه کنید.

هشدار: قبل از استفاده از API لایه داده‌های پوشیدنی، بررسی کنید که آیا روی دستگاه موجود است یا خیر؛ در غیر این صورت، یک استثنا رخ می‌دهد. از کلاس GoogleApiAvailability ، همانطور که در Horologist پیاده‌سازی شده است، استفاده کنید.

تنظیم اولویت DataItem

رابط برنامه‌نویسی کاربردی DataClient امکان درخواست‌های فوری برای همگام‌سازی اشیاء DataItem را فراهم می‌کند. به‌طور معمول، سیستم برای بهبود عمر باتری دستگاه‌های کاربر، تحویل اقلام داده به شبکه Wear OS را به تأخیر می‌اندازد، اما اگر تأخیر در همگام‌سازی اقلام داده تأثیر منفی بر تجربه کاربر داشته باشد، می‌توانید آنها را به‌عنوان فوری علامت‌گذاری کنید. به‌عنوان مثال، در یک برنامه کنترل از راه دور که کاربر انتظار دارد اقداماتش فوراً منعکس شود، می‌توانید با فراخوانی setUrgent() از سیستم بخواهید اقلام داده شما را فوراً همگام‌سازی کند.

اگر تابع setUrgent() را فراخوانی نکنید، سیستم ممکن است تا 30 دقیقه قبل از همگام‌سازی اقلام داده‌ای غیر فوری تأخیر داشته باشد، اگرچه معمولاً می‌توانید انتظار داشته باشید که این تأخیر فقط چند دقیقه باشد. فوریت پیش‌فرض غیر فوری است، بنابراین اگر نیاز به حفظ رفتار همگام‌سازی فوری از نسخه‌های قبلی API سیستم عامل Wear OS دارید، باید از setUrgent() استفاده کنید.

به رویدادهای اقلام داده گوش دهید

اگر یک طرف اتصال لایه داده، یک آیتم داده را تغییر دهد، کاربر را از هرگونه تغییر در طرف دیگر اتصال مطلع کنید. می‌توانید این کار را با پیاده‌سازی یک شنونده برای رویدادهای آیتم داده انجام دهید.

قطعه کد در مثال زیر، هنگامی که مقدار شمارنده تعریف شده در مثال قبلی تغییر می‌کند، به برنامه اطلاع می‌دهد:

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 را پیاده‌سازی می‌کند. این فعالیت خود را به عنوان یک شنونده برای رویدادهای آیتم داده در داخل متد onResume() اضافه می‌کند و شنونده را در متد onPause() حذف می‌کند. برای مشاهده پیاده‌سازی با استفاده از تصاویر، مدل‌های نمایش و سرویس‌ها، به برنامه نمونه DataLayer مراجعه کنید.

شما همچنین می‌توانید شنونده را به عنوان یک سرویس پیاده‌سازی کنید. برای اطلاعات بیشتر، به Listen for Data Layer events مراجعه کنید.