Adımları izleme

Health Connect, StepsRecord kullanarak adım sayılarını kaydetmek için adım veri türü sağlar. Adım sayısı, sağlık ve fitness takibinde temel bir ölçümdür.

Bu kılavuz, Health Connect 1.1.0-alpha12 veya sonraki sürümlerle uyumludur.

Mobil adımları okuma

Android 14 (API düzeyi 34) ve SDK Uzantısı sürüm 20 veya sonraki sürümlerde Health Connect, cihaz üzerinde adım sayma özelliği sunar. Herhangi bir uygulamaya READ_STEPS izni verilirse Health Connect, Android cihazdan adım sayısını kaydetmeye başlar ve kullanıcılar, adım verilerinin Health Connect Adım girişlerine otomatik olarak eklendiğini görür.

Cihaz üzerinde adım sayma özelliğinin kullanılabilir olup olmadığını kontrol etmek için cihazda Android 14 (API düzeyi 34) ve en az SDK uzantısı sürüm 20'nin yüklü olduğunu doğrulayın:

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

Uygulamanız, aggregate kullanarak toplu adım sayılarını okuyor ve DataOrigin ölçütüne göre filtreleme yapmıyorsa cihaz üzerinde adımlar otomatik olarak toplama dahil edilir ve Haziran 2026 güncellemesi için herhangi bir değişiklik yapılması gerekmez.

Cihaz üzerinde gerçekleştirilen adımlar için ilişkilendirme değişikliği

Haziran 2026 güncellemesinden itibaren, Health Connect tarafından yerel olarak izlenen adımlar Sentetik Paket Adı (SPN) ile ilişkilendirilir (ör. com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e).

Daha önce, yerleşik adımlar android paket adına atfediliyordu. Haziran 2026'dan önce kaydedilen geçmiş adım verileri, android paket adını korur.

SPN'ler cihaza özeldir ve kullanıcı gizliliğini korumak için uygulama bazında kapsamlandırılır:

  • Kararlı: Mevcut cihazın SPN'si uygulamanız için kararlı.
  • Uygulama kapsamlı: Aynı cihazdaki farklı uygulamalar, cihaz üzerindeki adım verileri için farklı SPN'ler görür.

Cihaz üzerinde gerçekleştirilen adımları sorgulama

SPN'ler kapsamlı ve cihaza özel olduğundan SPN değerlerini sabit kodlamamanız gerekir. Bunun yerine, mevcut cihazın SPN'sini almak için getCurrentDeviceDataSource API'sini kullanın.

Cihaz üzerinde adım sayma için SDK uzantısı sürüm 20 veya sonraki sürümler gerekirken getCurrentDeviceDataSource() API, Android 14 (API düzeyi 34) ve SDK uzantısı sürüm 22 veya sonraki sürümlerde kullanılabilir. Bu API'yi kullanmak için modül düzeyindeki build.gradle.kts veya build.gradle dosyanızda compileSdkExtension değerini 22 veya daha yüksek bir değere ayarlayın:

Kotlin

android {
    compileSdk = 35
    compileSdkExtension = 22
}

Modern

android {
    compileSdk 35
    compileSdkExtension 22
}

getCurrentDeviceDataSource() API'si henüz Health Connect Jetpack kitaplığında kullanılamıyor. Aşağıdaki örneklerde, Executor ve OutcomeReceiver geri çağırma işlevi gerektiren Android çerçeve API'si kullanılmaktadır:

import android.content.Context
import android.health.connect.DeviceDataSource
import android.health.connect.HealthConnectException
import android.health.connect.HealthConnectManager
import android.os.OutcomeReceiver

val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)
healthConnectManager?.getCurrentDeviceDataSource(
    context.mainExecutor,
    object : OutcomeReceiver<DeviceDataSource, HealthConnectException> {
        override fun onResult(result: DeviceDataSource) {
            val currentDeviceSpn = result.deviceDataOrigin.packageName
        }

        override fun onError(error: HealthConnectException) {
            // Handle error
        }
    }
)

Uygulamanızın cihaz üzerindeki adımları okuması gerekiyorsa veya adım verilerini kaynak uygulama ya da cihaza göre döküm halinde gösteriyorsa DataOrigin değerinin android olduğu veya cihazın SPN'siyle eşleştiği kayıtları sorgulamanız gerekir. Uygulamanız adım verileri için ilişkilendirme gösteriyorsa her bir kaydın kaynak cihazını tanımlamak için metadata.device kullanın. Birleştirilmiş verilerde SPN ile tanımlanan cihaz üzerinde adımlar için ilişkilendirme amacıyla DeviceDataSource üzerinden model veya manufacturer gibi cihaz meta verilerini kullanabilir ya da cihaz üzerinde adımlar için "Telefonunuz" gibi genel bir etiket kullanabilirsiniz.

Aşağıdaki örnekte, hem android hem de mevcut cihaz SPN'si için filtreleme yaparak cihaz üzerinde toplanan adım sayısı verilerinin nasıl okunacağı gösterilmektedir:

import android.content.Context
import android.health.connect.DeviceDataSource
import android.health.connect.HealthConnectException
import android.health.connect.HealthConnectManager
import android.os.Build
import android.os.OutcomeReceiver
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
import kotlin.coroutines.resume
import kotlin.coroutines.resumeWithException
import kotlinx.coroutines.suspendCancellableCoroutine

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

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

        // 2. Safely fetch the package name only if the API is available
        val currentDeviceSpn = if (isDataSourceApiAvailable && healthConnectManager != null) {
            suspendCancellableCoroutine { continuation ->
                healthConnectManager.getCurrentDeviceDataSource(
                    context.mainExecutor,
                    object : OutcomeReceiver<DeviceDataSource, HealthConnectException> {
                        override fun onResult(result: DeviceDataSource) {
                            continuation.resume(result.deviceDataOrigin.packageName)
                        }

                        override fun onError(error: HealthConnectException) {
                            continuation.resumeWithException(error)
                        }
                    }
                )
            }
        } 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.
    }
}

Cihaz Üzerinde Adım Sayma

  • Sensör Kullanımı: Health Connect, SensorManager uygulamasındaki TYPE_STEP_COUNTER sensörünü kullanır. Bu sensör, düşük güç tüketimi için optimize edildiğinden arka planda sürekli adım takibi için idealdir.
  • Veri ayrıntı düzeyi: Pil ömrünü korumak için adım verileri genellikle toplu olarak işlenir ve Health Connect veritabanına dakikada en fazla bir kez yazılır.
  • İlişkilendirme: Bu özellik tarafından Haziran 2026'dan önce kaydedilen adımlar, DataOrigin içindeki android paket adıyla ilişkilendirilir. Bu tarihten sonra, cihaza özel bir SPN ile ilişkilendirilirler. Cihaz üzerinde adımlar için ilişkilendirme değişikliği başlıklı makaleyi inceleyin.
  • Etkinleştirme: Cihazdaki adım sayma mekanizması, yalnızca cihazdaki en az bir uygulamaya Health Connect'te READ_STEPS izni verildiğinde etkin olur.

Health Connect'in kullanılabilirlik durumunu kontrol etme

Uygulamanız, Health Connect'i kullanmaya çalışmadan önce Health Connect'in kullanıcının cihazında kullanılabilir olduğunu doğrulamalıdır. Health Connect, tüm cihazlara önceden yüklenmemiş veya devre dışı bırakılmış olabilir. HealthConnectClient.getSdkStatus() yöntemini kullanarak kullanılabilirlik durumunu kontrol edebilirsiniz.

Health Connect'in kullanılabilirliğini kontrol etme

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata"
    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() tarafından döndürülen duruma bağlı olarak, kullanıcıyı gerekirse Google Play Store'dan Health Connect'i yüklemeye veya güncellemeye yönlendirebilirsiniz.

Gerekli izinler

Adımlara erişim aşağıdaki izinlerle korunur:

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

Uygulamanıza adım özelliğini eklemek için Steps veri türüyle ilgili izinleri isteyerek başlayın.

Adımları yazabilmek için beyan etmeniz gereken izin şudur:

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

Adımları okumak için aşağıdaki izinleri istemeniz gerekir:

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

Kullanıcıdan izin isteme

Uygulamanız, istemci örneği oluşturduktan sonra kullanıcıdan izin istemelidir. Kullanıcıların diledikleri zaman izin vermelerine veya izinleri reddetmelerine olanak tanınmalıdır. Bunun için gerekli veri türlerine yönelik bir izin grubu oluşturun. Öncelikle, kümedeki izinlerin Android manifest dosyanızda beyan edildiğinden emin olun. 

val permissions =
    setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
 Uygulamanızın gerekli izinlere sahip olup olmadığını görmek için getGrantedPermissions yöntemini kullanın. Aksi takdirde bu izinleri istemek için createRequestPermissionResultContract yöntemini kullanın. Health Connect izinleri ekranı açılır. 
val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
 Kullanıcılar istedikleri zaman izin verebildikleri veya izinleri iptal edebildikleri için uygulamanızın, izinleri kullanmadan önce her seferinde kontrol etmesi ve iznin kaybedildiği senaryoları yönetmesi gerekir.

Adım kaydında yer alan bilgiler

Her StepsRecord aşağıdaki bilgileri içerir:

  • count: Zaman aralığında atılan adım sayısı (Long olarak).
  • startTime: Ölçüm aralığının başlangıç zamanı.
  • endTime: Ölçüm aralığının bitiş zamanı.
  • startZoneOffset: Başlangıç zamanının saat dilimi farkı.
  • endZoneOffset: Bitiş zamanının bölge farkı.

Desteklenen toplamalar

StepsRecord için aşağıdaki toplu değerler kullanılabilir:

StepsCadenceRecord için aşağıdaki toplu değerler kullanılabilir:

Örnek kullanım

Aşağıdaki bölümlerde, StepsRecord verilerinin nasıl okunacağı ve yazılacağı gösterilmektedir.

Adım verilerini yazma

Uygulamanız, StepsRecord örnekleri ekleyerek adım sayısı verilerini yazabilir. Aşağıdaki örnekte, bir kullanıcının attığı 1.000 adımın nasıl kaydedileceği gösterilmektedir:

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

Birleştirilmiş verileri okuma

Adım verilerini okumanın en yaygın yolu, belirli bir dönemdeki toplam adımları birleştirmektir. Aşağıdaki örnekte, belirli bir zaman aralığında bir kullanıcının toplam adım sayısının nasıl okunacağı gösterilmektedir:

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
}

Ham verileri okuma

Aşağıdaki örnekte, başlangıç ve bitiş zamanı arasındaki ham StepsRecord verilerinin nasıl okunacağı gösterilmektedir:

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