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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

متد increaseCounter() در مثال زیر نحوه ایجاد نقشه داده و قرار دادن داده ها در آن را نشان می دهد:

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

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 ، به مستندات مرجع مراجعه کنید.

اولویت DataItem را تنظیم کنید

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

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

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

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

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

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) { ... }
    ...
}

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

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