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

يتوافق هذا الدليل مع الإصدار ‎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" // Or get from HealthConnectClient.DEFAULT_PROVIDER_PACKAGE_NAME
    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(
            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}")
}