مراحل را دنبال کنید

Health Connect یک نوع داده گام برای ثبت تعداد گام‌ها با استفاده از StepsRecord ارائه می‌دهد. گام‌ها یک معیار اساسی در ردیابی سلامت و تناسب اندام هستند.

مراحل موبایل را بخوانید

با اندروید ۱۴ (سطح API ۳۴) و افزونه SDK نسخه ۲۰ یا بالاتر، Health Connect امکان شمارش گام‌ها را روی دستگاه فراهم می‌کند. اگر به هر برنامه‌ای مجوز READ_STEPS اعطا شده باشد، Health Connect شروع به ثبت گام‌ها از دستگاه مبتنی بر اندروید می‌کند و کاربران می‌توانند داده‌های گام‌ها را که به طور خودکار به ورودی‌های Health Connect Steps اضافه می‌شوند، مشاهده کنند.

برای بررسی اینکه آیا شمارش گام روی دستگاه در دسترس است، باید تأیید کنید که دستگاه از اندروید ۱۴ (سطح API ۳۴) استفاده می‌کند و حداقل نسخه ۲۰ افزونه SDK را دارد. می‌توانید از کد زیر استفاده کنید:

val isStepTrackingAvailable =
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
        SdkExtensions.getExtensionVersion(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) >= 20

تعداد گام‌های ثبت‌شده توسط اپلیکیشن Health Connect در DataOrigin روی نام بسته‌ی android تنظیم شده است. اگر برنامه‌ی شما صرفاً تعداد گام‌های جمع‌آوری‌شده را با استفاده aggregate می‌خواند و با DataOrigin فیلتر نمی‌کند، گام‌های ثبت‌شده روی دستگاه به‌طور خودکار در مجموع گنجانده می‌شوند.

اگر برنامه شما نیاز به خواندن مراحل روی دستگاه دارد، یا اگر داده‌های مرحله‌ای را بر اساس برنامه یا دستگاه مبدا نمایش می‌دهد، می‌توانید رکوردهایی را که DataOrigin مربوط به android است، جستجو کنید. اگر برنامه شما برای داده‌های مرحله‌ای، نسبتی نشان می‌دهد، باید داده‌ها را از بسته اندروید به دستگاه فعلی نسبت دهید. می‌توانید این کار را با استفاده از برچسبی مانند "Your phone" یا بازیابی نام دستگاه با استفاده از Settings.Global.getString(resolver, Settings.Global.DEVICE_NAME) یا بررسی فیلد Device در فراداده رکورد انجام دهید.

مثال زیر نحوه خواندن داده‌های جمع‌آوری‌شده از تعداد گام‌های موبایل را با فیلتر کردن مبدا داده‌های android نشان می‌دهد:

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                dataOriginFilter = setOf(DataOrigin("android"))
            )
        )
        // 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 از حسگر TYPE_STEP_COUNTER از SensorManager استفاده می‌کند. این حسگر برای مصرف کم انرژی بهینه شده است و آن را برای ردیابی مداوم گام‌ها در پس‌زمینه ایده‌آل می‌کند.
• جزئیات داده‌ها : برای صرفه‌جویی در مصرف باتری، داده‌های مرحله معمولاً دسته‌بندی شده و حداکثر یک بار در دقیقه در پایگاه داده Health Connect نوشته می‌شوند.
• انتساب : همانطور که قبلاً ذکر شد، تمام مراحل ثبت شده توسط این ویژگی روی دستگاه به نام بسته android در DataOrigin نسبت داده می‌شوند.
• فعال‌سازی : مکانیزم شمارش گام روی دستگاه تنها زمانی فعال است که حداقل به یک برنامه روی دستگاه، مجوز READ_STEPS در Health Connect اعطا شده باشد.

بررسی در دسترس بودن Health Connect

قبل از تلاش برای استفاده از Health Connect، برنامه شما باید تأیید کند که Health Connect در دستگاه کاربر موجود است. Health Connect ممکن است از قبل روی همه دستگاه‌ها نصب نشده باشد یا غیرفعال باشد. می‌توانید با استفاده از متد HealthConnectClient.getSdkStatus() در دسترس بودن آن را بررسی کنید.

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata" // Or get from HealthConnectClient.DEFAULT_PROVIDER_PACKAGE_NAME
    val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)

    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
      // Health Connect is not available. Guide the user to install/enable it.
      // For example, show a dialog.
      return // early return as there is no viable integration
    }
    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
      // Health Connect is available but requires an update.
      // 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
    }
    // Health Connect is available, obtain a HealthConnectClient instance
    val healthConnectClient = HealthConnectClient.getOrCreate(context)
    // Issue operations with healthConnectClient
}

بسته به وضعیت برگردانده شده توسط getSdkStatus() ، می‌توانید در صورت لزوم کاربر را برای نصب یا به‌روزرسانی Health Connect از فروشگاه Google Play راهنمایی کنید.

مجوزهای مورد نیاز

دسترسی به مراحل توسط مجوزهای زیر محافظت می‌شود:

• android.permission.health.READ_STEPS
• android.permission.health.WRITE_STEPS

برای افزودن قابلیت steps به برنامه خود، با درخواست مجوزهای نوشتن برای نوع داده Steps شروع کنید.

برای نوشتن مراحل، باید مجوز زیر را اعلام کنید:

<application>
  <uses-permission
android:name="android.permission.health.WRITE_STEPS" />
...
</application>

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

<application>
  <uses-permission
android:name="android.permission.health.READ_STEPS" />
...
</application>

درخواست مجوز از کاربر

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

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

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  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)
  }
}

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

اطلاعات موجود در رکورد مراحل

هر StepsRecord شامل اطلاعات زیر است:

• count : تعداد گام‌های برداشته شده در بازه زمانی، به صورت Long .
• startTime : زمان شروع بازه اندازه‌گیری.
• endTime : زمان پایان بازه اندازه‌گیری.
• startZoneOffset : انحراف منطقه برای زمان شروع.
• endZoneOffset : انحراف منطقه برای زمان پایان.

تجمیع‌های پشتیبانی‌شده

مقادیر تجمعی زیر برای StepsRecord در دسترس هستند:

• COUNT_TOTAL

مقادیر تجمعی زیر برای StepsCadenceRecord در دسترس هستند:

• RATE_AVG
• RATE_MAX
• RATE_MIN

مثال استفاده

بخش‌های زیر نحوه خواندن و نوشتن داده‌های StepsRecord را نشان می‌دهند.

نوشتن داده‌های مراحل

برنامه شما می‌تواند با وارد کردن نمونه‌های StepsRecord داده‌های شمارش گام را بنویسد. مثال زیر نحوه ثبت ۱۰۰۰ گام برداشته شده توسط یک کاربر را نشان می‌دهد:

suspend fun writeStepsData(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant,
    startZoneOffset: ZoneOffset,
    endZoneOffset: ZoneOffset
) {
    try {
        val stepsRecord = StepsRecord(
            startTime = startTime,
            startZoneOffset = startZoneOffset,
            endTime = endTime,
            endZoneOffset = endZoneOffset,
            count = 1000
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling
    }
}

خواندن داده‌های تجمیعی

رایج‌ترین روش برای خواندن داده‌های گام، جمع‌آوری کل گام‌ها در یک بازه زمانی است. مثال زیر نحوه خواندن تعداد کل گام‌ها برای یک کاربر در یک بازه زمانی خاص را نشان می‌دهد:

suspend fun readStepsAggregate(
    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
    }
}

خواندن داده‌های خام

مثال زیر نحوه خواندن داده‌های خام StepsRecord بین زمان شروع و پایان را نشان می‌دهد:

suspend fun readStepsRaw(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = StepsRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (record in response.records) {
            // Process each record
        }
    } catch (e: Exception) {
        // Run error handling here
    }
}