Cómo comenzar a usar Health Connect

En esta guía, se muestra cómo puedes comenzar a usar Health Connect en tu app.

Paso 1: Prepara la app de Health Connect

La app de Health Connect es responsable de controlar todas las solicitudes que envía tu aplicación a través del SDK de Health Connect. Estas solicitudes incluyen almacenar datos y administrar su acceso de lectura y escritura.

El acceso a Health Connect depende de la versión de Android instalada en el teléfono. En las siguientes secciones, se describe cómo controlar varias versiones recientes de Android.

Android 14

A partir de Android 14 (nivel de API 34), Health Connect forma parte del framework de Android. Esta versión de Health Connect es un módulo del framework. Con eso, no es necesario configurar nada.

Android 13 y versiones anteriores

En Android 13 (nivel de API 33) y versiones anteriores, Health Connect no forma parte del framework de Android. Con eso, debes instalar la app de Health Connect desde Google Play Store.

Si integraste tu app con Health Connect en Android 13 y versiones anteriores y deseas migrar en Android 14, consulta Cómo migrar de Android 13 a 14.

Cómo abrir la app de Health Connect

Health Connect ya no aparece en la pantalla principal de forma predeterminada. Para abrir Health Connect, ve a Configuración > Apps > Health Connect o agrega Health Connect al menú de Configuración rápida.

Además, Health Connect requiere que el usuario tenga habilitado el bloqueo de pantalla con un PIN, un patrón o una contraseña para que los datos de salud que se almacenan en Health Connect estén protegidos contra terceros maliciosos mientras el dispositivo está bloqueado. Para establecer un bloqueo de pantalla, ve a Configuración > Seguridad > Bloqueo de pantalla.

Paso 2: Agrega el SDK de Health Connect a tu app

El SDK de Health Connect es responsable de usar la API de Health Connect para enviar solicitudes durante la realización de operaciones en el almacén de datos de la app de Health Connect.

Agrega la dependencia del SDK de Health Connect en tu archivo build.gradle de nivel de módulo:

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.1.0-alph10"
  ...
}

Consulta las versiones de Health Connect para conocer la versión más reciente.

Nota: El SDK de Health Connect admite Android 8 (nivel de API 26) y versiones posteriores, mientras que la app de Health Connect solo es compatible con Android 9 (nivel de API 28) o versiones posteriores. Esto significa que las apps de terceros pueden admitir usuarios de Android 8, pero solo los que tienen Android 9 o versiones posteriores pueden usar Health Connect.

Paso 3: Configura tu app

En las siguientes secciones, se explica cómo configurar tu app para integrarla a Health Connect.

Cómo declarar permisos

El acceso a los datos de salud y actividad física es sensible. Health Connect implementa una capa de seguridad para las operaciones de lectura y escritura, lo que mantiene la confianza del usuario.

En tu app, declara permisos de lectura y escritura en el archivo AndroidManifest.xml según los tipos de datos requeridos, que deben coincidir con los a los que declaraste acceso en Play Console.

Health Connect usa el formato de declaración de permisos estándar de Android. Asigna permisos con las etiquetas <uses-permission>. Anídalos dentro de las etiquetas <manifest>.

<manifest>
  <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.WRITE_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.READ_STEPS"/>
  <uses-permission android:name="android.permission.health.WRITE_STEPS"/>

  <application>
  ...
  </application>
</manifest>

Para obtener la lista completa de permisos y sus tipos de datos correspondientes, consulta la Lista de tipos de datos.

Cómo mostrar el diálogo de la política de privacidad de tu app

Tu manifiesto de Android debe tener una actividad que muestre la política de privacidad de tu app, que es la lógica de los permisos solicitados, y que describa cómo se usan y se controlan los datos del usuario.

Declara esta actividad para controlar el intent ACTION_SHOW_PERMISSIONS_RATIONALE que se envía a la app cuando el usuario hace clic en el vínculo de la política de privacidad, en la pantalla de permisos de Health Connect.

...
<application>
  ...
  <!-- For supported versions through Android 13, create an activity to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity
      android:name=".PermissionsRationaleActivity"
      android:exported="true">
    <intent-filter>
      <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
  </activity>

  <!-- For versions starting Android 14, create an activity alias to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity-alias
      android:name="ViewPermissionUsageActivity"
      android:exported="true"
      android:targetActivity=".PermissionsRationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
      <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
      <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
  </activity-alias>
  ...
</application>
...

Cómo obtener un cliente de Health Connect

HealthConnectClient es un punto de entrada a la API de Health Connect. Permite que la app use el almacén de datos en la app de Health Connect. Administra automáticamente la conexión con la capa de almacenamiento subyacente y controla la IPC y la serialización completas de las solicitudes salientes y las respuestas entrantes.

Para obtener una instancia de cliente, primero declara el nombre del paquete de Health Connect en tu manifiesto de Android.

<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

Luego, en tu actividad, verifica si Health Connect está instalado con getSdkStatus. De ser así, obtén una instancia de HealthConnectClient.

val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
  return // early return as there is no viable integration
}
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
  // 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
}
val healthConnectClient = HealthConnectClient.getOrCreate(context)
// Issue operations with healthConnectClient

Paso 4: 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(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  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)
  }
}

No des por sentado que los permisos son constantes, ya que los usuarios pueden otorgarlos o revocarlos en cualquier momento. Tu app necesita verificar en forma periódica los permisos otorgados y controlar situaciones en las que el permiso se pierde.

Paso 5: Realiza operaciones

Ahora que todo está configurado, realiza operaciones de lectura y escritura en tu app.

Cómo escribir datos

Estructura los datos en un registro. Consulta la lista de tipos de datos disponibles en Health Connect.

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET,
)

Luego, escribe tu registro usando insertRecords.

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET,
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Cómo leer datos

Puedes leer tus datos individualmente con readRecords.

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

También puedes leer tus datos de forma agregada con aggregate.

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

Importante: Health Connect puede leer datos hasta 30 días antes de la fecha en que se otorgó el permiso por primera vez. Sin embargo, si un usuario borra tu app, se perderá el historial de permisos. Si el usuario vuelve a instalar tu app y le otorga permiso de nuevo, Health Connect podrá leer datos hasta 30 días antes de esa fecha nueva.

Videos instructivos

Mira estos videos que explican más sobre las funciones de Health Connect, así como los lineamientos y las prácticas recomendadas para obtener una integración fluida:

• Cómo administrar permisos en Health Connect
• Cómo leer y escribir en Health Connect
• Sugerencias para lograr una excelente integración con Health Connect

Recursos

Consulta los siguientes recursos que te ayudarán con el desarrollo más adelante.

• SDK de Health Connect (disponible en Jetpack): Incluye este SDK en tu aplicación para usar la API de Health Connect
• Referencia de la API: Consulta la referencia de Jetpack para la API de Health Connect
• Declara el uso de los tipos de datos: En Play Console, declara el acceso a los tipos de datos de Health Connect de los que lee y escribe tu app.
• Muestra de código de GitHub y codelab opcionales: Para comenzar, consulta el repositorio de muestras de código de GitHub y el ejercicio del codelab.

Nota: Si solicitas otra solicitud en caso de que tu app requiera tipos de datos nuevos, debes incluir los tipos de datos nuevos y existentes, y excluir los tipos de datos que ya no necesites. Si solo necesitas quitar el acceso a ciertos tipos de datos, incluye todos los tipos de datos existentes, pero excluye los tipos de datos que ya no necesitas.

Próximos pasos

Consulta Flujos de trabajo comunes para aprender a realizar operaciones en Health Connect, como las siguientes:

• Cómo escribir datos
• Cómo leer datos sin procesar
• Cómo leer datos agregados