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

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() तरीके का इस्तेमाल करके यह दिखाया गया है कि डेटा मैप कैसे बनाया जाता है और उसमें डेटा कैसे डाला जाता है:

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

Tasks को मैनेज करने के बारे में ज़्यादा जानने के लिए, रेफ़रंस दस्तावेज़ देखें.

चेतावनी: Wearable Data Layer API का इस्तेमाल करने से पहले, यह देख लें कि यह किसी डिवाइस पर उपलब्ध है या नहीं. ऐसा न करने पर, एक अपवाद होता है. GoogleApiAvailability क्लास का इस्तेमाल करें. इसे Horologist में लागू किया गया है.

DataItem की प्राथमिकता सेट करना

DataClient API की मदद से, DataItem ऑब्जेक्ट को सिंक करने के लिए तुरंत अनुरोध किए जा सकते हैं. आम तौर पर, सिस्टम Wear OS नेटवर्क पर डेटा आइटम की डिलीवरी में देरी करता है, ताकि उपयोगकर्ता के डिवाइसों की बैटरी लाइफ़ को बेहतर बनाया जा सके. हालांकि, अगर डेटा आइटम को सिंक करने में देरी होने से उपयोगकर्ता अनुभव पर बुरा असर पड़ता है, तो उन्हें 'ज़रूरी' के तौर पर मार्क किया जा सकता है. उदाहरण के लिए, रिमोट कंट्रोल वाले किसी ऐप्लिकेशन में, उपयोगकर्ता को अपनी कार्रवाइयों के नतीजे तुरंत दिखने चाहिए. ऐसे में, setUrgent() को कॉल करके, सिस्टम को अपने डेटा आइटम तुरंत सिंक करने के लिए कहा जा सकता है.

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

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

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