डेटा लेयर एपीआई के साथ डेटा आइटम सिंक करना

DataItem उस इंटरफ़ेस को तय करता है जिसका इस्तेमाल सिस्टम, हैंडहेल्ड और पहनने योग्य डिवाइसों के बीच डेटा को सिंक करने के लिए करता है. DataItem में आम तौर पर ये कॉम्पोनेंट शामिल होते हैं:

• Payload: यह एक बाइट ऐरे है, जिसे डेटा के साथ सेट किया जा सकता है. इससे आपको ऑब्जेक्ट को क्रमबद्ध और क्रम से हटाने की सुविधा मिलती है. पे लोड का साइज़ 100 केबी से ज़्यादा नहीं होना चाहिए.
• पाथ: यह एक यूनीक स्ट्रिंग होती है. यह फ़ॉरवर्ड स्लैश से शुरू होनी चाहिए. जैसे, "/path/to/data".

ध्यान दें: Data Layer API, सिर्फ़ Android फ़ोन या Wear OS वाली घड़ियों के साथ मैसेज भेज सकता है और डेटा सिंक कर सकता है. अगर आपका Wear OS डिवाइस, किसी iOS डिवाइस के साथ पेयर किया गया है, तो Data Layer API काम नहीं करेगा.

इसलिए, नेटवर्क से कम्यूनिकेट करने के लिए, Data Layer API का इस्तेमाल मुख्य तरीके के तौर पर न करें. इसके बजाय, मोबाइल ऐप्लिकेशन की तरह ही पैटर्न का इस्तेमाल करें. हालांकि, इसमें कुछ मामूली अंतर हो सकते हैं.

आम तौर पर, DataItem को सीधे तौर पर लागू नहीं किया जाता. इसके बजाय, यह तरीका अपनाएं:

1. एक PutDataRequest ऑब्जेक्ट बनाएं. इसमें आइटम की खास तौर पर पहचान करने के लिए, स्ट्रिंग पाथ तय करें.
2. पेलोड सेट करने के लिए, setData() को कॉल करें.
3. अगर सिंक होने में देरी की वजह से उपयोगकर्ता अनुभव पर बुरा असर पड़ता है, तो setUrgent() को कॉल करें.
4. सिस्टम से डेटा आइटम बनाने का अनुरोध करने के लिए, DataClient क्लास के putDataItem तरीके का इस्तेमाल करें.

डेटा आइटम का अनुरोध करने पर, सिस्टम ऐसे ऑब्जेक्ट दिखाता है जो DataItem इंटरफ़ेस को सही तरीके से लागू करते हैं. हालांकि, हमारा सुझाव है कि setData() का इस्तेमाल करके रॉ बाइट के साथ काम करने के बजाय, डेटा मैप का इस्तेमाल करें. इससे Bundle जैसे इंटरफ़ेस के साथ डेटा आइटम दिखता है.

ज़्यादा जानकारी के लिए, DataLayer Sample ऐप्लिकेशन देखें.

डेटा मैप की मदद से डेटा सिंक करना

जब भी संभव हो, DataMap क्लास का इस्तेमाल करें. इस तरीके से, Android Bundle के तौर पर डेटा आइटम के साथ काम किया जा सकता है. इसलिए, सिस्टम आपके लिए ऑब्जेक्ट को क्रम से लगाने और क्रम से हटाने का काम करता है. साथ ही, की-वैल्यू पेयर की मदद से डेटा में बदलाव किया जा सकता है.

डेटा मैप का इस्तेमाल करने के लिए:

1. डेटा आइटम का पाथ सेट करके, PutDataMapRequest ऑब्जेक्ट बनाएं.

   ध्यान दें: पाथ स्ट्रिंग, डेटा आइटम के लिए एक यूनीक आइडेंटिफ़ायर होता है. इसकी मदद से, कनेक्शन के दोनों ओर से डेटा आइटम को ऐक्सेस किया जा सकता है. पाथ, फ़ॉरवर्ड स्लैश से शुरू होना चाहिए. अगर आपको अपने ऐप्लिकेशन में क्रमबद्ध डेटा का इस्तेमाल करना है, तो डेटा के स्ट्रक्चर से मेल खाने वाली पाथ स्कीम बनाएं.

2. डेटा मैप पाने के लिए PutDataMapRequest.getDataMap() को कॉल करें. इस डेटा मैप में वैल्यू सेट की जा सकती हैं.
3. put...() तरीकों का इस्तेमाल करके, डेटा मैप के लिए वैल्यू सेट करें. जैसे, putString().
4. अगर सिंक होने में देरी की वजह से उपयोगकर्ता अनुभव पर बुरा असर पड़ता है, तो setUrgent() को कॉल करें.
5. PutDataRequest ऑब्जेक्ट पाने के लिए, PutDataMapRequest.asPutDataRequest() को कॉल करें.
6. सिस्टम से डेटा आइटम बनाने का अनुरोध करने के लिए, DataClient क्लास के putDataItem तरीके का इस्तेमाल करें.

   ध्यान दें: अगर हैंडसेट और पहनने लायक डिवाइस डिसकनेक्ट हो जाते हैं, तो डेटा बफ़र हो जाता है. कनेक्शन फिर से चालू होने पर, यह सिंक हो जाता है.

यहां दिए गए उदाहरण में 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 मिनट तक का समय ले सकता है. हालांकि, आम तौर पर इसमें कुछ ही मिनट लगते हैं. डिफ़ॉल्ट रूप से, सूचना को 'ज़रूरी नहीं' के तौर पर सेट किया जाता है. इसलिए, अगर आपको Wear OS API के पिछले वर्शन की तरह ही तुरंत सिंक होने की सुविधा चाहिए, तो आपको setUrgent() का इस्तेमाल करना होगा.

डेटा आइटम के इवेंट को मॉनिटर करने की अनुमति

अगर डेटा लेयर कनेक्शन का कोई हिस्सा, डेटा आइटम में बदलाव करता है, तो कनेक्शन के दूसरे हिस्से में होने वाले किसी भी बदलाव के बारे में उपयोगकर्ता को सूचना दें. इसके लिए, डेटा आइटम इवेंट के लिए लिसनर लागू करें.

यहां दिए गए उदाहरण में, कोड स्निपेट ऐप्लिकेशन को तब सूचना देता है, जब पिछले उदाहरण में तय किए गए काउंटर की वैल्यू बदल जाती है:

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 इंटरफ़ेस लागू करती है. यह गतिविधि, onResume() तरीके के अंदर डेटा आइटम इवेंट के लिए खुद को लिसनर के तौर पर जोड़ती है. साथ ही, onPause() तरीके में लिसनर को हटाती है. इमेज, व्यू मॉडल, और सेवाओं का इस्तेमाल करके लागू करने का तरीका जानने के लिए, DataLayer का सैंपल ऐप्लिकेशन देखें.

लिसनर को सेवा के तौर पर भी लागू किया जा सकता है. ज़्यादा जानकारी के लिए, डेटा लेयर के इवेंट सुनना लेख पढ़ें.