تخطيط أنواع بيانات Health Connect ومراجعتها

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

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

فئات أنواع البيانات

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

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

تنسيق نوع البيانات

يتم تخزين أنواع البيانات في Health Connect في عناصر هي فئات فرعية من Record.

لكل نوع من أنواع البيانات، هناك حقول مرتبطة إما عامة مثل time وzoneOffset أو محدّدة مثل title وcount وpercentage. تستخدم بعض الحقول أنواعًا بسيطة، مثل long أو double أو string، بينما تستخدم حقول أخرى أنواعًا معقّدة مثل التعدادات والفئات مثل Instant و ZoneOffset. يمكن أن تكون سمات هذه الحقول مطلوبة أو اختيارية. تكون بعض السمات للقراءة فقط، وتكون بعض السمات محدودة بمجموعة معيّنة من القيم.

للحصول على القائمة الكاملة لأنواع البيانات المتاحة وحقولها، راجِع الفئات في Jetpack.

سمات البيانات الإضافية

تتضمّن البيانات في Health Connect API أيضًا سمات البيانات الوصفية описанة في القائمة التالية:

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

معرّف Health Connect

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

تذكَّر الملاحظات التالية عند العمل مع أرقام تعريف Health Connect:

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

الوقت في Health Connect

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

في حالات نادرة، قد لا يكون توقيت المنطقة متاحًا. عند حدوث ذلك في Android 14 (المستوى 34 من واجهة برمجة التطبيقات)، يضبط Health Connect توقيت المنطقة استنادًا إلى المنطقة الزمنية التلقائية للنظام على الجهاز. في الإصدار 13 من نظام التشغيل Android والإصدارات الأقدم (المستوى 33 من واجهة برمجة التطبيقات والإصدارات الأقدم)، من الممكن الكتابة إلى Health Connect بدون تحديد أي معلومات عن تعويض المنطقة، ويجب تجنُّب ذلك كلما أمكن.

ضبط الوقت والمنطقة

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

الأذونات

قبل طلب أي أذونات، يجب أن يعلن تطبيقك عنها في البيان أولاً. اطّلِع على الجداول التالية للربط الكامل لأنواع البيانات و أذوناتها.

بالنسبة إلى الإصدار 1.0.0-alpha10 والإصدارات الأحدث

مرجع الأذونات بيان أذونات القراءة
عمليات القراءة في الخلفية android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND
عمليات قراءة السجلّ android.permission.health.READ_HEALTH_DATA_HISTORY

نوع فئة السجلّ بيان أذونات القراءة والكتابة
ActiveCaloriesBurned android.permission.health.READ_ACTIVE_CALORIES_BURNED
android.permission.health.WRITE_ACTIVE_CALORIES_BURNED
BasalMetabolicRate android.permission.health.READ_BASAL_METABOLIC_RATE
android.permission.health.WRITE_BASAL_METABOLIC_RATE
BloodPressure android.permission.health.READ_BLOOD_PRESSURE
android.permission.health.WRITE_BLOOD_PRESSURE
CyclingPedalingCadence android.permission.health.READ_CYCLING_PEDALING_CADENCE
android.permission.health.WRITE_CYCLING_PEDALING_CADENCE
المسافة android.permission.health.READ_DISTANCE
android.permission.health.WRITE_DISTANCE
ElevationGained android.permission.health.READ_ELEVATION_GAINED
android.permission.health.WRITE_ELEVATION_GAINED
ExerciseSession android.permission.health.READ_EXERCISE_ROUTE
android.permission.health.READ_EXERCISE_SESSION
android.permission.health.WRITE_EXERCISE_ROUTE
android.permission.health.WRITE_EXERCISE_SESSION
FloorsClimbed android.permission.health.READ_FLOORS_CLIMBED
android.permission.health.WRITE_FLOORS_CLIMBED
HeartRate android.permission.health.READ_HEART_RATE
android.permission.health.WRITE_HEART_RATE
الارتفاع android.permission.health.READ_HEIGHT
android.permission.health.WRITE_HEIGHT
الترطيب android.permission.health.READ_HYDRATION
android.permission.health.WRITE_HYDRATION
MindfulnessSession android.permission.health.READ_MINDFULNESS
android.permission.health.WRITE_MINDFULNESS
التغذية android.permission.health.READ_NUTRITION
android.permission.health.WRITE_NUTRITION
الطاقة android.permission.health.READ_POWER
android.permission.health.WRITE_POWER
معدل ضربات القلب في حالة الراحة android.permission.health.READ_RESTING_HEART_RATE
android.permission.health.WRITE_RESTING_HEART_RATE
SkinTemperature android.permission.health.READ_SKIN_TEMPERATURE
android.permission.health.WRITE_SKIN_TEMPERATURE
SleepSession android.permission.health.READ_SLEEP_SESSION
android.permission.health.WRITE_SLEEP_SESSION
السرعة android.permission.health.READ_SPEED
android.permission.health.WRITE_SPEED
الخطوات android.permission.health.READ_STEPS
android.permission.health.WRITE_STEPS
StepsCadence android.permission.health.READ_STEPS_CADENCE
android.permission.health.WRITE_STEPS_CADENCE
TotalCaloriesBurned android.permission.health.READ_TOTAL_CALORIES_BURNED
android.permission.health.WRITE_TOTAL_CALORIES_BURNED
الوزن android.permission.health.READ_WEIGHT
android.permission.health.WRITE_WEIGHT
WheelchairPushes android.permission.health.READ_WHEELCHAIR_PUSHES
android.permission.health.WRITE_WHEELCHAIR_PUSHES

بالنسبة إلى الإصدار 1.0.0-alpha09 والإصدارات الأقدم

نوع فئة السجلّ بيان أذونات القراءة والكتابة
ActiveCaloriesBurned androidx.health.permission.ActiveCaloriesBurned.READ
androidx.health.permission.ActiveCaloriesBurned.WRITE
BasalMetabolicRate androidx.health.permission.BasalMetabolicRate.READ
androidx.health.permission.BasalMetabolicRate.WRITE
BloodPressure androidx.health.permission.BloodPressure.READ
androidx.health.permission.BloodPressure.WRITE
CyclingPedalingCadence androidx.health.permission.CyclingPedalingCadence.READ
androidx.health.permission.CyclingPedalingCadence.WRITE
المسافة androidx.health.permission.Distance.READ
androidx.health.permission.Distance.WRITE
ElevationGained androidx.health.permission.ElevationGained.READ
androidx.health.permission.ElevationGained.WRITE
ExerciseSession androidx.health.permission.ExerciseSession.READ
androidx.health.permission.ExerciseSession.WRITE
FloorsClimbed androidx.health.permission.FloorsClimbed.READ
androidx.health.permission.FloorsClimbed.WRITE
HeartRate androidx.health.permission.HeartRate.READ
androidx.health.permission.HeartRate.WRITE
الارتفاع androidx.health.permission.Height.READ
androidx.health.permission.Height.WRITE
الترطيب androidx.health.permission.Hydration.READ
androidx.health.permission.Hydration.WRITE
التغذية androidx.health.permission.Nutrition.READ
androidx.health.permission.Nutrition.WRITE
الطاقة androidx.health.permission.Power.READ
androidx.health.permission.Power.WRITE
معدل ضربات القلب في حالة الراحة androidx.health.permission.RestingHeartRate.READ
androidx.health.permission.RestingHeartRate.WRITE
SleepSession androidx.health.permission.SleepSession.READ
androidx.health.permission.SleepSession.WRITE
السرعة androidx.health.permission.Speed.READ
androidx.health.permission.Speed.WRITE
الخطوات androidx.health.permission.Steps.READ
androidx.health.permission.Steps.WRITE
StepsCadence androidx.health.permission.StepsCadence.READ
androidx.health.permission.StepsCadence.WRITE
TotalCaloriesBurned androidx.health.permission.TotalCaloriesBurned.READ
androidx.health.permission.TotalCaloriesBurned.WRITE
الوزن androidx.health.permission.Weight.READ
androidx.health.permission.Weight.WRITE
WheelchairPushes androidx.health.permission.WheelchairPushes.READ
androidx.health.permission.WheelchairPushes.WRITE

مراجعة أنواع البيانات والأذونات

بعد أن خططت لأنواع البيانات والأذونات، يمكنك تنفيذ هذه الأنواع والأذونات أثناء مرحلة التطوير.

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

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