شروع کار با Health Connect

این راهنما با Health Connect نسخه 1.1.0-alpha12 یا بالاتر سازگار است.

این راهنما به شما نشان می‌دهد که چگونه می‌توانید استفاده از Health Connect را در برنامه‌تان شروع کنید.

مرحله ۱: آماده کردن برنامه Health Connect

برنامه Health Connect مسئول رسیدگی به همه درخواست‌هایی است که برنامه شما ازطریق Health Connect SDK ارسال می‌کند. این درخواست‌ها شامل ذخیره کردن داده‌ها و مدیریت دسترسی خواندن و نوشتن آن‌ها است.

دسترسی به Health Connect به نسخه Android نصب‌شده در تلفن بستگی دارد. بخش‌های زیر نحوه مدیریت چندین نسخه اخیر Android را شرح می‌دهند.

Android 14

از Android 14 (سطح میانای برنامه‌سازی کاربردی ۳۴)، Health Connect بخشی از چارچوب Android است. این نسخه Health Connect یک واحد چارچوب است. با این کار، نیازی به راه‌اندازی نیست.

‫Android 13 و نسخه‌های پایین‌تر

در Android 13 (میانای برنامه‌سازی کاربردی سطح ۳۳) و نسخه‌های پایین‌تر، Health Connect بخشی از چارچوب Android نیست. با این کار، باید برنامه Health Connect را از «فروشگاه Google Play» نصب کنید.

اگر برنامه‌تان را با Health Connect در Android 13 و پایین‌تر ادغام کرده‌اید و می‌خواهید به Android 14 انتقال دهید، به انتقال از Android 13 به 14 مراجعه کنید.

باز کردن برنامه Health Connect

Health Connect دیگر به‌طور پیش‌فرض در «صفحه اصلی» نشان داده نمی‌شود. می‌توانید Health Connect را ازطریق تنظیمات باز کنید، هرچند مسیر آن بسته به نسخه Android متفاوت است:

  • در Android نسخه ۱۴ و بالاتر: به تنظیمات > امنیت و حریم خصوصی > کنترل‌های حریم خصوصی > Health Connect بروید، یا Health Connect را در «تنظیمات» جستجو کنید.
  • در Android نسخه ۱۳ و پایین‌تر: به تنظیمات > برنامه‌ها > Health Connect بروید، یا Health Connect را به منو تنظیمات فوری اضافه کنید.

مرحله ۲: افزودن Health Connect SDK به برنامه

کیت توسعه نرم‌افزار Health Connect مسئول استفاده از Health Connect API برای ارسال درخواست‌ها در اجرای عملیات در مقابل پایگاه داده در برنامه Health Connect است.

وابستگی Health Connect SDK را در فایل build.gradle سطح واحدتان اضافه کنید:

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

برای اطلاع از جدیدترین نسخه، به نسخه‌های Health Connect مراجعه کنید.

نسخه 1.1.0 و جدیدتر connect-client به compileSdk = 36 و افزایه Android Gradle (AGP) نسخه 8.9.1 یا بالاتر نیاز دارد. compileSdk را در فایل build.gradle سطح ماژول به‌روز کنید:

android {
  compileSdk = 36
}

استفاده از ویژگی‌های کانال انتشار Canary

برای استفاده از ویژگی‌ها در کانال انتشار Canary، نسخه compileSdk را در فایل build.gradle سطح واحدتان اصلاح کنید:

android {
  compileSdkPreview = "CANARY"
}

مرحله ۳: پیکربندی برنامه

بخش‌های زیر نحوه پیکربندی برنامه را برای ادغام با Health Connect توضیح می‌دهد.

بررسی امکان دسترسی به ویژگی

وقتی ویژگی‌های جدیدی به Health Connect اضافه می‌شود، ممکن است کاربران همیشه نسخه Health Connect خود را به‌روز نکنند. «میانای برنامه‌سازی کاربردی دردسترس بودن ویژگی» روشی برای بررسی این است که آیا ویژگی‌ای در Health Connect در دستگاه کاربر دردسترس است یا نه و تصمیم‌گیری درباره اینکه چه اقدامی باید انجام شود.

تابع اصلی برای بررسی دردسترس بودن ویژگی getFeatureStatus() است. این ثابت‌های عدد صحیح FEATURE_STATUS_AVAILABLE یا FEATURE_STATUS_UNAVAILABLE را برمی‌گرداند:

fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}

اعلام اجازه‌ها

دسترسی به داده‌های سلامتی و تناسب اندام حساس است. Health Connect یک لایه امنیتی برای عملیات خواندن و نوشتن پیاده‌سازی می‌کند تا اعتماد کاربر را حفظ کند.

در برنامه‌تان، اجازه‌های خواندن و نوشتن را در فایل AndroidManifest.xml براساس انواع داده‌های موردنیاز اعلام کنید. این اجازه‌ها باید با اجازه‌هایی که در «کنسول Play» برای دسترسی به آن‌ها اعلام کرده‌اید مطابقت داشته باشد.

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 است. این به برنامه اجازه می‌دهد از datastore در برنامه 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)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
    Box(modifier = modifier.padding(16.dp), contentAlignment = Alignment.Center) {
        Text(
            text = "Health Connect is not available on this device. Please ensure it is installed and updated.",
            style = MaterialTheme.typography.bodyLarge,
            textAlign = TextAlign.Center
        )
    }
    return
}

val healthConnectClient = remember {
    if (availabilityStatus == HealthConnectClient.SDK_AVAILABLE) {
        HealthConnectClient.getOrCreate(context)
    } else {
        null
    }
}

مرحله ۴: درخواست اجازه‌ها از کاربر

پس‌از ایجاد نمونه مشتری، برنامه‌تان باید از کاربر درخواست اجازه کند. کاربران باید بتوانند در هرزمانی اجازه‌ها را اعطا یا رد کنند. برای انجام این کار، مجموعه‌ای از اجازه‌ها را برای انواع داده‌های موردنیاز ایجاد کنید. مطمئن شوید که اجازه‌های موجود در مجموعه ابتدا در مانیفست Android شما اعلام شده باشد. 

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
 از getGrantedPermissions استفاده کنید تا ببینید آیا اجازه‌های لازم قبلاً به برنامه‌تان اعطا شده است یا نه. اگر نه، از createRequestPermissionResultContract برای درخواست آن اجازه‌ها استفاده کنید. با این کار، صفحه اجازه‌های Health Connect نمایش داده می‌شود. 
val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
 ازآنجایی‌که کاربران می‌توانند در هر زمانی اجازه‌ها را اعطا یا لغو کنند، برنامه شما باید قبل‌از استفاده از اجازه‌ها، هر بار آن‌ها را بررسی کند و سناریوهایی را که در آن‌ها اجازه ازدست رفته است مدیریت کند.

آماده‌سازی کاربران

بسیاری از برنامه‌ها جریان آماده‌سازی سفارشی دارند، مثل آموزش ویژگی یا درخواست رضایت کاربر. برای اینکه Health Connect بتواند جریان آماده‌سازی شما را راه‌اندازی کند، موارد زیر را به مانیفست خود اضافه کنید:

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

کاربران ممکن است اتصال به برنامه شما را مستقیماً از برنامه Health Connect شروع کنند، نه از داخل برنامه شما. اگر برنامه شما به هرگونه تعامل اضافی فراتر از اعطای اجازه برای خواندن یا نوشتن داده‌ها نیاز دارد، یک فعالیت آماده‌سازی ارائه دهید.

توجه داشته باشید که فعالیت آماده‌سازی ممکن است بیش‌از یک بار راه‌اندازی شود، برای مثال اگر کاربر بعداً اجازه‌های برنامه‌تان را لغو کند و سپس دوباره آن را متصل کند.

مرحله ۵: انجام عملیات

اکنون که همه‌چیز تنظیم شده است، عملیات خواندن و نوشتن را در برنامه‌تان انجام دهید.

کاربرانتان ممکن است از برنامه‌های دیگری استفاده کنند که داده‌ها را با Health Connect همگام‌سازی می‌کنند تا برنامه شما به آن‌ها دسترسی پیدا کند. اگر کاربر هنوز این برنامه‌ها را برای نوشتن در Health Connect راه‌اندازی نکرده است، می‌توانید از Matchmaking API برای اتصال یکپارچه این برنامه‌ها برای کاربران خود استفاده کنید.

نوشتن داده‌ها

داده‌هایتان را در یک سابقه ساختاربندی کنید. فهرست انواع داده موجود در Health Connect را بررسی کنید.

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

سپس بااستفاده از insertRecords، سابقه خود را بنویسید.

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

خواندن داده‌ها

می‌توانید داده‌هایتان را به‌طور جداگانه بااستفاده از readRecords بخوانید.

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        HeartRateRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}

همچنین می‌توانید داده‌هایتان را به‌صورت انبوهه بااستفاده از aggregate بخوانید.

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}

آموزش‌های ویدیویی

این ویدیوها را تماشا کنید تا درباره ویژگی‌های Health Connect و همچنین دستورالعمل‌های روال‌های مطلوب برای دستیابی به ادغامی روان بیشتر بدانید:

منابع

منابع زیر را که به توسعه در آینده کمک می‌کنند بررسی کنید.

مراحل بعدی

گردش کارهای رایج را بررسی کنید تا با نحوه انجام عملیات در Health Connect آشنا شوید، ازجمله: