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

این راهنما به شما نشان می دهد که چگونه می توانید از 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، به Settings > Apps > Health Connect بروید یا Health Connect را به منوی Quick Settings خود اضافه کنید.

علاوه بر این، Health Connect از کاربر می‌خواهد که قفل صفحه را با یک پین، الگو یا رمز عبور فعال کند تا زمانی که دستگاه قفل است، داده‌های سلامتی که در 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.1.0-alph10"
  ...
}

برای آخرین نسخه به نسخه های 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 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)
  }
}

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

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

منابع

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

مراحل بعدی

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