تتبُّع جلسات اليقظة والوعي التام

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

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

التحقّق من توفّر Health Connect

قبل محاولة استخدام Health Connect، يجب أن يتأكّد تطبيقك من توفُّر Health Connect على جهاز المستخدم. قد لا يكون تطبيق Health Connect مثبَّتًا مسبقًا على جميع الأجهزة أو قد يكون غير مفعَّل. يمكنك التحقّق من توفّره باستخدام طريقة HealthConnectClient.getSdkStatus().

كيفية التحقّق من توفّر Health Connect

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata"
    val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)

    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
      // Health Connect is not available. Guide the user to install/enable it.
      // For example, show a dialog.
      return // early return as there is no viable integration
    }
    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
      // Health Connect is available but requires an update.
      // Optionally redirect to package installer to find a provider, for example:
      val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
      context.startActivity(
        Intent(Intent.ACTION_VIEW).apply {
          setPackage("com.android.vending")
          data = Uri.parse(uriString)
          putExtra("overlay", true)
          putExtra("callerId", context.packageName)
        }
      )
      return
    }
    // Health Connect is available, obtain a HealthConnectClient instance
    val healthConnectClient = HealthConnectClient.getOrCreate(context)
    // Issue operations with healthConnectClient
}

بناءً على الحالة التي يعرضها getSdkStatus()، يمكنك توجيه المستخدم لتثبيت Health Connect أو تحديثه من "متجر Google Play" إذا لزم الأمر.

مدى توفّر الميزة

لتحديد ما إذا كان جهاز المستخدم يتيح سجلّات جلسات التأمّل في Health Connect، تحقَّق من توفُّر FEATURE_MINDFULNESS_SESSION على جهاز المستخدم:

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_MINDFULNESS_SESSION
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
} else {
  // Feature isn't available
}
يُرجى الاطّلاع على التحقّق من توفّر الميزة لمزيد من المعلومات.

الأذونات المطلوبة

تتم حماية الوصول إلى بيانات التأمّل من خلال الأذونات التالية:

  • android.permission.health.READ_MINDFULNESS
  • android.permission.health.WRITE_MINDFULNESS

لإضافة ميزة اليقظة الذهنية إلى تطبيقك، ابدأ بطلب أذونات لنوع البيانات MindfulnessSession.

في ما يلي الإذن الذي يجب الإفصاح عنه لتتمكّن من كتابة بيانات اليقظة الذهنية:

<application>
  <uses-permission
android:name="android.permission.health.WRITE_MINDFULNESS" />
...
</application>

لقراءة بيانات التأمّل، عليك طلب الأذونات التالية:

<application>
  <uses-permission
android:name="android.permission.health.READ_MINDFULNESS" />
...
</application>

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

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

val permissions =
    setOf(
        HealthPermission.getReadPermission(MindfulnessSessionRecord::class),
        HealthPermission.getWritePermission(MindfulnessSessionRecord::class)
    )
 استخدِم getGrantedPermissions لمعرفة ما إذا كان تطبيقك قد حصل على الأذونات المطلوبة. وإذا لم يكن الأمر كذلك، استخدِم createRequestPermissionResultContract لطلب هذه الأذونات. سيؤدي ذلك إلى عرض شاشة أذونات Health Connect. 
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.") }
    }
}
 بما أنّ المستخدمين يمكنهم منح الأذونات أو إبطالها في أي وقت، يحتاج تطبيقك إلى التحقّق من الأذونات في كل مرة قبل استخدامها والتعامل مع السيناريوهات التي يتم فيها فقدان الإذن.

المعلومات المضمّنة في سجلّ جلسة اليقظة الذهنية

يسجّل كل سجلّ لجلسة اليقظة والوعي التام أي نوع من جلسات اليقظة والوعي التام التي يؤديها المستخدم، مثل التأمل والتنفس والحركة. يمكن أن يتضمن السجل أيضًا ملاحظات إضافية حول الجلسة.

تتوفّر أنواع جلسات التأمّل التالية في "MindfulnessSessionRecord":

  • MINDFULNESS_SESSION_TYPE_UNKNOWN
  • MINDFULNESS_SESSION_TYPE_MEDITATION
  • MINDFULNESS_SESSION_TYPE_BREATHING
  • MINDFULNESS_SESSION_TYPE_MUSIC
  • MINDFULNESS_SESSION_TYPE_MOVEMENT
  • MINDFULNESS_SESSION_TYPE_UNGUIDED

للاطّلاع على قائمة كاملة بأنواع جلسات التأمّل، يُرجى مراجعة المستندات المرجعية لـ MindfulnessSessionRecord.

عمليات التجميع المتوافقة

تتوفّر القيم المجمّعة التالية لـ MindfulnessSessionRecord:

كتابة بيانات جلسة اليقظة والوعي التام

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

val isAvailable = healthConnectClient.features.getFeatureStatus(FEATURE_MINDFULNESS_SESSION)

if (isAvailable == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

    val record = MindfulnessSessionRecord(
        startTime = Instant.now().minus(Duration.ofHours(1)),
        startZoneOffset = ZoneOffset.UTC,
        endTime = Instant.now(),
        endZoneOffset = ZoneOffset.UTC,
        mindfulnessSessionType = MindfulnessSessionRecord.MINDFULNESS_SESSION_TYPE_MEDITATION,
        title = "Lake meditation",
        notes = "Meditation by the lake",
        metadata = Metadata.activelyRecorded(
            clientRecordId = "myid",
            clientRecordVersion = 1L,
            device = Device(type = Device.TYPE_PHONE)
        )
    )

قراءة بيانات جلسة اليقظة والوعي التام

يوضّح مقتطف الرمز التالي كيفية قراءة جلسة تأمّل ضمن نطاق زمني:

Val now = Instant.now()

val records = healthConnectClient.readRecords(
    ReadRecordsRequest(
        recordType = MindfulnessSessionRecord::class,
        timeRangeFilter = TimeRangeFilter.between(
            startTime = now.minus(Duration.ofHours(5)),
            endTime = now
        )
    )
)

// Process the returned records
records.records.forEach { session ->
    println("Mindfulness session:")
    println("Start: ${session.startTime}")
    println("End: ${session.endTime}")
    println("Title: ${session.title}")
    println("Notes: ${session.notes}")
    println("Type: ${session.mindfulnessSessionType}")
}