Desenvolver experiências de treino com a Conexão Saúde

Este guia é compatível com a versão 1.1.0 ou mais recente do app Conexão Saúde.

Se você quer criar uma experiência de treino no seu app, use a Conexão Saúde para:

• Gravar sessões de exercícios
• Gravar trajetos de treino
• Gravar métricas de treino, como frequência cardíaca, velocidade e distância
• Ler dados de treino de outros apps

Neste guia, descrevemos como criar esses recursos de treino, incluindo tipos de dados, execução em segundo plano, permissões, fluxos de trabalho recomendados e práticas recomendadas.

Visão geral: como criar um monitor de treino completo

Para criar uma experiência completa de monitoramento de treinos usando a Conexão Saúde, siga estas etapas principais:

• Implementar corretamente as permissões com base nas permissões de saúde.
• Gravar sessões usando ExerciseSessionRecord.
• Gravar dados de treino de forma consistente durante a sessão.
• Gerenciar a execução em segundo plano corretamente para verificar a captura contínua de dados.
• Ler dados de sessões para resumos e análises pós-treino.

Esse fluxo de trabalho permite a interoperabilidade com outros apps da Conexão Saúde e verifica o acesso aos dados controlado pelo usuário.

Antes de começar

Antes de implementar os recursos de treino:

• Integre o Conexão Saúde usando a dependência adequada.
• Crie uma instância HealthConnectClient.
• Verifique se o app implementa fluxos de permissão de execução com base nas permissões de integridade.
• Se o fluxo de trabalho usar GPS, configure a permissão de localização e um serviço em primeiro plano.

Principais conceitos

A Conexão Saúde representa os dados de treino usando alguns componentes principais. Um ExerciseSessionRecord funciona como o registro central de um treino, contendo detalhes como horários de início ou término e tipo de exercício. Durante uma sessão, vários tipos de dados, como HeartRateRecord ou SpeedRecord, podem ser registrados. Para atividades ao ar livre, o ExerciseRoute armazena dados de GPS, que são vinculados à sessão correspondente.

Sessões de exercícios

ExerciseSessionRecord é o registro central de dados de treino, que representa uma única sessão de treino. Cada registro armazena:

• startTime
• endTime
• exerciseType
• Metadados de sessão opcionais (título, notas)

Um ExerciseSessionRecord também pode conter trajetos de exercícios, voltas e segmentos como parte dos dados. Além disso, outros tipos de dados, como HeartRateRecord ou SpeedRecord, podem ser registrados durante uma sessão e associados a ela.

Tipos de dados associados

Os dados associados às sessões de treino são representados por tipos de registro individuais. Alguns tipos comuns são:

• HeartRateRecord: representa uma série de medições de frequência cardíaca.
• SpeedRecord: representa uma série de medições de velocidade.
• DistanceRecord: representa a distância percorrida entre as leituras.
• TotalCaloriesBurnedRecord: representa o total de calorias queimadas entre as leituras.
• ElevationGainedRecord: representa o ganho de elevação entre as leituras.
• StepsCadenceRecord: representa a cadência de passos entre as leituras.
• PowerRecord: representa a potência entre as leituras, comum em atividades como ciclismo.

Para uma lista completa de tipos de dados, consulte Tipos de dados do Conexão Saúde.

Trajetos de exercícios

É possível associar um trajeto a treinos ao ar livre usando o ExerciseRoute. As rotas consistem em objetos ExerciseRoute.Location sequenciais, cada um contendo:

• Latitude e longitude
• Altitude opcional
• Ângulo opcional
• Informações de precisão
• Carimbo de data/hora

Vincular rotas de sessão

Um ExerciseRoute contém os dados de local sequenciais de uma sessão de exercícios. Ele não é tratado como um registro independente na Conexão Saúde. Em vez disso, você fornece dados de ExerciseRoute ao inserir ou atualizar um ExerciseSessionRecord.

Considerações de desenvolvimento

Os apps de monitoramento de treino geralmente precisam ser executados por períodos prolongados, com frequência em segundo plano quando a tela está desligada. Ao criar seus recursos de treino, é importante considerar como gerenciar a execução em segundo plano e solicitar as permissões necessárias para os dados de treino.

Execução em segundo plano

Os apps de treino geralmente são executados com a tela desligada. Nesse estado, use:

• Serviços em primeiro plano para amostragem de localização e sensores
• WorkManager para gravação ou sincronização adiada
• Estratégias de lote para gravação de registros regulares

Mantenha a continuidade mantendo o ID da sessão consistente em todas as gravações.

Permissões

Seu app precisa solicitar as permissões relevantes do Conexão Saúde antes de ler ou gravar dados de treino. As permissões comuns para treinos incluem sessões de exercícios, trajetos de exercícios e métricas como frequência cardíaca ou velocidade. Isso inclui o seguinte:

• Sessões de exercícios:permissões de leitura e gravação para ExerciseSessionRecord.
• Trajetos de exercícios:permissões de leitura e gravação para ExerciseRoute.
• Frequência cardíaca:permissões de leitura e gravação para HeartRateRecord.
• Velocidade:permissões de leitura e gravação para SpeedRecord.
• Distância:permissões de leitura e gravação para DistanceRecord.
• Calorias:permissões de leitura e gravação para TotalCaloriesBurnedRecord.
• Ganho de elevação:permissões de leitura e gravação para ElevationGainedRecord.
• Cadência dos passos:permissões de leitura e gravação para StepsCadenceRecord.
• Power:permissões de leitura e gravação para PowerRecord.
• Etapas:permissões de leitura e gravação para StepsRecord.

Veja um exemplo de como solicitar várias permissões para uma sessão de treino que inclui dados de trajeto, frequência cardíaca, distância, calorias, velocidade e passos:

Depois de criar uma instância de cliente, seu app precisa solicitar permissões aos usuários. Os usuários precisam concedê-las ou negá-las a qualquer momento. Para fazer isso, crie um conjunto de permissões para os tipos de dados necessários. Verifique se as permissões no conjunto foram declaradas no manifesto do Android primeiro.

val permissions =
    setOf(
        HealthPermission.getReadPermission(ExerciseSessionRecord::class),
        HealthPermission.getWritePermission(ExerciseSessionRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(SpeedRecord::class),
        HealthPermission.getWritePermission(SpeedRecord::class),
        HealthPermission.getReadPermission(DistanceRecord::class),
        HealthPermission.getWritePermission(DistanceRecord::class),
        HealthPermission.getReadPermission(TotalCaloriesBurnedRecord::class),
        HealthPermission.getWritePermission(TotalCaloriesBurnedRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
HealthConnectManager.kt

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.") }
    }
}
HealthConnectActivity.kt

Para solicitar permissões, chame a função checkPermissionsAndRun:

if (!granted.containsAll(permissions)) {
    // Check if required permissions are not granted, and return
    return emptySet()
}
// Permissions already granted; proceed with inserting or reading data
HealthConnectManager.kt

Se você só precisar solicitar permissões para um único tipo de dado, como frequência cardíaca, inclua apenas esse tipo no conjunto de permissões:

O acesso à frequência cardíaca é protegido pelas seguintes permissões:

• android.permission.health.READ_HEART_RATE
• android.permission.health.WRITE_HEART_RATE

Para adicionar a capacidade de frequência cardíaca ao app, solicite permissões para o tipo de dados HeartRateRecord.

Confira a permissão necessária para poder gravar a frequência cardíaca:

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

Para ler a frequência cardíaca, você precisa solicitar as seguintes permissões:

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

Implementar uma sessão de treino

Nesta seção, descrevemos o fluxo de trabalho recomendado para registrar dados de treino.

Iniciar a sessão

Para criar um treino:

1. Gere um ID de sessão exclusivo: verifique se ele é estável. Se o processo do app for encerrado e reiniciado, você precisará retomar o uso do mesmo ID para evitar sessões fragmentadas.
2. Defina um metadata.clientRecordId para evitar duplicatas durante as novas tentativas de sincronização.
3. Escreva um ExerciseSessionRecord: inclua o horário de início.
4. Comece a coletar o tipo de dados e os dados de GPS: só comece a coletar esses dados depois que o registro da sessão for inicializado.

Exemplo:

val sessionClientId = UUID.randomUUID().toString()
val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)

val session =   ExerciseSessionRecord(
    startTime = startTime,
    startZoneOffset = zoneOffset,
    endTime = startTime.plusSeconds(3600),
    endZoneOffset = zoneOffset,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    metadata = Metadata.activelyRecorded(clientRecordId = sessionClientId, device = Device(type = Device.TYPE_PHONE)),
)

healthConnectClient.insertRecords(listOf(session))
HealthConnectManager.kt

Registrar trajetos de exercícios

Para saber mais sobre as orientações de leitura, consulte Ler dados brutos.

Ao registrar um trajeto de exercício, é preciso agrupar os dados em lote. Isso significa que, em vez de salvar cada ponto de GPS conforme ele acontece, você coleta um grupo de pontos e salva todos de uma vez em uma única chamada.

Isso é importante porque, sempre que o app lê ou grava na Conexão Saúde, ele usa um pouco de bateria e capacidade de processamento.

O código a seguir mostra como gravar em lotes:

// 1. Create a list to hold your route locations
val routeLocations = mutableListOf<ExerciseRoute.Location>()

// 2. Add points to your list as the exercise happens
routeLocations.add(
    ExerciseRoute.Location(
        time = Instant.now(),
        latitude = 37.7749,
        longitude = -122.4194
    )
)

// ... keep adding points over a period of time ...

// 3. Save the whole list at once (Batching)
val session = ExerciseSessionRecord(
    startTime = startTime,
    endTime = endTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    // We pass the whole list here
    exerciseRoute = ExerciseRoute(routeLocations)
)

healthConnectClient.insertRecords(listOf(session))

Encerrar uma sessão

Depois de interromper a coleta de dados:

• Atualizar o registro: o app atualiza ExerciseSessionRecord com um endTime.
• Finalizar dados: opcionalmente, calcule valores de resumo (como distância total ou ritmo médio) e os grave como registros adicionais.

val finishedSession = session.copy(endTime = Instant.now())
healthConnectClient.updateRecords(listOf(finishedSession))

Ler dados de treino

Os apps podem ler sessões de exercícios e os dados associados para resumir a atividade, fornecer insights de saúde ou sincronizar dados com um servidor externo. Por exemplo, é possível ler um ExerciseSessionRecord e consultar o HeartRateRecord ou o DistanceRecord que ocorreu durante esse mesmo intervalo de tempo.

Se você precisar sincronizar dados de treino com um servidor de back-end ou manter o repositório de dados do seu app atualizado com o Conexão Saúde, use os registros de mudanças. Isso permite recuperar uma lista de registros inseridos, atualizados ou excluídos desde um momento específico, o que é mais eficiente do que rastrear manualmente as mudanças ou ler repetidamente todos os dados. Para mais informações, consulte Sincronizar dados com a Conexão Saúde.

Ler sessões

Para ler sessões de exercício, use um ReadRecordsRequest com ExerciseSessionRecord como o tipo. Normalmente, você filtra isso por um período específico.

suspend fun readExerciseSessions(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = ExerciseSessionRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )

    for (exerciseRecord in response.records) {
        // Process each session
        val exerciseType = exerciseRecord.exerciseType
        val notes = exerciseRecord.notes
    }
}

Ler rotas

Embora os dados de ExerciseRoute sejam gravados como parte de uma sessão de exercícios, eles precisam ser lidos separadamente. Use o método getExerciseRoute() com o ID da sessão para ler os dados de trajeto dela:

suspend fun readExerciseRoute(
    healthConnectClient: HealthConnectClient,
    exerciseSessionRecord: ExerciseSessionRecord
) {
    // Check if the session has a route
    val route = healthConnectClient.getExerciseRoute(
        exerciseSessionRecordId = exerciseSessionRecord.metadata.id
    )

    when (route) {
        is ExerciseRouteResponse.Success -> {
            val locations = route.exerciseRoute.locations
            for (location in locations) {
                // Use latitude, longitude, and altitude
            }
        }
        is ExerciseRouteResponse.NoData -> {
            // Handle case where no route exists
        }
        is ExerciseRouteResponse.ConsentRequired -> {
            // Handle case where permissions are missing
        }
    }
}

Tipos de dados de leitura

Para ler dados granulares específicos (como frequência cardíaca) que ocorreram durante uma sessão, use os valores startTime e endTime da sessão para filtrar a solicitação desse tipo de dados.

suspend fun readHeartRateData(
    healthConnectClient: HealthConnectClient,
    exerciseSession: ExerciseSessionRecord
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = HeartRateRecord::class,
            timeRangeFilter = TimeRangeFilter.between(
                exerciseSession.startTime,
                exerciseSession.endTime
            )
        )
    )

    for (heartRateRecord in response.records) {
        for (sample in heartRateRecord.samples) {
            val bpm = sample.beatsPerMinute
        }
    }
}

Práticas recomendadas

Siga estas diretrizes para melhorar a confiabilidade dos dados e a experiência do usuário:

• Gravar com frequência durante o monitoramento de atividade: para o monitoramento de atividade, grave os dados conforme eles forem disponibilizados ou em um intervalo máximo de 15 minutos.
• Use o WorkManager para sincronizações em segundo plano: use WorkManager para gravações adiadas. Busque um intervalo de 15 minutos para equilibrar os dados em tempo real e a eficiência da bateria.
• Solicitações de gravação em lote: não grave cada evento de sensor individualmente. Divida as solicitações em partes. O Conexão Saúde processa até 1.000 registros por solicitação de gravação.
• Mantenha os IDs de sessão estáveis e exclusivos: use identificadores consistentes para suas sessões. Se uma sessão for editada ou atualizada, o uso do mesmo ID impede que ela seja tratada como uma sessão nova e separada.
• Use o processamento em lote para tipos de dados e pontos de trajeto: para reduzir a sobrecarga de entrada/saída e preservar a duração da bateria, agrupe os pontos de dados em uma única chamada insertRecords em vez de gravar cada ponto individualmente.
• Evite gravar dados duplicados: use IDs de cliente: ao criar registros, defina um metadata.clientRecordId. O Conexão Saúde usa isso para identificar registros exclusivos. Se você tentar gravar um registro com um clientRecordId que já existe, a Conexão Saúde vai ignorar a cópia ou atualizar o registro atual em vez de criar um novo. Definir um metadata.clientRecordId é a maneira mais eficaz de evitar duplicatas durante novas tentativas de sincronização ou reinstalações de apps.
  

  val record = StepsRecord(
      count = 100,
      startTime = startTime,
      endTime = endTime,
      startZoneOffset = ZoneOffset.UTC,
      endZoneOffset = ZoneOffset.UTC,
      metadata = Metadata(
          // Use a unique ID from your own database
          clientRecordId = "daily_steps_2023_10_27_user_123"
      )
  )

• Verificar os dados atuais: antes de sincronizar, consulte o período para conferir se já existem registros do seu app.
• Validar a precisão do GPS: filtre as amostras de GPS de baixa precisão (por exemplo, pontos com um raio de precisão horizontal alto) antes de gravar no ExerciseRoute para verificar se o mapa está limpo e profissional.
• Verifique se os carimbos de data/hora não se sobrepõem: confirme se uma nova sessão não começa antes do término da anterior. Sessões sobrepostas podem causar conflitos nos painéis de condicionamento físico e nos cálculos de resumo.
• Forneça justificativas claras para a permissão: use o fluxo Permission.createIntent para explicar por que o app precisa de acesso aos dados de saúde, por exemplo: "Para monitorar suas tendências de pressão arterial e fornecer insights".
• Suporte para pausar e retomar: verifique se o app lida com pausas corretamente. Quando um usuário pausar, interrompa a coleta de pontos do trajeto e tipos de dados para que o ritmo médio e a duração permaneçam precisos.
• Teste sessões de longa duração: monitore o consumo da bateria durante sessões que duram várias horas para verificar se o intervalo de lote e o uso do sensor não descarregam o dispositivo.
• Alinhar os carimbos de data/hora com as taxas do sensor: combine os carimbos de data/hora do registro com a frequência real dos sensores para manter a alta fidelidade dos dados.

Teste

Para verificar a precisão dos dados e garantir uma experiência do usuário de alta qualidade, siga estas estratégias de teste e consulte a documentação oficial Testar os principais casos de uso.

Ferramentas de verificação

• Caixa de ferramentas do Conexão Saúde:use esse app complementar para inspecionar manualmente registros, excluir dados de teste e simular mudanças no banco de dados. É a melhor maneira de verificar se os registros estão sendo armazenados corretamente.
• Teste de unidade com FakeHealthConnectClient:use a biblioteca de testes para verificar como o app lida com casos extremos, como revogação de permissões ou exceções de API, sem precisar de um dispositivo físico.

Checklist de qualidade

Arquitetura típica

Uma implementação de treino geralmente inclui:

Solução de problemas

Etapas comuns de depuração