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

يتوافق هذا الدليل مع الإصدار 1.1.0-alpha12 من 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 هي وحدة إطار عمل. وبالتالي، لا يلزم إجراء أي عملية إعداد.

‫Android 13 والإصدارات الأقدم

في الإصدار 13 من نظام التشغيل Android (المستوى 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 مسؤولة عن استخدام واجهة برمجة التطبيقات (API) الخاصة بتطبيق Health Connect لإرسال الطلبات عند تنفيذ العمليات على مستودع البيانات في تطبيق Health Connect.

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

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.2.0-alpha01"
  ...
}

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

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

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

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

يُعد الوصول إلى بيانات الصحة واللياقة البدنية أمرًا حسّاسًا. يوفّر 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. يسمح للتطبيق باستخدام مستودع البيانات في تطبيق 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) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(15))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            ),
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

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

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

suspend fun readHeartRateByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (record in response.records) {
            // Process each 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، بالإضافة إلى إرشادات أفضل الممارسات لتحقيق عملية دمج سلسة:

المراجع

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

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

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

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