بدء استخدام Health Connect

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

يوضّح لك هذا الدليل كيفية البدء في استخدام Health Connect في تطبيقك.

الخطوة 1: إعداد تطبيق Health Connect

يتولّى تطبيق Health Connect مسؤولية معالجة جميع الطلبات التي يرسلها تطبيقك من خلال حزمة تطوير البرامج (SDK) الخاصة بتطبيق Health Connect. تشمل هذه الطلبات تخزين البيانات وإدارة إمكانية الوصول إليها للقراءة والكتابة.

تعتمد إمكانية الوصول إلى Health Connect على إصدار Android المثبَّت على الهاتف. توضّح الأقسام التالية كيفية التعامل مع عدة إصدارات حديثة من Android.

Android 14

اعتبارًا من Android 14 (المستوى 34 من واجهة برمجة التطبيقات)، يشكّل Health Connect جزءًا من إطار عمل Android. هذا الإصدار من Health Connect هو وحدة إطار عمل. وبالتالي، لا يلزم إجراء أي عملية إعداد.

نظام التشغيل Android 13 والإصدارات الأقدم

في نظام التشغيل Android 13 (المستوى 33 لواجهة برمجة التطبيقات) والإصدارات الأقدم، لا يشكّل تطبيق Health Connect جزءًا من إطار عمل Android. بالتالي، عليك تثبيت تطبيق Health Connect من "متجر Google Play".

إذا كنت قد دمجت تطبيقك مع Health Connect على نظام التشغيل Android 13 والإصدارات الأقدم، وأردت نقل البيانات إلى نظام التشغيل Android 14، يُرجى الرجوع إلى مقالة نقل البيانات من الإصدار 13 إلى الإصدار 14 من نظام التشغيل Android.

فتح تطبيق Health Connect

لن يظهر تطبيق Health Connect على الشاشة الرئيسية تلقائيًا بعد الآن. يمكنك فتح Health Connect من خلال الإعدادات، على الرغم من أنّ المسار يختلف حسب إصدار Android:

  • على أجهزة Android 14 والإصدارات الأحدث: انتقِل إلى الإعدادات > الخصوصية والأمان > عناصر التحكّم في الخصوصية > Health Connect ، أو ابحث عن Health Connect في "الإعدادات".
  • على أجهزة Android 13 والإصدارات الأقدم: انتقِل إلى الإعدادات > التطبيقات > Health Connect، أو أضِف Health Connect إلى قائمة الإعدادات السريعة.

الخطوة 2: إضافة حزمة تطوير البرامج (SDK) الخاصة بتطبيق Health Connect إلى تطبيقك

تتولّى حزمة تطوير البرامج (SDK) الخاصة بتطبيق Health Connect مسؤولية استخدام واجهة برمجة التطبيقات Health Connect API لإرسال الطلبات عند تنفيذ عمليات على مستودع البيانات في تطبيق Health Connect.

أضِف مصدر الاعتمادية الخاص بحزمة تطوير البرامج (SDK) الخاصة بتطبيق Health Connect في ملف build.gradle على مستوى الوحدة:

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.2.0-alpha04"
  ...
}

راجِع ملاحظات إصدارات Health Connect للحصول على أحدث إصدار.

استخدام ميزات قناة الإصدار Canary

لاستخدام الميزات في قناة الإصدار Canary ، عدِّل إصدار compileSdk في ملف build.gradle على مستوى الوحدة:

android {
  compileSdkPreview = "CANARY"
}

الخطوة 3: إعداد تطبيقك

توضّح الأقسام التالية كيفية إعداد تطبيقك للدمج مع Health Connect.

التحقّق من توفُّر الميزات

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

الدالة الرئيسية للتحقّق من توفُّر الميزات هي getFeatureStatus(). تعرض هذه الدالة الثوابت العددية FEATURE_STATUS_AVAILABLE أو FEATURE_STATUS_UNAVAILABLE:

fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}

تضمين الأذونات في نماذج البيان

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

في تطبيقك، يجب الإفصاح عن أذونات القراءة والكتابة في الملف AndroidManifest.xml استنادًا إلى أنواع البيانات المطلوبة، والتي يجب أن تتطابق مع تلك التي أفصحت عن إمكانية الوصول إليها في Play Console.

يستخدم تطبيق Health Connect تنسيق بيان أذونات Android العادي. يمكنك منح الأذونات باستخدام العلامات <uses-permission>. يجب دمجها ضمن علامات <manifest>.

<manifest>
  <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.WRITE_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.READ_STEPS"/>
  <uses-permission android:name="android.permission.health.WRITE_STEPS"/>

  <application>
  ...
  </application>
</manifest>

للاطّلاع على القائمة الكاملة بالأذونات وأنواع البيانات المقابلة لها، يُرجى الرجوع إلى قائمة أنواع البيانات.

عرض مربّع حوار سياسة الخصوصية في تطبيقك

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

أعلِن عن هذا النشاط لمعالجة الغرض من ACTION_SHOW_PERMISSIONS_RATIONALE الذي يتم إرساله إلى التطبيق عندما ينقر المستخدم على رابط سياسة الخصوصية في شاشة أذونات Health Connect.

...
<application>
  ...
  <!-- For supported versions through Android 13, create an activity to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity
      android:name=".PermissionsRationaleActivity"
      android:exported="true">
    <intent-filter>
      <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
  </activity>

  <!-- For versions starting Android 14, create an activity alias to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity-alias
      android:name="ViewPermissionUsageActivity"
      android:exported="true"
      android:targetActivity=".PermissionsRationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
      <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
      <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
  </activity-alias>
  ...
</application>
...

الحصول على عميل لتطبيق Health Connect

‫HealthConnectClient هي نقطة دخول إلى واجهة برمجة التطبيقات Health Connect API. يسمح للتطبيق باستخدام مستودع البيانات في تطبيق Health Connect، ويدير تلقائيًا عملية الربط بطبقة التخزين الأساسية ويتعامل مع جميع عمليات الاتصال بين العمليات (IPC) وتسلسل الطلبات الصادرة والردود الواردة.

للحصول على مثيل عميل، أعلِن أولاً عن اسم حزمة Health Connect في بيان Android.

<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

بعد ذلك، في نشاطك، تحقَّق مما إذا كان Health Connect مثبَّتًا باستخدام getSdkStatus. إذا كان مثبَّتًا، احصل على مثيل HealthConnectClient.

val availabilityStatus = HealthConnectClient.getSdkStatus(context)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
    Box(modifier = modifier.padding(16.dp), contentAlignment = Alignment.Center) {
        Text(
            text = "Health Connect is not available on this device. Please ensure it is installed and updated.",
            style = MaterialTheme.typography.bodyLarge,
            textAlign = TextAlign.Center
        )
    }
    return
}

val healthConnectClient = remember {
    if (availabilityStatus == HealthConnectClient.SDK_AVAILABLE) {
        HealthConnectClient.getOrCreate(context)
    } else {
        null
    }
}

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

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

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

إعداد المستخدمين

تتضمّن العديد من التطبيقات عملية إعداد مخصّصة، مثل توضيح الميزات أو طلب موافقة المستخدم. للسماح لتطبيق Health Connect بتشغيل عملية الإعداد، أضِف ما يلي إلى بيانك:

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

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

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

الخطوة 5: تنفيذ العمليات

بعد إعداد كل شيء، نفِّذ عمليات القراءة والكتابة في تطبيقك.

قد يستخدم المستخدمون تطبيقات أخرى تُزامِن البيانات مع Health Connect ليتمكّن تطبيقك من الوصول إليها. إذا لم يسبق للمستخدم إعداد هذه التطبيقات للكتابة في Health Connect بعد، يمكنك استخدام Matchmaking API لربط هذه التطبيقات بسلاسة للمستخدمين.

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

نظِّم بياناتك في سجلّ. اطّلِع على قائمة أنواع البيانات المتاحة في 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))

بعد ذلك، اكتب سجلّك باستخدام 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))

قراءة البيانات

يمكنك قراءة بياناتك بشكل فردي باستخدام readRecords.

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        HeartRateRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}

يمكنك أيضًا قراءة بياناتك بطريقة مجمّعة باستخدام aggregate.

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}

فيديوهات تعليمية

شاهِد هذه الفيديوهات التي توضّح المزيد عن ميزات Health Connect، بالإضافة إلى إرشادات أفضل الممارسات لتحقيق عملية دمج سلسة:

الموارد

اطّلِع على الموارد التالية التي تساعد في عملية التطوير لاحقًا.

  • حزمة تطوير البرامج (SDK) لتطبيق Health Connect (متوفّرة على Jetpack): أدرِج هذه الحزمة في تطبيقك لاستخدام واجهة برمجة التطبيقات Health Connect API.
  • مرجع واجهة برمجة التطبيقات: يمكنك الاطّلاع على مرجع Jetpack الخاص بواجهة برمجة التطبيقات Health Connect API.
  • الإعلان عن استخدام أنواع البيانات: في Play Console، أعلِن عن إمكانية الوصول إلى أنواع بيانات Health Connect التي يقرأها تطبيقك ويكتبها.
  • عيّنة التعليمات البرمجية والدرس التطبيقي حول الترميز الاختياريان على GitHub: يمكنك الاطّلاع على مستودع عيّنة التعليمات البرمجية والدرس التطبيقي حول الترميز على GitHub لمساعدتك في البدء.

الخطوات التالية

اطّلِع على العمليات الشائعة لمعرفة كيفية تنفيذها في Health Connect، مثل: