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

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

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

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

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

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

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

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

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

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

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))
HealthConnectManager.kt

سجلات بوحدات القياس

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

في نوع البيانات هذا، يتم تمثيل جميع العناصر الغذائية بوحدات الكتلة، بينما يتم تمثيل 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.activelyRecorded(
        device = Device(type = Device.TYPE_PHONE)
    )
)
HealthConnectManager.kt

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

يمكن لتطبيق 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.activelyRecorded(
        device = Device(type = Device.TYPE_WATCH)
    ))
HealthConnectManager.kt

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

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

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
HealthConnectManager.kt

val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
HealthConnectActivity.kt

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

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

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

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))
HealthConnectManager.kt

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

إذا كنت بحاجة إلى تغيير سجلّ واحد أو أكثر، خاصةً عندما تحتاج إلى مزامنة مخزن بيانات تطبيقك مع البيانات من 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
    }
}
HealthConnectManager.kt

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

إذا كنت تستخدم قيمتَي "رقم تعريف سجلّ العميل" و"إصدار سجلّ العميل" الاختياريتَين، ننصحك باستخدام insertRecords بدلاً من updateRecords.

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

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

 fun pullStepsFromDatastore(startTime: Instant, endTime: Instant) : 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.activelyRecorded(
            clientRecordId = "Your client record ID",
            clientRecordVersion = 0L,
            device = Device(type = Device.TYPE_WATCH)
        ),
        startTime = startTime,
        startZoneOffset = startTime.atZone(ZoneId.of("PST")).offset,
        endTime = endTime,
        endZoneOffset = endTime.atZone(ZoneId.of("PST")).offset,
        count = 120
    )
    appStepsRecords.add(sr)
    // ...
    return appStepsRecords
}

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

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

upsertSteps(healthConnectClient, pullStepsFromDatastore(
    startTime = startTime,
    endTime = endTime
))
HealthConnectManager.kt

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

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

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

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.activelyRecorded(
        clientRecordId = "Your supplied record ID",
        clientRecordVersion = 0L, // Your supplied record version
        device = Device(type = Device.TYPE_WATCH)
    )
)
HealthConnectManager.kt

لا تؤدي عمليات الإضافة أو التعديل إلى زيادة قيمة version تلقائيًا عند حدوث تغييرات، ما يمنع أي حالات غير متوقعة لاستبدال البيانات. وبالتالي، عليك إدخال قيمة أعلى يدويًا.

إرشادات عامة

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

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

• recordingMethod: بالنسبة إلى البيانات التي يتم تسجيلها تلقائيًا أو يدويًا، نتوقّع أن يتم تعديل طريقة التسجيل لتعكس نوع النشاط الذي تم تسجيله:
  • RECORDING_METHOD_AUTOMATICALLY_RECORDED: إذا تم تسجيل البيانات تلقائيًا، على سبيل المثال، إذا رصد سوار اللياقة البدنية تلقائيًا أنّ المستخدم ذهب للجري.
  • ‫RECORDING_METHOD_ACTIVELY_RECORDED: إذا بدأ المستخدم نشاطًا جديدًا، مثل ركوب الدراجة على جهازه القابل للارتداء
  • ‫RECORDING_METHOD_MANUAL_ENTRY: إذا أدخل المستخدم البيانات يدويًا
• device.type: عليك تحديد نوع جهاز من أحد أنواع Device المتوافقة.
• ‫device.manufacturer: الشركة المصنّعة للجهاز، مثل "Fitbit".
• ‫device.model: طراز الجهاز، مثل "Charge 3".
• ‫device.udi: (اختيارية) معرّف الجهاز (DI) الذي يمثّل جزءًا من معرّف الجهاز الفريد (UDI) للجهاز الطبي للاطّلاع على تفاصيل حول الإذن المطلوب وإرشادات الخصوصية، يُرجى الرجوع إلى دليل البيانات الوصفية.

من المهم ضبط البيانات الوصفية بشكل صحيح لضمان شفافية البيانات ومساعدة المستخدمين في فهم مصدر معلوماتهم الصحية. للاطّلاع على التفاصيل الكاملة، يُرجى الرجوع إلى دليل البيانات الوصفية في Health Connect.

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

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

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

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

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

val endTime = Instant.now()
val startTime = endTime.minus(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(Duration.ofMinutes(minutesBetweenSamples)),
        startZoneOffset = zoneOffset,
        endTime = sampleTime,
        endZoneOffset = zoneOffset,
        count = Random.nextLong(1, 100),
        metadata = Metadata.activelyRecorded(device = Device(type = Device.TYPE_WATCH)),
    )
    sampleTime = sampleTime.plus(Duration.ofMinutes(minutesBetweenSamples))
}
healthConnectClient.insertRecords(
    stepsRecords
)
HealthConnectManager.kt

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

معدّل تكرار الكتابة ودرجة الدقة

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

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

إرشادات إضافية

اتّبِع الإرشادات التالية عند كتابة البيانات:

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

يستخدم الرمز التالي واجهة WorkManager لجدولة المهام الدورية في الخلفية، مع تحديد حد أقصى للفترة الزمنية يبلغ 15 دقيقة، وفاصل زمني مرن يبلغ 5 دقائق. يتم ضبط هذه الإعدادات باستخدام الفئة PeriodicWorkRequest.Builder.

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 ثانية. ومع ذلك، قد تمنح معدّلات البيانات الأعلى المستخدمين نظرة أكثر تفصيلاً ودقة على بيانات الصحة واللياقة البدنية. يجب أن تحقّق ترددات معدّل البيانات في الملف الصوتي توازنًا بين التفاصيل والأداء.

تنظيم السجلات لبيانات السلاسل الزمنية

بالنسبة إلى أنواع البيانات التي تستخدم سلسلة من العينات، مثل HeartRateRecord، من المهم تنظيم سجلاتك بشكل صحيح. بدلاً من إنشاء سجلّ واحد على مدار اليوم يتم تحديثه باستمرار، يجب إنشاء سجلّات متعددة أصغر حجمًا، يمثّل كل منها فترة زمنية محدّدة.

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

أثناء عمليات المزامنة المنتظمة مع Health Connect (على سبيل المثال، كل 15 دقيقة)، يجب أن يكتب تطبيقك جميع السجلات التي تبلغ مدتها دقيقة واحدة والتي تم إنشاؤها منذ المزامنة السابقة. يؤدي ذلك إلى الاحتفاظ بالسجلات بحجم يمكن إدارته وتحسين أداء الاستعلام عن البيانات ومعالجتها.

يوضّح المثال التالي كيفية إنشاء HeartRateRecord لدقيقة واحدة، يحتوي على عيّنات متعددة:

val startTime = Instant.now().truncatedTo(ChronoUnit.MINUTES)
val endTime = startTime.plus(Duration.ofMinutes(1))

val heartRateRecord = HeartRateRecord(
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    // Create a new record every minute, containing a list of samples.
    samples = listOf(
        HeartRateRecord.Sample(
            time = startTime + Duration.ofSeconds(15),
            beatsPerMinute = 80,
        ),
        HeartRateRecord.Sample(
            time = startTime + Duration.ofSeconds(30),
            beatsPerMinute = 82,
        ),
        HeartRateRecord.Sample(
            time = startTime + Duration.ofSeconds(45),
            beatsPerMinute = 85,
        )
    ),
    metadata = Metadata.activelyRecorded(
        device = Device(type = Device.TYPE_WATCH)
    ))
HealthConnectManager.kt

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

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

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

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

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

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

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

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

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

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

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

يستخدم هذا النهج أنواع البيانات وهياكلها الحالية، ويتحقّق من التوافق مع عمليات تنفيذ 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.activelyRecorded(
        device = Device(type = Device.TYPE_WATCH)
    ),
    startZoneOffset = null,
    endZoneOffset = null,
)

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

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

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

التعامل مع الاستثناءات

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

تدرج كل طريقة في HealthConnectClient الاستثناءات التي يمكن طرحها. بشكل عام، يجب أن يتعامل تطبيقك مع الاستثناءات التالية: