با Health Connect شروع کنید

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

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

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

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

دسترسی به Health Connect بستگی به نسخه اندروید نصب شده روی گوشی دارد. در بخش‌های زیر نحوه کار با چندین نسخه اخیر اندروید توضیح داده شده است.

اندروید 14

با شروع Android 14 (API Level 34)، Health Connect بخشی از چارچوب Android است. این نسخه از Health Connect یک ماژول چارچوب است. با آن، هیچ راه اندازی لازم وجود دارد.

اندروید 13 و پایین تر

در Android 13 (API Level 33) و نسخه‌های پایین‌تر، Health Connect بخشی از چارچوب Android نیست. با این کار، باید برنامه Health Connect را از فروشگاه Google Play نصب کنید.

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

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

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

  • در اندروید 14 و بالاتر: به تنظیمات > امنیت و حریم خصوصی > کنترل‌های حریم خصوصی > اتصال سلامت بروید یا Health Connect را در تنظیمات جستجو کنید.
  • در Android 13 و پایین‌تر: به تنظیمات > برنامه‌ها > اتصال سلامت بروید یا Health Connect را به منوی تنظیمات سریع خود اضافه کنید.

مرحله 2: Health Connect SDK را به برنامه خود اضافه کنید

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

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

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

برای آخرین نسخه به نسخه های Health Connect مراجعه کنید.

مرحله 3: برنامه خود را پیکربندی کنید

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

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

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

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

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
  ...
} else {
  // Feature is not available
  ...
}

مجوزها را اعلام کنید

دسترسی به داده های سلامت و تناسب اندام حساس است. 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 استفاده کند. به طور خودکار اتصال خود را به لایه ذخیره سازی زیرین مدیریت می کند و تمام IPC و سریال سازی درخواست های خروجی و پاسخ های دریافتی را مدیریت می کند.

برای دریافت نمونه مشتری، ابتدا نام بسته Health Connect را در مانیفست اندروید خود اعلام کنید.

<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

سپس در Activity خود، بررسی کنید که آیا 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: درخواست مجوز از کاربر

پس از ایجاد یک نمونه مشتری، برنامه شما باید از کاربر مجوز درخواست کند. کاربران باید در هر زمانی اجازه دهند یا رد کنند.

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

// 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)
  }
}

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

کاربران داخلی

بسیاری از برنامه‌ها دارای یک جریان سفارشی ورود مانند آموزش ویژگی یا درخواست رضایت کاربر هستند. برای فعال کردن 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 و نه از داخل برنامه شما آغاز کنند. اگر برنامه شما به هر گونه تعامل اضافی غیر از دریافت مجوز خواندن یا نوشتن داده ها نیاز دارد، یک فعالیت ورود ارائه کنید.

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

مرحله 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 و همچنین بهترین دستورالعمل‌ها برای دستیابی به یکپارچگی روان توضیح می‌دهند:

منابع

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

مراحل بعدی

برای یادگیری نحوه انجام عملیات در Health Connect مانند: