डेटा सिंक करें

यह गाइड, Health Connect के 1.1.0-alpha12 वर्शन के साथ काम करती है.

Health Connect के साथ इंटिग्रेट होने वाले ज़्यादातर ऐप्लिकेशन का अपना डेटा स्टोर होता है. यह डेटा स्टोर, डेटा का मुख्य सोर्स होता है. Health Connect, आपके ऐप्लिकेशन को सिंक रखने के तरीके उपलब्ध कराता है.

आपके ऐप्लिकेशन के आर्किटेक्चर के हिसाब से, सिंक करने की प्रोसेस में इनमें से कुछ या सभी कार्रवाइयां शामिल हो सकती हैं:

• अपने ऐप्लिकेशन के डेटास्टोर से, Health Connect में नया या अपडेट किया गया डेटा भेजें.
• Health Connect से डेटा में हुए बदलावों को अपने ऐप्लिकेशन के डेटास्टोर में पुल करें.
• जब आपके ऐप्लिकेशन के डेटास्टोर से डेटा मिटा दिया जाता है, तब Health Connect से भी डेटा मिटा दिया जाता है.

हर मामले में, पक्का करें कि सिंक करने की प्रोसेस के दौरान, Health Connect और आपके ऐप्लिकेशन के डेटा स्टोर, दोनों को अलाइन किया गया हो.

Health Connect को डेटा देना

सिंक करने की प्रोसेस का पहला हिस्सा यह है कि आपके ऐप्लिकेशन के डेटास्टोर से डेटा को Health Connect के डेटास्टोर में भेजा जाए.

अपना डेटा तैयार करना

आम तौर पर, आपके ऐप्लिकेशन के डेटास्टोर में मौजूद रिकॉर्ड में यह जानकारी होती है:

• कोई यूनीक कुंजी, जैसे कि UUID.
• वर्शन या टाइमस्टैंप.

Health Connect में डेटा सिंक करते समय, सिर्फ़ उस डेटा की पहचान करें और उसे फ़ीड करें जिसे पिछले सिंक के बाद से डाला गया है, अपडेट किया गया है या मिटाया गया है.

Health Connect में डेटा सेव करना

Health Connect में डेटा फ़ीड करने के लिए, यह तरीका अपनाएं:

1. अपने ऐप्लिकेशन के डेटास्टोर से, नई, अपडेट की गई या मिटाई गई एंट्री की सूची पाएं.
2. हर एंट्री के लिए, उस डेटा टाइप के हिसाब से Record ऑब्जेक्ट बनाएं. उदाहरण के लिए, वज़न से जुड़े डेटा के लिए WeightRecord ऑब्जेक्ट बनाएं.

3. हर Record के लिए एक Metadata ऑब्जेक्ट बताएं. इसमें clientRecordId शामिल है. यह आपके ऐप्लिकेशन के डेटास्टोर का आईडी है. इसका इस्तेमाल, रिकॉर्ड की खास तौर पर पहचान करने के लिए किया जा सकता है. इसके लिए, अपनी मौजूदा यूनीक कुंजी का इस्तेमाल किया जा सकता है. अगर आपके डेटा का वर्शन बनाया गया है, तो clientRecordVersion भी दें. यह clientRecordVersion, आपके डेटा में इस्तेमाल किए गए वर्शन के हिसाब से होना चाहिए. अगर यह वर्शन में नहीं है, तो मौजूदा टाइमस्टैंप की Long वैल्यू का इस्तेमाल किया जा सकता है.

   val recordVersion = 0L
   // Specify as needed
   // The clientRecordId is an ID that you choose for your record. This
   // is often the same ID you use in your app's datastore.
   val clientRecordId = "<your-record-id>"
   
   val record = WeightRecord(
       metadata = Metadata.activelyRecorded(
           clientRecordId = clientRecordId,
           clientRecordVersion = recordVersion,
           device = Device(type = Device.TYPE_SCALE)
       ),
       weight = Mass.kilograms(62.0),
       time = Instant.now(),
       zoneOffset = ZoneOffset.UTC,
   )
   healthConnectClient.insertRecords(listOf()(record))
   
   

4. insertRecords का इस्तेमाल करके, Health Connect में डेटा अपसर्ट करें. डेटा को अपसर्ट करने का मतलब है कि Health Connect में मौजूद कोई भी डेटा तब तक बदलता रहेगा, जब तक Health Connect के डेटास्टोर में clientRecordId की वैल्यू मौजूद हैं और clientRecordVersion की वैल्यू, मौजूदा वैल्यू से ज़्यादा है. ऐसा न होने पर, अपसर्ट किए गए डेटा को नए डेटा के तौर पर लिखा जाता है.

   healthConnectClient.insertRecords(arrayListOf(record))
   

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

Health Connect आईडी सेव करता है

अगर आपका ऐप्लिकेशन, Health Connect से भी डेटा ऐक्सेस करता है, तो Health Connect id को अपडेट करने के बाद, उसे सेव करें. Health Connect से डेटा में हुए बदलावों को वापस लाने पर, आपको डेटा मिटाने की प्रोसेस पूरी करने के लिए इस id की ज़रूरत होगी.

insertRecords फ़ंक्शन, InsertRecordsResponse दिखाता है. इसमें id वैल्यू की सूची होती है. जवाब का इस्तेमाल करके, रिकॉर्ड आईडी पाएं और उन्हें सेव करें.

val response = healthConnectClient.insertRecords(arrayListOf(record))

for (recordId in response.recordIdsList) {
    // Store recordId to your app's datastore
}

Health Connect से डेटा पाना

सिंक करने की प्रोसेस का दूसरा हिस्सा यह है कि Health Connect से आपके ऐप्लिकेशन के डेटास्टोर में डेटा के किसी भी बदलाव को पुल किया जाए. डेटा में बदलावों में अपडेट और मिटाने की कार्रवाइयां शामिल हो सकती हैं.

बदलाव का टोकन पाना

Health Connect से बदलावों की सूची पाने के लिए, आपके ऐप्लिकेशन को बदलाव टोकन को ट्रैक करना होगा. इनका इस्तेमाल, डेटा में हुए बदलावों की सूची और अगली बार इस्तेमाल करने के लिए नया Changes टोकन, दोनों पाने के लिए Changes का अनुरोध करते समय किया जा सकता है.

बदलाव टोकन पाने के लिए, getChangesToken को कॉल करें और ज़रूरी डेटा टाइप दें.

val changesToken = healthConnectClient.getChangesToken(
    ChangesTokenRequest(recordTypes = setOf(WeightRecord::class))
)

डेटा में हुए बदलावों की जांच करना

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

1. बदलावों की सूची पाने के लिए, टोकन का इस्तेमाल करके getChanges को कॉल करें.
2. हर बदलाव की जांच करें कि वह UpsertionChange या DeletionChange किस तरह का बदलाव है. इसके बाद, ज़रूरी कार्रवाइयां करें.
   • UpsertionChange के लिए, सिर्फ़ उन बदलावों को शामिल करें जो कॉलिंग ऐप्लिकेशन से नहीं किए गए हैं. इससे यह पक्का किया जा सकेगा कि डेटा को फिर से इंपोर्ट न किया जाए.
3. अगले बदलाव टोकन को अपना नया टोकन असाइन करें.
4. जब तक कोई बदलाव न बचे, तब तक पहले से तीसरे चरण को दोहराएं.
5. यह कुकी, अगले टोकन को सेव करती है और उसे आने वाले समय में इंपोर्ट करने के लिए रिज़र्व करती है.

suspend fun processChanges(token: String): String {
    var nextChangesToken = token
    do {
        val response = healthConnectClient.getChanges(nextChangesToken)
        response.changes.forEach { change ->
            when (change) {
                is UpsertionChange ->
                    if (change.record.metadata.dataOrigin.packageName != context.packageName) {
                        processUpsertionChange(change)
                    }
                is DeletionChange -> processDeletionChange(change)
            }
        }
        nextChangesToken = response.nextChangesToken
    } while (response.hasMore)
    // Return and store the changes token for use next time.
    return nextChangesToken
}

डेटा पाने के लिए, व्यावहारिक बातों के बारे में जानने के लिए, डेटा सिंक करने के सबसे सही तरीके देखें.

डेटा में हुए बदलावों को प्रोसेस करना

आपके ऐप्लिकेशन के डेटास्टोर में बदलावों को दिखाएं. रिकॉर्ड को अपसर्ट करने के लिए, UpsertionChange के लिए id और metadata से lastModifiedTime का इस्तेमाल करें. DeletionChange के लिए, रिकॉर्ड को मिटाने के लिए दिए गए id का इस्तेमाल करें. इसके लिए, आपको id का रिकॉर्ड सेव करना होगा. इसके बारे में Health Connect आईडी सेव करना लेख में बताया गया है.

Health Connect से डेटा मिटाना

जब कोई उपयोगकर्ता आपके ऐप्लिकेशन से अपना डेटा मिटाता है, तो पक्का करें कि वह डेटा Health Connect से भी हटा दिया गया हो. इसके लिए, deleteRecords का इस्तेमाल करें. यह रिकॉर्ड टाइप और id और clientRecordId वैल्यू की सूची लेता है. इससे एक साथ कई डेटा को मिटाना आसान हो जाता है. timeRangeFilter को इनपुट के तौर पर इस्तेमाल करने वाला एक deleteRecords भी उपलब्ध है.

वियरेबल डिवाइसों से कम इंतज़ार के समय में डेटा सिंक करने की सुविधा

अगर आपको कम समय में, पहनने लायक फ़िटनेस डिवाइस से Health Connect पर डेटा सिंक करना है, तो CompanionDeviceService का इस्तेमाल करें. यह तरीका, उन डिवाइसों के लिए काम करता है जो BLE GATT सूचनाओं या इंडिकेशन के साथ काम करते हैं. साथ ही, यह Android 8.0 (एपीआई लेवल 26) या इसके बाद के वर्शन को टारगेट करता है. CompanionDeviceService से, आपके ऐप्लिकेशन को पहनने लायक डिवाइसों से डेटा पाने और उसे Health Connect में सेव करने की अनुमति मिलती है. ऐसा तब भी किया जा सकता है, जब ऐप्लिकेशन पहले से न चल रहा हो. बीएलई के सबसे सही तरीकों के बारे में ज़्यादा जानने के लिए, Bluetooth Low Energy की खास जानकारी देखें.

डिवाइस को जोड़ना

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

मेनिफ़ेस्ट में सेवा की जानकारी देना

इसके बाद, अपने ऐप्लिकेशन की मेनिफ़ेस्ट फ़ाइल में CompanionDeviceService का एलान करें. अपनी AndroidManifest.xml में यह जोड़ें:

<manifest ...>
   <application ...>
       <service
           android:name=".MyWearableService"
           android:exported="true"
           android:permission="android.permission.BIND_COMPANION_DEVICE_SERVICE">
           <intent-filter>
               <action android:name="android.companion.CompanionDeviceService" />
           </intent-filter>
       </service>
   </application>
</manifest>

Create CompanionDeviceService

आखिर में, CompanionDeviceService को बढ़ाने वाली क्लास बनाएं. यह सेवा, पहने जाने वाले डिवाइस से कनेक्शन को मैनेज करती है. साथ ही, BLE GATT कॉलबैक के ज़रिए डेटा हासिल करती है. नया डेटा मिलने पर, उसे तुरंत Health Connect में सेव कर दिया जाता है.

import android.companion.CompanionDeviceService
import android.bluetooth.BluetoothGatt
import android.bluetooth.BluetoothGattCallback
import android.bluetooth.BluetoothGattCharacteristic
import androidx.health.connect.client.permission.HealthPermission
import androidx.health.connect.client.HealthConnectClient
import androidx.health.connect.client.records.HeartRateRecord
import androidx.health.connect.client.records.StepsRecord
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch

class MyWearableService : CompanionDeviceService() {

   // A coroutine scope for handling suspend functions like writing to Health Connect
   private val serviceScope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
   private var healthConnectClient: HealthConnectClient? = null
   private var bluetoothGatt: BluetoothGatt? = null

   // This is called by the system when your wearable connects
   override fun onDeviceAppeared(address: String) {
       super.onDeviceAppeared(address)
       healthConnectClient = HealthConnectClient.getOrCreate(this)

       serviceScope.launch {
           // Check which permissions have been granted before subscribing to data from the wearable.
           // A service cannot request permissions, so your app must have already requested
           // and been granted them from an Activity.
           val granted = healthConnectClient?.permissionController?.getGrantedPermissions()

           // ... set up your GATT connection here ...

           // Once connected, subscribe to notifications for the data types you have
           // permission to write.
           if (granted?.contains(HealthPermission.getWritePermission(HeartRateRecord::class)) == true) {
               // subscribeToHeartRate(bluetoothGatt)
           }
       }
   }

   // The core of your low-latency pipeline is the BLE callback
   private val gattCallback = object : BluetoothGattCallback() {
       override fun onCharacteristicChanged(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, value: ByteArray) {
           super.onCharacteristicChanged(gatt, characteristic, value)

           // 1. Instantly receive the data
           val rawData = value

           // 2. Parse the data from the wearable
           val healthData = parseWearableData(rawData) // Your custom parsing logic

           // 3. Immediately process it. For simplicity, this example writes
           //    directly to Health Connect. A real-world app might write to its
           //    own datastore first and then sync with Health Connect.
           serviceScope.launch {
               writeToHealthConnect(healthData)
           }
       }
   }

   private suspend fun writeToHealthConnect(healthData: HealthData) {
       val records = prepareHealthConnectRecords(healthData) // Convert to Health Connect records
       try {
           healthConnectClient?.insertRecords(records)
       } catch (e: Exception) {
           // Handle exceptions
       }
   }

   // This is called by the system when your wearable disconnects
   override fun onDeviceDisappeared(address: String) {
       super.onDeviceDisappeared(address)
       // Clean up your GATT connection and other resources
       bluetoothGatt?.close()
   }
}

डेटा सिंक करने के सबसे सही तरीके

सिंक करने की प्रोसेस पर इन बातों का असर पड़ता है.

टोकन के खत्म होने की अवधि

इस्तेमाल नहीं किया गया Changes टोकन, 30 दिनों में खत्म हो जाता है. इसलिए, आपको सिंक करने की ऐसी रणनीति का इस्तेमाल करना होगा जिससे इस तरह के मामले में जानकारी न मिटे. आपकी रणनीति में ये तरीके शामिल हो सकते हैं:

• अपने ऐप्लिकेशन के डेटास्टोर में, हाल ही में इस्तेमाल किया गया ऐसा रिकॉर्ड खोजें जिसमें Health Connect से मिला id भी शामिल हो.
• Health Connect से ऐसे रिकॉर्ड का अनुरोध करें जो किसी खास टाइमस्टैंप से शुरू होते हैं. इसके बाद, उन्हें अपने ऐप्लिकेशन के डेटा स्टोर में डालें या अपडेट करें.
• बदलावों के टोकन का अनुरोध करें, ताकि अगली बार ज़रूरत पड़ने पर इसे रिज़र्व किया जा सके.

सुझाए गए बदलावों को मैनेज करने की रणनीतियां

अगर आपके ऐप्लिकेशन को अमान्य या समयसीमा खत्म हो चुके Changes टोकन मिल रहे हैं, तो हम आपको इन टोकन को मैनेज करने की ये रणनीतियां अपनाने का सुझाव देते हैं. ये रणनीतियां, आपके लॉजिक में इनके इस्तेमाल पर निर्भर करती हैं:

• पूरा डेटा पढ़ें और डुप्लीकेट डेटा हटाएं. यह सबसे सही रणनीति है.
  • यह कुकी, उस टाइमस्टैंप को सेव करती है जब उपयोगकर्ता ने आखिरी बार Health Connect से डेटा पढ़ा था.
  • टोकन की समयसीमा खत्म होने पर, सबसे नए टाइमस्टैंप या पिछले 30 दिनों का सारा डेटा फिर से पढ़ें. इसके बाद, आइडेंटिफ़ायर का इस्तेमाल करके, पहले से पढ़े गए डेटा से डुप्लीकेट डेटा हटाएं.
  • हमारा सुझाव है कि Client-ID लागू करें, क्योंकि डेटा अपडेट करने के लिए इनकी ज़रूरत होती है.
• सिर्फ़ उस डेटा को पढ़ो जिसे आखिरी बार पढ़े जाने के टाइमस्टैंप के बाद से जोड़ा गया है. इस वजह से, बदलावों के टोकन की समयसीमा खत्म होने के दौरान कुछ डेटा में अंतर दिखता है. हालांकि, यह अंतर कुछ घंटों से लेकर कुछ दिनों तक ही रहता है.
  • यह कुकी, उस टाइमस्टैंप को सेव करती है जब उपयोगकर्ता ने आखिरी बार Health Connect से डेटा पढ़ा था.
  • टोकन की समयसीमा खत्म होने पर, इस टाइमस्टैंप से आगे का सारा डेटा पढ़ें.
• पिछले 30 दिनों का डेटा मिटाएं और फिर उसे पढ़ें. यह पहले इंटिग्रेशन के दौरान होने वाली प्रोसेस से ज़्यादा मेल खाता है.
  • ऐप्लिकेशन ने पिछले 30 दिनों में Health Connect से जो डेटा पढ़ा है उसे मिटाएं.
  • मिटाने के बाद, इस पूरे डेटा को फिर से पढ़ें.
• पिछले 30 दिनों का डेटा पढ़ें. इसमें डुप्लीकेट डेटा शामिल नहीं किया गया है. यह सबसे कम सही रणनीति है. इससे उपयोगकर्ताओं को डुप्लीकेट डेटा दिखता है.
  • ऐप्लिकेशन ने पिछले 30 दिनों में Health Connect से जो डेटा ऐक्सेस किया है उसे मिटाएं.
  • डुप्लीकेट एंट्री की अनुमति दें.

डेटा टाइप बदलने वाले टोकन

अगर आपका ऐप्लिकेशन एक से ज़्यादा तरह के डेटा का इस्तेमाल करता है, तो हर तरह के डेटा के लिए अलग-अलग Changes Tokens का इस्तेमाल करें. Changes Sync API के साथ, एक से ज़्यादा डेटा टाइप की सूची का इस्तेमाल सिर्फ़ तब करें, जब इन डेटा टाइप का इस्तेमाल एक साथ किया जाता हो या इनका इस्तेमाल न किया जाता हो.

फ़ोरग्राउंड में पढ़ने की सुविधा

ऐप्लिकेशन, सिर्फ़ फ़ोरग्राउंड में होने पर Health Connect से डेटा पढ़ सकते हैं. Health Connect से डेटा सिंक करते समय, Health Connect का ऐक्सेस किसी भी समय बंद हो सकता है. उदाहरण के लिए, Health Connect से ज़्यादा डेटा पढ़ने के दौरान, अगर सिंक करने की प्रोसेस में रुकावट आती है, तो आपके ऐप्लिकेशन को इसे मैनेज करना होगा. साथ ही, जब अगली बार ऐप्लिकेशन खोला जाए, तो सिंक करने की प्रोसेस को जारी रखना होगा.

बैकग्राउंड में पढ़ने की सुविधा

आपके पास यह अनुरोध करने का विकल्प होता है कि आपका ऐप्लिकेशन बैकग्राउंड में चलता रहे और Health Connect से डेटा ऐक्सेस करता रहे. Background Read अनुमति का अनुरोध करने पर, उपयोगकर्ता आपके ऐप्लिकेशन को बैकग्राउंड में डेटा पढ़ने की अनुमति दे सकता है.

इंपोर्ट का समय

आपका ऐप्लिकेशन नए डेटा के बारे में सूचना नहीं पा सकता. इसलिए, दो जगहों पर नए डेटा की जांच करें:

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