همگام‌سازی عناصر داده با Data Layer API

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

• بار: آرایه‌ای از بایت‌ها که می‌توانید با داده تنظیم کنید و به شما امکان می‌دهد سریال‌سازی و سریال‌سازی معکوس شیء خودتان را انجام دهید. اندازه پایه‌بار به ۱۰۰ کیلوبایت محدود است.
• مسیر: رشته‌ای یکتا که باید با خط مورب شروع شود، مثلاً "/path/to/data".

توجه: «میانای برنامه‌سازی کاربردی لایه داده» فقط می‌تواند پیام ارسال کند و داده‌ها را با تلفن‌های Android یا ساعت‌های Wear OS همگام‌سازی کند. اگر دستگاه Wear OS شما با دستگاه iOS جفت شده باشد، «میانای برنامه‌سازی کاربردی لایه داده» کار نخواهد کرد.

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

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

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

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

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

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

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

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

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

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

2. برای دریافت نقشه داده‌ای که می‌توانید مقادیر را در آن تنظیم کنید، با PutDataMapRequest.getDataMap() تماس بگیرید.
3. بااستفاده از روش‌های put...()، مثل putString()، مقادیر را برای نقشه داده تنظیم کنید.
4. اگر تأخیر در همگام‌سازی تأثیر منفی بر تجربه کاربری داشته باشد، با setUrgent() تماس بگیرید.
5. برای دریافت شیء PutDataRequest با PutDataMapRequest.asPutDataRequest() تماس بگیرید.
6. از روش putDataItem کلاس DataClient برای درخواست ایجاد عنصر داده توسط سیستم استفاده کنید.

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

روش increaseCounter() در مثال زیر نشان می‌دهد که چگونه یک نقشه داده ایجاد کنیم و داده‌ها را در آن قرار دهیم:

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

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

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

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

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

اگر با setUrgent() تماس نگیرید، سیستم ممکن است همگام‌سازی موارد داده غیرفوری را تا ۳۰ دقیقه به‌تأخیر بیندازد، هرچند معمولاً می‌توانید انتظار داشته باشید که تأخیر فقط چند دقیقه باشد. فوریت پیش‌فرض غیرفوری است، بنابراین اگر می‌خواهید رفتار همگام‌سازی فوری را از نسخه‌های قبلی Wear OS API حفظ کنید، باید از 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 را ببینید.

همچنین می‌توانید شنونده را به‌عنوان سرویس پیاده‌سازی کنید. برای اطلاعات بیشتر، گوش دادن به رویدادهای «لایه داده» را ببینید.