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

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

الخطوة 1: تحضير تطبيق Health Connect

يتحمّل تطبيق Health Connect مسؤولية معالجة جميع الطلبات التي يرسلها تطبيقك من خلال حزمة تطوير البرامج 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 والإصدارات الأقدم، وكنت تريد نقل البيانات على الإصدار 14 من نظام Android، يُرجى الرجوع إلى نقل البيانات من الإصدار 13 إلى الإصدار 14 من نظام التشغيل Android.

فتح تطبيق Health Connect

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

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

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

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

أضِف حزمة تطوير البرامج (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 استنادًا إلى أنواع البيانات المطلوبة. احرص على استخدام مجموعة الأذونات التي طلبت الوصول إليها بعد إكمال النموذج.

يستخدم تطبيق 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, 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)
  }
}

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

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

الآن وبعد أن أصبح كل شيء على ما يرام، يمكنك تنفيذ عمليات القراءة والكتابة في التطبيق الخاص بك.

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

قم بهيكلة بياناتك في سجل. اطّلِع على قائمة أنواع البيانات المتاحة في 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، بالإضافة إلى إرشادات أفضل الممارسات لتحقيق عملية دمج سلسة:

المَراجع

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

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

اطلع على سير العمل الشائع لمعرفة كيفية إجراء العمليات في Health Connect مثل: