كتابة البيانات

يتوافق هذا الدليل مع الإصدار 1.1.0-alpha12 من Health Connect.

يغطّي هذا الدليل عملية كتابة البيانات أو تعديلها في Health Connect.

التعامل مع القيم الصفرية

قد تكون قيمة بعض أنواع البيانات، مثل الخطوات أو المسافة أو السعرات الحرارية، هي 0. لا تكتب القيمة صفر إلا إذا كانت تعكس عدم النشاط الفعلي أثناء ارتداء المستخدم للجهاز. لا تكتب قيمًا صفرية إذا لم يتم ارتداء الجهاز أو إذا كانت البيانات غير متوفّرة أو إذا نفدت البطارية. في مثل هذه الحالات، احذف السجلّ لتجنُّب البيانات المضلّلة.

إعداد بنية البيانات

قبل كتابة البيانات، علينا إعداد السجلات أولاً. بالنسبة إلى أكثر من 50 نوعًا من البيانات، لكل نوع منها بنيته الخاصة. يمكنك الاطّلاع على مرجع Jetpack للحصول على مزيد من التفاصيل حول أنواع البيانات المتاحة.

السجلات الأساسية

يسجّل نوع بيانات الخطوات في Health Connect عدد الخطوات التي اتّخذها المستخدم بين القراءات. تمثّل أعداد الخطوات مقياسًا شائعًا في جميع منصات الصحة واللياقة البدنية والعافية.

يوضّح المثال التالي كيفية ضبط بيانات عدد الخطوات:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(15))

val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = ZoneOffset.UTC,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)

السجلات التي تتضمّن وحدات قياس

يمكن لتطبيق Health Connect تخزين القيم مع وحدات القياس الخاصة بها لضمان الدقة. أحد الأمثلة على ذلك هو نوع بيانات التغذية الذي يتضمّن معلومات واسعة النطاق وشاملة. وهي تتضمّن مجموعة متنوعة من حقول العناصر الغذائية الاختيارية، بدءًا من إجمالي الكربوهيدرات وصولاً إلى الفيتامينات. تمثّل كل نقطة بيانات العناصر الغذائية التي تم استهلاكها كجزء من وجبة أو طبق.

في نوع البيانات هذا، يتم تمثيل جميع العناصر الغذائية بوحدات Mass، بينما يتم تمثيل energy بوحدة Energy.

يوضّح المثال التالي كيفية ضبط بيانات التغذية لمستخدم تناول موزة:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(1))

val banana = NutritionRecord(
    name = "banana",
    energy = 105.0.kilocalories,
    dietaryFiber = 3.1.grams,
    potassium = 0.422.grams,
    totalCarbohydrate = 27.0.grams,
    totalFat = 0.4.grams,
    saturatedFat = 0.1.grams,
    sodium = 0.001.grams,
    sugar = 14.0.grams,
    vitaminB6 = 0.0005.grams,
    vitaminC = 0.0103.grams,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = ZoneOffset.UTC,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.manualEntry(
        device = Device(type = Device.TYPE_PHONE)
    )
)

السجلات التي تتضمّن بيانات سلسلة

يمكن لتطبيق Health Connect تخزين قائمة ببيانات السلسلة. أحد الأمثلة على ذلك هو نوع البيانات معدّل نبضات القلب الذي يسجّل سلسلة من عيّنات نبضات القلب التي تم رصدها بين القراءات.

في نوع البيانات هذا، يتم تمثيل المَعلمة samples بقائمة من عينات معدّل نبضات القلب. تحتوي كل عيّنة على قيمة beatsPerMinute وقيمة time.

يوضّح المثال التالي كيفية ضبط بيانات سلسلة معدّل ضربات القلب:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(5))

val heartRateRecord = HeartRateRecord(
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    // records 10 arbitrary data, to replace with actual data
    samples = List(10) { index ->
        HeartRateRecord.Sample(
            time = startTime + Duration.ofSeconds(index.toLong()),
            beatsPerMinute = 100 + index.toLong(),
        )
    },
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    ))

طلب الأذونات من المستخدم

بعد إنشاء مثيل للعميل، يحتاج تطبيقك إلى طلب أذونات من المستخدم. يجب السماح للمستخدمين بمنح الأذونات أو رفضها في أي وقت.

لإجراء ذلك، أنشئ مجموعة من الأذونات لأنواع البيانات المطلوبة. تأكَّد من أنّ الأذونات في المجموعة معرَّفة في بيان Android أولاً.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::class)
)

استخدِم getGrantedPermissions لمعرفة ما إذا كان تطبيقك قد حصل على الأذونات المطلوبة. إذا لم يكن الأمر كذلك، استخدِم createRequestPermissionResultContract لطلب هذه الأذونات. سيؤدي ذلك إلى عرض شاشة أذونات Health Connect.

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

بما أنّ المستخدمين يمكنهم منح الأذونات أو إبطالها في أي وقت، يجب أن يتحقّق تطبيقك بشكل دوري من الأذونات الممنوحة وأن يتعامل مع السيناريوهات التي يتم فيها فقدان الإذن.

كتابة البيانات

أحد إجراءات سير العمل الشائعة في Health Connect هو كتابة البيانات. لإضافة سجلّات، استخدِم insertRecords.

يوضّح المثال التالي كيفية كتابة بيانات إدراج عدد الخطوات:

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(5))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            )
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

تعديل البيانات

إذا كنت بحاجة إلى تغيير سجلّ واحد أو أكثر، خاصةً عندما تحتاج إلى مزامنة مخزن بيانات تطبيقك مع بيانات من Health Connect، يمكنك تعديل بياناتك. تتوفّر طريقتان لتعديل البيانات الحالية، وتعتمدان على المعرّف المستخدَم للعثور على السجلات.

البيانات الوصفية

من المفيد فحص الفئة Metadata أولاً لأنّها ضرورية عند تعديل البيانات. عند إنشاء كل Record في Health Connect، يتم تضمين حقل metadata. في ما يلي السمات ذات الصلة بالمزامنة:

تعديل بعد القراءة حسب النطاق الزمني

لتعديل البيانات، عليك إعداد السجلات المطلوبة أولاً. أجرِ أي تغييرات على السجلات إذا لزم الأمر. بعد ذلك، اتّصِل بالرقم updateRecords لإجراء التغييرات.

يوضّح المثال التالي كيفية تعديل البيانات. لهذا الغرض، يتم تعديل قيم إزاحة المنطقة الزمنية لكل سجل لتصبح بتوقيت المحيط الهادئ.

suspend fun updateSteps(
    healthConnectClient: HealthConnectClient,
    prevRecordStartTime: Instant,
    prevRecordEndTime: Instant
) {
    try {
        val request = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = StepsRecord::class, timeRangeFilter = TimeRangeFilter.between(
                    prevRecordStartTime, prevRecordEndTime
                )
            )
        )

        val newStepsRecords = arrayListOf<StepsRecord>()
        for (record in request.records) {
            // Adjusted both offset values to reflect changes
            val sr = StepsRecord(
                count = record.count,
                startTime = record.startTime,
                startZoneOffset = record.startTime.atZone(ZoneId.of("PST")).offset,
                endTime = record.endTime,
                endZoneOffset = record.endTime.atZone(ZoneId.of("PST")).offset,
                metadata = record.metadata
            )
            newStepsRecords.add(sr)
        }

        healthConnectClient.updateRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

إجراء عملية إدراج أو تعديل من خلال معرّف سجلّ العميل

في حال استخدام قيمتَي Client Record ID وClient Record Version الاختياريتَين، ننصحك باستخدام insertRecords بدلاً من updateRecords.

تتيح الدالة insertRecords إمكانية إدراج البيانات أو تعديلها. إذا كانت البيانات متوفّرة في Health Connect استنادًا إلى مجموعة معرّفات سجلّات العميل المحدّدة، سيتم استبدالها. بخلاف ذلك، يتم تسجيلها كبيانات جديدة. يكون هذا السيناريو مفيدًا عندما تحتاج إلى مزامنة البيانات من متجر بيانات تطبيقك مع Health Connect.

يوضّح المثال التالي كيفية إجراء عملية إدراج أو تعديل على البيانات التي تم استرجاعها من مستودع بيانات التطبيق:

suspend fun pullStepsFromDatastore() : ArrayList<StepsRecord> {
    val appStepsRecords = arrayListOf<StepsRecord>()
    // Pull data from app datastore
    // ...
    // Make changes to data if necessary
    // ...
    // Store data in appStepsRecords
    // ...
    var sr = StepsRecord(
        metadata = Metadata.autoRecorded(
            clientRecordId = "Your client record ID",
            device = Device(type = Device.TYPE_WATCH)
        ),
        // Assign more parameters for this record
    )
    appStepsRecords.add(sr)
    // ...
    return appStepsRecords
}

suspend fun upsertSteps(
    healthConnectClient: HealthConnectClient,
    newStepsRecords: ArrayList<StepsRecord>
) {
    try {
        healthConnectClient.insertRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

بعد ذلك، يمكنك استدعاء هذه الدوال في سلسلة التعليمات البرمجية الرئيسية.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

التحقّق من القيمة في "إصدار سجلّ العميل"

إذا كانت عملية إدراج البيانات أو تعديلها تتضمّن Client Record Version، سيُجري تطبيق Health Connect عمليات تحقّق للمقارنة في clientRecordVersion القيم. إذا كان الإصدار من البيانات المُدرَجة أعلى من الإصدار من البيانات الحالية، سيتم إجراء عملية الإدراج والتعديل. بخلاف ذلك، تتجاهل العملية التغيير وتبقى القيمة كما هي.

لتضمين معلومات حول الإصدارات في بياناتك، عليك تقديم قيمة Long للسمة Metadata.clientRecordVersion استنادًا إلى منطق تحديد الإصدارات.

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(15))

val stepsRecord = StepsRecord(
    count = 100L,
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.manualEntry(
        clientRecordId = "Your supplied record ID",
        clientRecordVersion = 0L, // Your supplied record version
        device = Device(type = Device.TYPE_WATCH)
    )
)

لا تزيد عمليات الإدراج والتعديل تلقائيًا قيمة version عند حدوث تغييرات، ما يمنع أي حالات غير متوقّعة من الكتابة فوق البيانات. في هذه الحالة، عليك تقديم قيمة أعلى يدويًا.

أفضل الممارسات لكتابة البيانات

يجب أن تكتب التطبيقات بيانات من مصادرها الخاصة فقط في Health Connect.

إذا تم استيراد البيانات في تطبيقك من تطبيق آخر، تقع مسؤولية تعديل البيانات في Health Connect على التطبيق الآخر.

من المستحسن أيضًا تنفيذ منطق يتعامل مع استثناءات الكتابة، مثل أن تكون البيانات خارج الحدود أو حدوث خطأ في النظام الداخلي. يمكنك تطبيق استراتيجيات التراجع وإعادة المحاولة على آلية جدولة المهام. إذا تعذّر في النهاية الكتابة إلى Health Connect، تأكَّد من أنّ تطبيقك يمكنه تجاوز نقطة التصدير هذه. لا تنسَ تسجيل الأخطاء والإبلاغ عنها للمساعدة في تشخيصها.

عند تتبُّع البيانات، هناك بعض الاقتراحات التي يمكنك اتّباعها حسب الطريقة التي يكتب بها تطبيقك البيانات.

التعامل مع المناطق الزمنية

عند كتابة سجلات مستندة إلى الوقت، تجنَّب ضبط الإزاحات على zoneOffset.UTC تلقائيًا لأنّ ذلك قد يؤدي إلى طوابع زمنية غير دقيقة عندما يكون المستخدمون في مناطق أخرى. بدلاً من ذلك، احسب الإزاحة استنادًا إلى الموقع الجغرافي الفعلي للجهاز. يمكنك استرداد المنطقة الزمنية للجهاز باستخدام ZoneId.systemDefault().

val endTime = Instant.now()
val startTime = endTime.minus(java.time.Duration.ofDays(1))
val stepsRecords = mutableListOf<StepsRecord>()
var sampleTime = startTime
val minutesBetweenSamples = 15L
while (sampleTime < endTime) {
    // Get the default ZoneId then convert it to an offset
    val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(sampleTime)
    stepsRecords += StepsRecord(
        startTime = sampleTime.minus(java.time.Duration.ofMinutes(minutesBetweenSamples)),
        startZoneOffset = zoneOffset,
        endTime = sampleTime,
        endZoneOffset = zoneOffset,
        count = Random.nextLong(1, 100),
        metadata = Metadata.unknownRecordingMethod(),
    )
    sampleTime = sampleTime.plus(java.time.Duration.ofMinutes(minutesBetweenSamples))
}
healthConnectClient.insertRecords(
    stepsRecords
)

لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات ZoneId.

التتبُّع غير النشط

ويشمل ذلك التطبيقات التي تتتبّع اللياقة البدنية أو الصحة بشكل غير مباشر، مثل تسجيل الخطوات أو معدّل نبضات القلب باستمرار في الخلفية.

يجب أن ييكتب تطبيقك البيانات بشكل دوري في Health Connect بالطرق التالية:

• عند إجراء كل عملية مزامنة، لا تكتب سوى البيانات الجديدة والبيانات المعدَّلة منذ آخر عملية مزامنة.
• قسِّم الطلبات إلى أجزاء لا تتضمّن أكثر من 1,000 سجلّ لكل طلب كتابة.
• استخدِم WorkManager لجدولة مهام دورية تعمل في الخلفية، على أن تكون الفترة الزمنية 15 دقيقة على الأقل.
• تقييد تنفيذ المهام عندما يكون الجهاز في وضع عدم النشاط ومستوى شحن البطارية ليس منخفضًا

val constraints = Constraints.Builder()
    .requiresBatteryNotLow()
    .requiresDeviceIdle(true)
    .build()

val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
        15,
        TimeUnit.MINUTES,
        5,
        TimeUnit.MINUTES
    )
    .setConstraints(constraints)
    .build()

التتبُّع النشط

ويشمل ذلك التطبيقات التي تتتبّع البيانات المستندة إلى الأحداث، مثل التمارين والنوم، أو إدخال المستخدم يدويًا، مثل التغذية. يتم إنشاء هذه السجلات عندما يكون التطبيق في المقدّمة، أو في أحداث نادرة يتم فيها استخدام التطبيق بضع مرات في اليوم.

تأكَّد من أنّ تطبيقك لا يبقي Health Connect قيد التشغيل طوال مدة الحدث.

يجب نقل البيانات إلى Health Connect بإحدى الطريقتَين التاليتَين:

• مزامنة البيانات مع Health Connect بعد اكتمال الحدث على سبيل المثال، تتم مزامنة البيانات عندما ينهي المستخدم جلسة تمرين يتم تتبُّعها.
• جدولة مهمة لمرة واحدة باستخدام WorkManager لمزامنة البيانات في وقت لاحق

أفضل الممارسات المتعلّقة بدقة البيانات وعدد مرات الكتابة

عند كتابة البيانات في Health Connect، استخدِم دقة مناسبة. يساعد استخدام الدقة المناسبة في تقليل عبء التخزين، مع الحفاظ على بيانات متسقة ودقيقة. يشمل تحليل البيانات أمرين:

1. معدّل تكرار عمليات الكتابة: عدد المرات التي يرسل فيها تطبيقك أي بيانات جديدة إلى Health Connect. على سبيل المثال، كتابة بيانات جديدة كل 15 دقيقة
2. دقة البيانات المكتوبة: عدد مرات أخذ عيّنات من البيانات التي تم إرسالها. على سبيل المثال، كتابة عيّنات معدّل نبضات القلب كل 5 ثوانٍ لا يتطلّب كل نوع من البيانات معدّل أخذ عيّنات مماثلاً. لا فائدة تُذكر من تعديل بيانات عدد الخطوات كل ثانية، مقارنةً بمعدّل أقل تكرارًا، مثل كل 60 ثانية. ومع ذلك، قد تتيح معدّلات أخذ العيّنات الأعلى للمستخدمين الاطّلاع على بيانات الصحة واللياقة البدنية بشكل أكثر تفصيلاً ودقة. يجب أن تحقق معدلات أخذ العينات توازنًا بين التفاصيل والأداء.

كتابة البيانات التي يتم تتبُّعها على مدار اليوم

بالنسبة إلى البيانات التي يتم جمعها بشكل مستمر، مثل الخطوات، يجب أن يكتب تطبيقك البيانات إلى Health Connect كل 15 دقيقة على الأقل طوال اليوم.

كتابة الجلسات

يجب كتابة البيانات في Health Connect في نهاية التمرين أو جلسة النوم.

يجب أن يلتزم تطبيقك على الأقل بالإرشادات الواردة في عمود المتوقع في الجدول التالي. اتّبِع أفضل الإرشادات حيثما أمكن ذلك.

جلسات التمرين الرياضي والنوم

يوضّح المثال التالي كيفية كتابة البيانات أثناء ممارسة التمارين الرياضية:

يوضّح المثال التالي كيفية كتابة البيانات أثناء جلسة نوم أو بعدها:

فعاليات تضمّ عدّة رياضات

يستخدم هذا النهج أنواع البيانات والبِنى الحالية، ويتحقّق من التوافق مع عمليات التنفيذ الحالية لقارئات البيانات في Health Connect. هذا النهج شائع في منصات اللياقة البدنية.

يوضّح المثال التالي كيفية كتابة بيانات خاصة بسباق ثلاثي:

val swimStartTime = Instant.parse("2024-08-22T08:00:00Z")
val swimEndTime = Instant.parse("2024-08-22T08:30:00Z")
val bikeStartTime = Instant.parse("2024-08-22T08:40:00Z")
val bikeEndTime = Instant.parse("2024-08-22T09:40:00Z")
val runStartTime = Instant.parse("2024-08-22T09:50:00Z")
val runEndTime = Instant.parse("2024-08-22T10:20:00Z")

val swimSession = ExerciseSessionRecord(
    startTime = swimStartTime,
    endTime = swimEndTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_SWIMMING_OPEN_WATER,
    metadata = Metadata.autoRecorded(
      device = Device(type = Device.TYPE_WATCH)
    )
)

val bikeSession = ExerciseSessionRecord(
    startTime = bikeStartTime,
    endTime = bikeEndTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_BIKING,
    metadata = Metadata.autoRecorded(
      device = Device(type = Device.TYPE_WATCH)
    )
)

val runSession = ExerciseSessionRecord(
    startTime = runStartTime,
    endTime = runEndTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    metadata = Metadata.autoRecorded(
      device = Device(type = Device.TYPE_WATCH)
    )
)

healthConnectClient.insertRecords(listOf(swimSession, bikeSession, runSession))