ستظل واجهات Google Fit API متاحةً حتى نهاية عام 2026. للتعرّف على مسارات نقل البيانات المقترَحة، يُرجى الاطّلاع على دليل نقل البيانات.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

بدء استخدام 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-alpha06"
  ...
}

يُرجى الرجوع إلى إصدارات Health Connect للحصول على أحدث إصدار.

يتطلّب الإصدار 1.1.0 والإصدارات الأحدث من connect-client استخدام compileSdk = 36 والإصدار 8.9.1 أو إصدار أحدث من المكوّن الإضافي لنظام Gradle المتوافق مع Android ‏ (AGP). عدِّل compileSdk في ملف build.gradle على مستوى الوحدة:

android {
  compileSdk = 36
}

استخدام ميزات قناة إصدار 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
        )
    }
}HealthConnectWorker.kt

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

يُعدّ الوصول إلى بيانات الصحة واللياقة البدنية أمرًا حساسًا. يوفّر تطبيق 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
    }
}HealthConnectActivity.kt

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

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

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

استخدِم 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.") }
    }
}HealthConnectActivity.kt

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

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

تتضمّن العديد من التطبيقات مسارًا مخصّصًا للإعداد، مثل تقديم معلومات عن الميزات أو طلب موافقة المستخدم. لتفعيل 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))HealthConnectManager.kt

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

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

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

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

يمكنك أيضًا قراءة بياناتك بشكل مجمّع باستخدام 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
}HealthConnectManager.kt

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

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

الموارد

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

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

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

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