تتبُّع الخطوات

يوفّر Health Connect نوع بيانات الخطوات لتسجيل عدد الخطوات باستخدام StepsRecord. الخطوات هي قياس أساسي في تتبُّع الصحة واللياقة البدنية.

قراءة بيانات الخطوات على الأجهزة الجوّالة

مع Android 14 (المستوى 34 من واجهة برمجة التطبيقات) والإصدار 20 أو إصدار أحدث من حزمة تطوير البرامج (SDK) للإضافات، يوفّر Health Connect ميزة عدّ الخطوات على الجهاز فقط. إذا تم منح أي تطبيق الإذن READ_STEPS، يبدأ Health Connect في تسجيل الخطوات من الجهاز الذي يعمل بنظام التشغيل Android، ويظهر للمستخدمين بيانات الخطوات التي تتم إضافتها تلقائيًا إلى إدخالات الخطوات في Health Connect.

للتحقّق مما إذا كانت ميزة عدّ الخطوات على الجهاز فقط متاحة، تأكَّد من أنّ الجهاز يعمل بنظام التشغيل Android 14 (مستوى واجهة برمجة التطبيقات 34) ويتضمّن الإصدار 20 أو إصدارًا أحدث من حزمة تطوير البرامج (SDK) للإضافات على الأقل:

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

إذا كان تطبيقك يقرأ عدد الخطوات المجمّع باستخدام aggregate ولا يفلتر حسب DataOrigin، يتم تلقائيًا تضمين الخطوات على الجهاز فقط في الإجمالي، ولا يلزم إجراء أي تغييرات لتحديث يونيو 2026.

تغيير الإسناد للخطوات على الجهاز فقط

بدءًا من تحديث يونيو 2026، يتم إسناد الخطوات التي يتتبّعها Health Connect بشكلٍ أصلي إلى اسم حزمة اصطناعي (SPN)، مثل com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e.

في السابق، كانت الخطوات المضمّنة تُسنَد إلى اسم الحزمة android. تحتفظ بيانات الخطوات السابقة المسجّلة قبل يونيو 2026 باسم الحزمة android.

تكون أسماء الحزم الاصطناعية خاصة بالجهاز ومحدّدة على أساس كل تطبيق لحماية خصوصية المستخدم:

  • ثابت: يكون اسم الحزمة الاصطناعي للجهاز الحالي ثابتًا لتطبيقك.
  • محدّد على نطاق التطبيق: ترى التطبيقات المختلفة على الجهاز نفسه أسماء حزم اصطناعية مختلفة لبيانات الخطوات على الجهاز فقط.

طلب الخطوات على الجهاز فقط

بما أنّ أسماء الحزم الاصطناعية محدّدة على نطاق الجهاز وخاصة به، يجب عدم تضمين قيم أسماء الحزم الاصطناعية في التعليمات البرمجية. بدلاً من ذلك، استخدِم واجهة برمجة التطبيقات getCurrentDeviceDataSource() لاسترداد اسم الحزمة الاصطناعي للجهاز الحالي.

في حين أنّ عدّ الخطوات على الجهاز فقط يتطلّب الإصدار 20 أو إصدارًا أحدث من حزمة تطوير البرامج (SDK) للإضافات، تتوفّر واجهة برمجة التطبيقات getCurrentDeviceDataSource() على Android 14 (المستوى 34 من واجهة برمجة التطبيقات) مع الإصدار 11 أو إصدار أحدث من حزمة تطوير البرامج (SDK) للإضافات.

لم تتوفّر واجهة برمجة التطبيقات getCurrentDeviceDataSource() بعد في مكتبة Health Connect Jetpack. تستخدِم الأمثلة التالية واجهة برمجة التطبيقات لإطار عمل Android بدلاً من ذلك:

import android.content.Context
import android.health.connect.HealthConnectManager

val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)
val deviceDataSource = healthConnectManager?.getCurrentDeviceDataSource()
val currentDeviceSpn = deviceDataSource?.deviceDataOrigin?.packageName

إذا كان تطبيقك بحاجة إلى قراءة الخطوات على الجهاز فقط، أو إذا كان يعرض بيانات الخطوات مقسّمة حسب التطبيق أو الجهاز المصدر، عليك طلب السجلات التي يكون فيها DataOrigin هو android أو يتطابق مع اسم الحزمة الاصطناعي للجهاز. إذا كان تطبيقك يعرض الإسناد لبيانات الخطوات، استخدِم metadata.device لتحديد الجهاز المصدر للسجلات الفردية. بالنسبة إلى الخطوات على الجهاز فقط التي تم تحديدها من خلال اسم حزمة اصطناعي في البيانات المجمّعة، يمكنك استخدام بيانات الجهاز الوصفية، مثل model أو manufacturer من DeviceDataSource لتحديد المصدر، أو استخدام تصنيف عام مثل "هاتفك" للخطوات على الجهاز فقط.

يوضّح المثال التالي كيفية قراءة بيانات عدد الخطوات المجمّعة على الجهاز فقط من خلال الفلترة حسب كل من android واسم الحزمة الاصطناعي للجهاز الحالي:

import android.content.Context
import android.health.connect.HealthConnectManager
import android.os.Build
import android.os.ext.SdkExtensions
import androidx.health.connect.client.HealthConnectClient
import androidx.health.connect.client.records.StepsRecord
import androidx.health.connect.client.records.metadata.DataOrigin
import androidx.health.connect.client.request.AggregateRequest
import androidx.health.connect.client.time.TimeRangeFilter
import java.time.Instant

suspend fun readDeviceStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    context: Context,
    startTime: Instant,
    endTime: Instant
) {
    // 1. Check if SDK Extension 11+ is available for getCurrentDeviceDataSource()
    val isDataSourceApiAvailable = Build.VERSION.SDK_INT >= Build.VERSION_CODES.U &&
            SdkExtensions.getExtensionVersion(Build.VERSION_CODES.U) >= 11

    try {
        val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)

        // 2. Safely fetch the package name only if API is available and data exists
        val currentDeviceSpn = if (isDataSourceApiAvailable) {
            healthConnectManager?.getCurrentDeviceDataSource()?.deviceDataOrigin?.packageName
        } else {
            null
        }

        val dataOriginFilters = mutableSetOf(DataOrigin("android"))

        // 3. Explicit null-safety check using .let
        currentDeviceSpn?.let {
            dataOriginFilters.add(DataOrigin(it))
        }

        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                dataOriginFilter = dataOriginFilters
            )
        )

        val stepCount = response[StepsRecord.COUNT_TOTAL]

    } catch (e: Exception) {
        // Now this catch block only handles actual runtime exceptions, 
        // rather than Errors from missing methods.
    }
}

عدّ الخطوات على الجهاز

  • استخدام أداة الاستشعار: يستخدِم Health Connect أداة الاستشعار TYPE_STEP_COUNTER من SensorManager. تم تحسين أداة الاستشعار هذه لخفض استهلاك الطاقة، ما يجعلها مثالية لتتبُّع الخطوات المستمر في الخلفية.
  • دقة البيانات: للحفاظ على عمر البطارية، يتم عادةً تجميع بيانات الخطوات وكتابتها في قاعدة بيانات Health Connect مرة واحدة على الأكثر في الدقيقة.
  • الإسناد: يتم إسناد الخطوات التي تسجّلها هذه الميزة قبل يونيو 2026 إلى اسم الحزمة android في DataOrigin. بعد هذا التاريخ، يتم إسنادها إلى اسم حزمة اصطناعي خاص بالجهاز. يُرجى الاطّلاع على تغيير تحديد المصدر للخطوات على الجهاز فقط.
  • التفعيل: لا تكون آلية عدّ الخطوات على الجهاز نشطة إلا عندما يتم منح تطبيق واحد على الأقل على الجهاز الإذن READ_STEPS في Health Connect.

التحقّق من توفُّر Health Connect

قبل محاولة استخدام Health Connect، يجب أن يتأكّد تطبيقك من توفُّر Health Connect على جهاز المستخدم. قد لا يكون تطبيق Health Connect مثبَّتًا مسبقًا على جميع الأجهزة أو قد يكون غير مفعَّل. يمكنك التحقّق من توفّره باستخدام طريقة HealthConnectClient.getSdkStatus().

كيفية التحقّق من توفُّر Health Connect

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

في ما يلي الإذن الذي عليك تضمينه في نموذج البيان لتتمكّن من كتابة بيانات الخطوات:

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

لقراءة بيانات الخطوات، عليك طلب الأذونات التالية:

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

طلب الأذونات من المستخدم

بعد إنشاء مثيل للعميل، يحتاج تطبيقك إلى طلب الأذونات من المستخدم. يجب أن يتمكّن المستخدمون من منح الأذونات أو رفضها في أي وقت.

لإجراء ذلك، أنشئ مجموعة من الأذونات لأنواع البيانات المطلوبة. تأكَّد من أنّ الأذونات في المجموعة مضمّنة في بيان Android أولاً.

// 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:

تتوفّر القيم المجمّعة التالية لـ StepsCadenceRecord:

مثال للاستخدام

توضّح الأقسام التالية كيفية قراءة بيانات StepsRecord وكتابتها.

كتابة بيانات الخطوات

يمكن لتطبيقك كتابة بيانات عدد الخطوات من خلال إدراج StepsRecord مثيلات. يوضّح المثال التالي كيفية تسجيل 1000 خطوة اتخذها أحد المستخدمين:

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata(
        device = Device(type = Device.TYPE_WATCH),
        recordingMethod = Metadata.RECORDING_METHOD_AUTOMATICALLY_RECORDED
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

قراءة البيانات المجمّعة

إنّ الطريقة الأكثر شيوعًا لقراءة بيانات الخطوات هي تجميع إجمالي الخطوات خلال فترة زمنية. يوضّح المثال التالي كيفية قراءة إجمالي عدد الخطوات لمستخدم خلال نطاق زمني معيّن:

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
}

قراءة البيانات الأولية

يوضّح المثال التالي كيفية قراءة بيانات StepsRecord الأولية بين وقتَي البدء والانتهاء:

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