Cómo registrar tus pasos

Health Connect proporciona un tipo de datos de pasos para registrar el recuento de pasos con StepsRecord. Los pasos son una medición fundamental en el monitoreo de la salud y la actividad física.

Leer los pasos en dispositivos móviles

Con Android 14 (nivel de API 34) y la versión 20 o posterior de la extensión del SDK, Health Connect proporciona el recuento de pasos en el dispositivo. Si alguna app tiene el permiso de READ_STEPS, Health Connect comenzará a capturar los pasos del dispositivo Android y los usuarios verán los datos de pasos agregados automáticamente a las entradas de Pasos de Health Connect.

Para verificar si el recuento de pasos en el dispositivo está disponible, debes comprobar que el dispositivo ejecute Android 14 (nivel de API 34) y tenga al menos la versión 20 de la extensión del SDK. Puedes usar el siguiente código:

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

Los pasos de actividad capturados por Health Connect tienen su DataOrigin establecido en el nombre del paquete android. Si tu app simplemente lee los recuentos de pasos agregados con aggregate y no filtra por DataOrigin, los pasos registrados en el dispositivo se incluyen automáticamente en el total.

Si tu app necesita leer los pasos registrados en el dispositivo o si muestra datos de pasos desglosados por aplicación o dispositivo fuente, puedes consultar los registros en los que DataOrigin es android. Si tu app muestra la atribución de los datos de pasos, debes atribuir los datos del paquete de Android al dispositivo actual. Para ello, puedes usar una etiqueta como "Tu teléfono", recuperar el nombre del dispositivo con Settings.Global.getString(resolver, Settings.Global.DEVICE_NAME) o inspeccionar el campo Device en los metadatos del registro.

En el siguiente ejemplo, se muestra cómo leer los datos agregados del recuento de pasos en dispositivos móviles filtrando el origen de datos 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
    }
}

Recuento de pasos en el dispositivo

Análisis más detallado de la función de recuento de pasos en el dispositivo:

  • Uso del sensor: Health Connect utiliza el sensor TYPE_STEP_COUNTER de SensorManager. Este sensor está optimizado para un bajo consumo de energía, lo que lo hace ideal para el seguimiento continuo de pasos en segundo plano.
  • Granularidad de los datos: Para conservar la duración de la batería, los datos de pasos suelen agruparse y escribirse en la base de datos de Health Connect con una frecuencia no mayor a una vez por minuto.
  • Atribución: Como se mencionó anteriormente, todos los pasos que registra esta función integrada en el dispositivo se atribuyen al nombre del paquete android en DataOrigin.
  • Activación: El mecanismo de conteo de pasos en el dispositivo solo está activo cuando al menos una aplicación del dispositivo tiene el permiso READ_STEPS en Health Connect.

Cómo verificar la disponibilidad de Health Connect

Antes de intentar usar Health Connect, tu app debe verificar que esté disponible en el dispositivo del usuario. Es posible que Health Connect no esté preinstalado en todos los dispositivos o que esté inhabilitado. Puedes verificar la disponibilidad con el método HealthConnectClient.getSdkStatus().

Cómo verificar la disponibilidad de 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
}

Según el estado que devuelva getSdkStatus(), puedes guiar al usuario para que instale o actualice Health Connect desde Google Play Store si es necesario.

Permisos necesarios

El acceso a los pasos está protegido por los siguientes permisos:

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

Si deseas agregar la función de pasos a tu app, comienza por solicitar permisos de escritura para el tipo de datos Steps.

Este es el permiso que debes declarar para poder escribir pasos:

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

Para leer los pasos, debes solicitar los siguientes permisos:

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

Solicita permisos al usuario

Después de crear una instancia de cliente, tu app debe solicitarle permisos al usuario. Los usuarios deben poder otorgar o rechazar permisos en cualquier momento.

Para hacerlo, crea un conjunto de permisos para los tipos de datos necesarios. Primero, asegúrate de que los permisos del conjunto se declaren en tu manifiesto de Android.

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

Usa getGrantedPermissions para ver si tu app ya tiene otorgados los permisos necesarios. De lo contrario, usa createRequestPermissionResultContract para solicitarlos. Se mostrará la pantalla de permisos de 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)
  }
}

Como los usuarios pueden otorgar o revocar permisos en cualquier momento, tu app necesita verificar en forma periódica los permisos otorgados y controlar situaciones en las que el permiso se pierde.

Información incluida en un registro de Pasos

Cada StepsRecord contiene la siguiente información:

  • count: Es la cantidad de pasos dados en el intervalo de tiempo, como un Long.
  • startTime: Es la hora de inicio del intervalo de medición.
  • endTime: Es la hora de finalización del intervalo de medición.
  • startZoneOffset: Es la zona horaria de la hora de inicio.
  • endZoneOffset: Es la zona horaria de la hora de finalización.

Agregaciones admitidas

Los siguientes valores agregados están disponibles para StepsRecord:

Los siguientes valores agregados están disponibles para StepsCadenceRecord:

Ejemplo de uso

En las siguientes secciones, se muestra cómo leer y escribir datos de StepsRecord.

Cómo registrar datos de pasos

Tu app puede escribir datos de recuento de pasos insertando instancias de StepsRecord. En el siguiente ejemplo, se muestra cómo registrar los 1,000 pasos que dio un usuario:

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

Cómo leer datos agregados

La forma más común de leer los datos de pasos es agregar los pasos totales durante un período. En el siguiente ejemplo, se muestra cómo leer el recuento total de pasos de un usuario en un período determinado:

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

Cómo leer datos sin procesar

En el siguiente ejemplo, se muestra cómo leer datos StepsRecord sin procesar entre una hora de inicio y una hora de finalización:

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