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

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

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

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

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

Android 14

اعتبارًا من الإصدار 14 من نظام التشغيل Android (المستوى 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 من 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 للحصول على أحدث إصدار.

ملاحظة: تتوافق حزمة تطوير البرامج (SDK) لتطبيق Health Connect مع الإصدار 8 من نظام التشغيل Android (المستوى 26 من واجهة برمجة التطبيقات) أو إصدار أحدث، في حين لا يتوافق تطبيق Health Connect إلا مع الإصدار 9 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات) أو إصدار أحدث. وهذا يعني أنّه يمكن للتطبيقات التابعة لجهات خارجية دعم مستخدمي الإصدار Android 8، ولكن يمكن فقط للمستخدمين الذين يستخدمون الإصدار 9 من نظام التشغيل Android أو الإصدارات الأحدث استخدام 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، كما يدير تلقائيًا ربطه بطبقة التخزين الأساسية ويعالج كل عمليات تبادل البيانات بين العمليات وتسلسل الطلبات الصادرة والردود الواردة.

للحصول على مثيل عميل، يُرجى تحديد اسم حزمة 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 قراءة البيانات لمدة تصل إلى 30 يومًا قبل حلول الوقت. منح الإذن لأول مرة. ومع ذلك، إذا حذف أحد المستخدمين تطبيقك، سيتم فقدان سجل الأذونات. إذا أعاد المستخدم تثبيت تطبيقك ومنحه مرة أخرى، يمكن لتطبيق Health Connect قراءة البيانات قبل 30 يومًا من تاريخ أو تاريخ الحصول على هذه الشارة

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

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

• إدارة الأذونات في Health Connect
• القراءة والكتابة في Health Connect
• نصائح لدمج Health Connect بنجاح

المراجع

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

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

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

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

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

• كتابة البيانات
• قراءة البيانات الأولية
• قراءة البيانات المجمّعة