بدء استخدام 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 هو وحدة إطار عمل. مع ذلك، بدون الحاجة إلى إعداد.

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

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

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

فتح تطبيق Health Connect

لن يظهر تطبيق Health Connect بعد الآن على الشاشة الرئيسية تلقائيًا. فتح تطبيق Health الاتصال، انتقل إلى الإعدادات > التطبيقات > تطبيق Health Connect أو أضِف تطبيق Health Connect إليه قائمة الإعدادات السريعة.

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

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

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

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

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.1.0-alpha02"
  ...
}

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

الخطوة 3: ضبط تطبيقك

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

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

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

إعلان أذونات القراءة والكتابة في ملف AndroidManifest.xml استنادًا إلى أنواع البيانات المطلوبة. تأكَّد من استخدام مجموعة الأذونات التي تم طلب الحصول على الإذن بالوصول بعد إكمال [form]{:.external}.

يستخدم تطبيق 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. يسمح هذا الخيار للتطبيق باستخدام مخزن البيانات في تطبيق 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, providerPackageName)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
  return // early return as there is no viable integration
}
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
  // 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
}
val healthConnectClient = HealthConnectClient.getOrCreate(context)
// Issue operations with healthConnectClient

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

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

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

// Create a set of permissions for required data types
val PERMISSIONS =
setOf(
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::class)
)

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

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

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

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

الآن بعد أن تم إعداد كل شيء، يمكنك إجراء عمليات القراءة والكتابة في تطبيقك.

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

قم بتنظيم بياناتك في سجل. تحقق من قائمة أنواع البيانات المتوفّرة في Health Connect.

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET,
)

بعد ذلك، اكتب السجلّ باستخدام insertRecords.

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET,
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

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

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

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    StepsRecord::class,
                    timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
                )
            )
        for (stepRecord in response.records) {
            // Process each step record
        }
    } catch (e: Exception) {
        // Run error handling here.
    }
}

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

suspend fun aggregateSteps(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

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

شاهِد هذه الفيديوهات التي توضّح المزيد من المعلومات حول ميزات Health Connect. كإرشادات لأفضل الممارسات لتحقيق التكامل السلس:

المراجع

يمكنك الاطّلاع على المراجع التالية التي تساعدك في استخدام والتطور لاحقًا.

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

اطّلع على سير العمل الشائعة للتعرّف على كيفية تنفيذ العمليات في مثل: