رابط‌های برنامه‌نویسی کاربردی گوگل فیت تا پایان سال ۲۰۲۶ پشتیبانی خواهند شد. برای آشنایی با مسیرهای مهاجرت پیشنهادی، به راهنمای مهاجرت مراجعه کنید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

شروع کار با Health Connect

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

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

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

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

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

Android 14

از Android 14 (سطح API 34) به بعد، 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 14 و نسخه‌های بالاتر: به تنظیمات > امنیت و حریم خصوصی > تنظیمات حریم خصوصی > Health Connect بروید، یا Health Connect را در «تنظیمات» جستجو کنید.
در Android 13 و نسخه‌های پایین‌تر: به تنظیمات > برنامه‌ها > Health Connect بروید، یا Health Connect را به منو تنظیمات فوری اضافه کنید.

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

«کیت توسعه نرم‌افزار Health Connect» مسئول استفاده از «میانای برنامه‌سازی کاربردی Health Connect» برای ارسال درخواست در انجام عملیات علیه مخزن داده در برنامه Health Connect است.

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

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

برای دریافت جدیدترین نسخه، به نسخه‌های پخش Health Connect مراجعه کنید.

استفاده از ویژگی‌های کانال انتشار 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
        )
    }
}HealthConnectWorker.kt

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

دسترسی به داده‌های سلامتی و تناسب اندام حساس است. ‫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» است. این اجازه به برنامه می‌دهد از مخزن داده در برنامه 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
    }
}HealthConnectActivity.kt

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

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

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )HealthConnectManager.kt

از 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.") }
    }
}HealthConnectActivity.kt

ازآنجایی‌که کاربران می‌توانند در هر زمانی اجازه‌ها را اعطا یا لغو کنند، برنامه شما باید هر بار قبل‌از استفاده از اجازه‌ها، آن‌ها را بررسی کند و سناریوهایی را که اجازه ازدست می‌رود مدیریت کند.

کاربران آماده کار کردن

بسیاری از برنامه‌ها جریان آماده‌سازی سفارشی دارند، مثلاً آموزش ویژگی یا درخواست موافقت کاربر. برای اینکه 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 راه‌اندازی نکرده است، می‌توانید از میانای برنامه‌سازی کاربردی «جفت‌سازی» برای متصل کردن یکپارچه این برنامه‌ها برای کاربران استفاده کنید.

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

داده‌هایتان را در یک گزارش ساختاربندی کنید. فهرست انواع داده موجود در 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))HealthConnectManager.kt

سپس بااستفاده از 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))HealthConnectManager.kt

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

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

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

همچنین می‌توانید داده‌هایتان را به‌صورت تجمیعی بااستفاده از 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
}HealthConnectManager.kt

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

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

منابع

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

کیت توسعه نرم‌افزار Health Connect (در Jetpack دردسترس است): برای استفاده از «میانای برنامه‌سازی کاربردی Health Connect»، این کیت توسعه نرم‌افزار را در برنامه‌تان بگنجانید.
مرجع میانای برنامه‌سازی کاربردی: مرجع Jetpack را برای میانای برنامه‌سازی کاربردی Health Connect ببینید.
اعلام استفاده از انواع داده: در «کنسول Play»، دسترسی به انواع داده Health Connect را که برنامه‌تان از آن‌ها می‌خواند و در آن‌ها می‌نویسد اعلام کنید.
نمونه کد و codelab اختیاری GitHub: برای کمک به شروع کار، مخزن نمونه کد GitHub و تمرین codelab را ببینید.

مراحل بعدی

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