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

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

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

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

يعتمد الوصول إلى 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 Connect، انتقِل إلى الإعدادات > التطبيقات > Health Connect أو أضِف Health Connect إلى قائمة الإعدادات السريعة.

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

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

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

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

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

يمكنك الرجوع إلى إصدارات Health Connect للاطّلاع على أحدث إصدار.

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

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

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

الإفصاح عن الأذونات

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

في Play Console، أدخِل بيانًا للوصول إلى أنواع بيانات 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، كما يدير تلقائيًا ربطه بطبقة التخزين الأساسية ويعالج كل عمليات تبادل البيانات بين العمليات وتسلسل الطلبات الصادرة والردود الواردة.

للحصول على مثيل عميل، عليك أولاً الإفصاح عن اسم حزمة 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 لمساعدتك في البدء.

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

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

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

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