Ler dados brutos

O exemplo abaixo mostra como ler dados brutos do fluxo de trabalho comum.

Ler dados

A Conexão Saúde permite que os apps leiam dados do repositório quando estão em primeiro plano e em segundo plano:

• Leituras em primeiro plano: normalmente, você pode ler dados da Conexão Saúde quando o app está em primeiro plano. Nesses casos, considere usar um serviço em primeiro plano para executar essa operação caso o usuário ou o sistema coloque seu app em segundo plano durante uma operação de leitura.

• Leituras em segundo plano: ao solicitar uma permissão extra do usuário, você pode ler dados depois que o usuário ou o sistema coloca o app em segundo plano. Confira o exemplo completo de leitura em segundo plano.

O tipo de dados "passos" no Conexão Saúde captura o número de passos que um usuário deu entre as leituras. A contagem de passos representa uma medida comum nas plataformas de saúde, condicionamento físico e bem-estar. Com a Conexão Saúde, é possível ler e gravar dados de contagem de passos.

Para ler registros, crie uma ReadRecordsRequest e forneça quando você chamar readRecords.

O exemplo abaixo mostra como ler dados de contagem de passos de um usuário em um determinado período. Para um exemplo mais detalhado com SensorManager, consulte o guia de dados de contagem de passos.

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

Você também pode ler seus dados de maneira agregada usando aggregate.

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
}
HealthConnectManager.kt

Ler passos em dispositivos móveis

Com o Android 14 (nível 34 da API) e a extensão do SDK versão 20 ou mais recente, a Conexão Saúde oferece contagem de passos no dispositivo. Se algum app tiver recebido a permissão READ_STEPS, o Conexão Saúde vai começar a capturar passos do dispositivo Android, e os usuários vão ver os dados de passos adicionados automaticamente às entradas de Passos do Conexão Saúde.

Para verificar se a contagem de passos no dispositivo está disponível, confira se o dispositivo está executando o Android 14 (nível 34 da API) e tem pelo menos a versão 20 da extensão do SDK:

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

Se o app ler contagens de passos agregadas usando aggregate e não filtrar por DataOrigin, as etapas no dispositivo serão incluídas automaticamente no total, e nenhuma mudança será necessária para a atualização de junho de 2026.

Mudança na atribuição para etapas no dispositivo

A partir da atualização de junho de 2026, as etapas rastreadas nativamente pela Conexão Saúde serão atribuídas a um nome de pacote sintético (SPN), como com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e.

Antes, as etapas integradas eram atribuídas ao nome do pacote android. Os dados históricos de passos registrados antes de junho de 2026 mantêm o nome do pacote android.

Os SPNs são específicos do dispositivo e têm escopo por aplicativo para proteger a privacidade do usuário:

• Estável:o SPN do dispositivo atual está estável para seu aplicativo.
• No escopo do aplicativo:diferentes aplicativos no mesmo dispositivo veem SPNs diferentes para dados de etapas no dispositivo.

Consultar etapas no dispositivo

Como os SPNs são específicos do dispositivo e têm escopo, não codifique valores de SPN. Em vez disso, use a API getCurrentDeviceDataSource() para recuperar o SPN do dispositivo atual.

Embora a contagem de passos no dispositivo exija a versão 20 ou mais recente da extensão do SDK, a API getCurrentDeviceDataSource() está disponível no Android 14 (nível 34 da API) com a versão 11 ou mais recente da extensão do SDK.

A API getCurrentDeviceDataSource() ainda não está disponível na biblioteca Conexão Saúde do Jetpack. Os exemplos a seguir usam a API do framework 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

Se o app precisar ler etapas no dispositivo ou mostrar dados de etapas divididos por aplicativo ou dispositivo de origem, consulte os registros em que o DataOrigin é android ou corresponde ao SPN do dispositivo. Se o app mostrar a atribuição dos dados de passos, use metadata.device para identificar o dispositivo de origem dos registros individuais. Para etapas no dispositivo identificadas por um SPN em dados agregados, use metadados do dispositivo, como model ou manufacturer de DeviceDataSource para atribuição, ou use um rótulo genérico, como "Seu smartphone", para etapas no dispositivo.

O exemplo a seguir mostra como ler dados agregados de contagem de passos no dispositivo filtrando por android e o SPN do dispositivo atual:

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

Contagem de passos no dispositivo

• Uso de sensores: o app Conexão Saúde usa o sensor TYPE_STEP_COUNTER do SensorManager. Esse sensor é otimizado para baixo consumo de energia, o que o torna ideal para rastreamento contínuo de passos em segundo plano.
• Granularidade dos dados: para conservar a duração da bateria, os dados de passos geralmente são agrupados e gravados no banco de dados da Conexão Saúde no máximo uma vez por minuto.
• Atribuição: as etapas registradas por esse recurso antes de junho de 2026 são atribuídas ao nome do pacote android no DataOrigin. Depois dessa data, eles serão atribuídos a um SPN específico do dispositivo. Consulte Mudança na atribuição para etapas no dispositivo.
• Ativação: o mecanismo de contagem de passos no dispositivo só fica ativo quando pelo menos um aplicativo no dispositivo recebe a permissão READ_STEPS na Conexão Saúde.

Exemplo de leitura em segundo plano

Para ler dados em segundo plano, declare a seguinte permissão no arquivo de manifesto:

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

O exemplo abaixo mostra como ler dados de contagem de passos em segundo plano para um usuário em um determinado período usando WorkManager:

class ScheduleWorker(appContext: Context, workerParams: WorkerParameters) :
    CoroutineWorker(appContext, workerParams) {

    override suspend fun doWork(): Result {
        val healthConnectClient = HealthConnectClient.getOrCreate(applicationContext)
        // Perform background read logic here
        return Result.success()
    }
}
HealthConnectWorker.kt

@OptIn(ExperimentalFeatureAvailabilityApi::class)
fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}
HealthConnectWorker.kt

O parâmetro ReadRecordsRequest tem um valor padrão pageSize de 1000. Se o número de registros em um único readResponse exceder o pageSize da solicitação, será necessário iterar todas as páginas da resposta para recuperar todos os registros usando pageToken. No entanto, tome cuidado para evitar problemas de limitação de taxa.

Exemplo de leitura de pageToken

Recomendamos usar pageToken para ler registros e recuperar todos os dados disponíveis do período solicitado.

O exemplo a seguir mostra como ler todos os registros até que todos os tokens de página tenham sido usados:

val type = HeartRateRecord::class
val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofDays(7))

try {
    var pageToken: String? = null
    do {
        val readResponse =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    recordType = type,
                    timeRangeFilter = TimeRangeFilter.between(
                        startTime,
                        endTime
                    ),
                    pageToken = pageToken
                )
            )
        val records = readResponse.records
        // Do something with records
        pageToken = readResponse.pageToken
    } while (pageToken != null)
} catch (quotaError: IllegalStateException) {
    // Backoff
}
HealthConnectManager.kt

Ler dados gravados anteriormente

Se um app tiver gravado registros na Conexão Saúde antes, ele poderá ler dados históricos. Isso se aplica a cenários em que o app precisa ser sincronizado novamente com a Conexão Saúde depois que o usuário o reinstala.

Algumas restrições de leitura se aplicam:

• Para Android 14 e versões mais recentes

  • Não há limite histórico para um app ler os próprios dados.
  • Limite de 30 dias para um app ler outros dados.

• Para Android 13 e versões anteriores

  • Limite de 30 dias para leitura de dados por apps.

Para remover as restrições, peça uma permissão de leitura.

Para ler dados históricos, é necessário indicar o nome do pacote como um objeto DataOrigin no parâmetro dataOriginFilter da ReadRecordsRequest.

O exemplo abaixo mostra como indicar o nome de um pacote ao ler registros de frequência cardíaca:

try {
    val response =  healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = HeartRateRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
            dataOriginFilter = setOf(DataOrigin("com.my.package.name"))
        )
    )
    for (record in response.records) {
        // Process each record
    }
} catch (e: Exception) {
    // Run error handling here
}
HealthConnectManager.kt

Ler dados com mais de 30 dias

Por padrão, todos os aplicativos podem ler dados da Conexão Saúde registrados até 30 dias antes da permissão ser concedida.

Se você precisar estender as permissões de leitura além de qualquer uma das restrições padrão, solicite o PERMISSION_READ_HEALTH_DATA_HISTORY. Caso contrário, sem essa permissão, uma tentativa de ler registros com mais de 30 dias resulta em um erro.

Histórico de permissões de um app excluído

Se um usuário excluir seu app, todas as permissões, incluindo a de histórico, serão revogadas. Se o usuário reinstalar o app e conceder a permissão novamente, as mesmas restrições padrão serão aplicadas, e o app poderá ler dados da Conexão Saúde registrados até 30 dias antes dessa nova data.

Por exemplo, suponha que o usuário exclua seu app em 10 de maio de 2023 e o reinstale em 15 de maio de 2023, concedendo permissões de leitura. A data mais antiga de que o app poderá ler dados por padrão é 15 de abril de 2023.

Tratar exceções

A plataforma Conexão Saúde gera exceções padrão para operações CRUD quando um problema é encontrado. O app precisa capturar e processar cada uma dessas exceções conforme adequado.

Cada método no HealthConnectClient lista as exceções que podem ser geradas. Em geral, o app precisa lidar com as seguintes exceções: