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

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

مرحله ۱: اپلیکیشن Health Connect را آماده کنید

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

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

اندروید ۱۴

از اندروید ۱۴ (API Level 34)، Health Connect بخشی از چارچوب اندروید است. این نسخه از Health Connect یک ماژول چارچوب است. با این اوصاف، هیچ تنظیماتی لازم نیست.

اندروید ۱۳ و پایین‌تر

در اندروید ۱۳ (سطح API ۳۳) و نسخه‌های پایین‌تر، Health Connect بخشی از چارچوب اندروید نیست. برای این کار، باید برنامه Health Connect را از فروشگاه گوگل پلی نصب کنید.

اگر برنامه خود را با Health Connect در اندروید ۱۳ و پایین‌تر ادغام کرده‌اید و می‌خواهید به اندروید ۱۴ مهاجرت کنید، به «مهاجرت از اندروید ۱۳ به ۱۴» مراجعه کنید.

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

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

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

مرحله ۲: کیت توسعه نرم‌افزار Health Connect را به برنامه خود اضافه کنید

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

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

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

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

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

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

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

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

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

نمایش پنجره‌ی سیاست حفظ حریم خصوصی برنامه

مانیفست اندروید شما باید یک Activity داشته باشد که سیاست حفظ حریم خصوصی برنامه شما را نمایش دهد، که دلیل برنامه شما برای مجوزهای درخواستی است و نحوه استفاده و مدیریت داده‌های کاربر را شرح می‌دهد.

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

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

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

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

سپس در Activity خود، با استفاده از getSdkStatus بررسی کنید که آیا Health Connect نصب شده است یا خیر. در صورت نصب بودن، یک نمونه 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

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

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

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

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

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

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

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

نوشتن داده

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