Adımları izleme

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

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 verildiyse Health Connect, Android destekli cihazdaki adımları kaydetmeye başlar ve kullanıcılar, Health Connect Adımlar girişlerine otomatik olarak eklenen adım verilerini görür.

Cihazda adım sayma özelliğinin kullanılabilir olup olmadığını kontrol etmek için cihazda Android 14 (API düzeyi 34) sürümünün yüklü olduğunu ve SDK uzantısı sürümünün en az 20 olduğunu doğrulamanız gerekir. Aşağıdaki kodu kullanabilirsiniz:

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

Health Connect tarafından kaydedilen mobil adımların DataOrigin değeri, paket adı olarak ayarlanır android. Uygulamanız yalnızca aggregate kullanarak toplanmış adım sayılarını okuyorsa ve DataOrigin ile filtreleme yapmıyorsa cihazdaki adımlar otomatik olarak toplama dahil edilir.

Uygulamanızın cihazdaki adımları okuması gerekiyorsa veya adım verilerini kaynak uygulamaya ya da cihaza göre ayrılmış şekilde gösteriyorsa DataOrigin değerinin android olduğu kayıtlar için sorgu oluşturabilirsiniz. Uygulamanız adım verileri için ilişkilendirme gösteriyorsa android paketindeki verileri mevcut cihaza atfetmeniz gerekir. Bunu yapmak için "Telefonunuz" gibi bir etiket kullanabilir, Settings.Global.getString(resolver, Settings.Global.DEVICE_NAME) ile cihaz adını alabilir veya kaydın meta verilerindeki Device alanını inceleyebilirsiniz.

Aşağıdaki örnekte, android veri kaynağına göre filtreleme yaparak birleştirilmiş mobil adım sayısı verilerinin nasıl okunacağı gösterilmektedir:

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
    }
}

Cihaz Üzerinde Adım Sayma

Cihaz üzerinde adım sayma özelliği hakkında daha fazla bilgi:

  • 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 edilmiştir. Bu nedenle, 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 gruplandırılır ve Health Connect veritabanına dakikada en fazla bir kez yazılır.
  • İlişkilendirme: Daha önce belirtildiği gibi, bu cihaz üzerinde özellik tarafından kaydedilen tüm adımlar, DataOrigin içindeki android paket adıyla ilişkilendirilir.
  • Etkinleştirme: Cihazdaki adım sayma mekanizması yalnızca cihazda en az bir uygulamaya Health Connect'te READ_STEPS izni verildiğinde etkin olur.

Health Connect'in kullanılabilirliğini kontrol etme

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

Health Connect'in kullanılabilirliğini kontrol etme

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() tarafından döndürülen duruma bağlı olarak, gerekirse kullanıcıyı 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 sayma özelliği eklemek için öncelikle Steps veri türü için yazma izni isteyerek başlayın.

Adım yazabilmek için beyan etmeniz gereken izin aşağıda verilmiştir:

<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 isteyin

İstemci örneği oluşturduktan sonra uygulamanızın kullanıcıdan izin istemesi gerekir. Kullanıcıların izinleri istedikleri zaman vermesine veya reddetmesine izin verilmelidir.

Bunu yapmak için gerekli veri türleri için bir izin grubu oluşturun. Gruptaki izinlerin önce Android manifestinizde tanımlandığından emin olun.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::class)
)

Uygulamanıza gerekli izinlerin verilip verilmediğini görmek için getGrantedPermissions aracını kullanın. Aksi takdirde, bu izinleri istemek için createRequestPermissionResultContract simgesini kullanın. Bu işlem, Health Connect izinleri ekranını gösterir.

// 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)
  }
}

Kullanıcılar izinleri istedikleri zaman verebilir veya iptal edebilir. Bu nedenle, uygulamanızın verilen izinleri düzenli olarak kontrol etmesi ve izinlerin kaybedildiği senaryoları yönetmesi gerekir.

Adımlar kaydında yer alan bilgiler

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

  • count: Zaman aralığında atılan adım sayısıdır (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 saat dilimi 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:

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
    }
}

Toplu verileri okuma

Adım verilerini okumanın en yaygın yolu, belirli bir süre boyunca atılan toplam adımları toplamaktır. 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(
    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
    }
}

Ham verileri okuma

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

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
    }
}