Começar a usar o app Conexão Saúde

Este guia é compatível com a versão 1.1.0-alpha12 do Health Connect.

Este guia mostra como começar a usar o app Conexão Saúde.

Etapa 1: preparar o app Conexão Saúde

O app Conexão Saúde é responsável por processar todas as solicitações enviadas pelo seu aplicativo usando o SDK. Essas solicitações incluem o armazenamento de dados e o gerenciamento do acesso de leitura e gravação.

O acesso à Conexão Saúde depende da versão do Android instalada no smartphone. As seções abaixo descrevem como lidar com várias versões recentes do Android.

Android 14

No Android 14 (nível 34 da API) e versões mais recentes, a Conexão Saúde faz parte do framework do Android. Essa versão da Conexão Saúde é um módulo de framework. Com isso, não é necessário fazer nenhuma configuração.

Android 13 e versões anteriores

No Android 13 (nível 33 da API) e versões anteriores, a Conexão Saúde não faz parte do framework do Android. Você precisa instalar o app Conexão Saúde na Google Play Store.

Se você integrou seu app à Conexão Saúde no Android 13 e em versões anteriores e quer migrar para o Android 14, consulte Migrar do Android 13 para o 14.

Abra o app Conexão Saúde.

A Conexão Saúde não aparece mais na tela inicial por padrão. Você pode abrir a Conexão Saúde em Configurações, mas o caminho varia de acordo com a versão do Android:

• No Android 14 e versões mais recentes:acesse Configurações > Segurança e privacidade > Controles de privacidade > Conexão Saúde ou pesquise Conexão Saúde nas Configurações.
• No Android 13 e em versões anteriores:acesse Configurações > Apps > Conexão Saúde ou adicione a Conexão Saúde ao menu Configurações rápidas.

Etapa 2: adicionar o SDK do Health Connect ao seu app

O SDK do Conexão Saúde é responsável por usar a API para enviar solicitações ao realizar operações no repositório de dados do app Conexão Saúde.

Adicione a dependência do SDK do Conexão Saúde ao arquivo build.gradle no nível do módulo:

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.2.0-alpha02"
  ...
}

Consulte as versões da Conexão Saúde para conferir a versão mais recente.

Observação: o SDK da plataforma Conexão Saúde oferece suporte ao Android 8 (nível 26 da API) ou versões mais recentes, enquanto o app Conexão Saúde só é compatível com o Android 9 (nível 28 da API) ou versões mais recentes. Isso significa que apps de terceiros têm suporte para usuários do Android 8, mas apenas usuários com o Android 9 ou versões mais recentes podem usar o app Conexão Saúde.

Etapa 3: configurar o app

As seções a seguir explicam como configurar seu app para integrar ao Health Connect.

Verificar a disponibilidade dos recursos

Quando novos recursos são adicionados à Conexão Saúde, os usuários nem sempre atualizam a versão do app. A API Feature Availability é uma maneira de verificar se um recurso do Conexão Saúde está disponível no dispositivo do usuário e decidir qual ação tomar.

A principal função para verificar a disponibilidade de recursos é getFeatureStatus(). Isso retorna constantes inteiras FEATURE_STATUS_AVAILABLE ou FEATURE_STATUS_UNAVAILABLE:

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
  ...
} else {
  // Feature is not available
  ...
}

Observação: se um recurso não estiver disponível, peça para o usuário atualizar o Conexão Saúde. Os recursos vinculados ao módulo do sistema continuam indisponíveis no Android 13 e em versões anteriores, mesmo com o APK.

Declarar permissões

O acesso a dados de saúde e condicionamento físico é sensível. O app Conexão Saúde implementa uma camada de segurança para operações de leitura e gravação, mantendo a confiança do usuário.

No app, declare as permissões de leitura e gravação no arquivo AndroidManifest.xml com base nos tipos de dados necessários, que precisam corresponder aos que você declarou ter acesso no Play Console.

A Conexão Saúde usa o formato de declaração de permissão padrão do Android. Atribua permissões com as tags <uses-permission>. Aninhe as permissões nas tags <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 a lista completa de permissões e os tipos de dados correspondentes, consulte Lista de tipos de dados.

Mostrar a caixa de diálogo da Política de Privacidade do app

Seu manifesto do Android precisa ter uma atividade que mostre a Política de Privacidade do app, que é a justificativa das permissões solicitadas, descrevendo como os dados do usuário são usados e tratados.

Declare essa atividade para processar a intent ACTION_SHOW_PERMISSIONS_RATIONALE enviada ao app quando o usuário clica no link Política de Privacidade na tela de permissões do app Conexão Saúde.

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

Acessar um cliente da Conexão Saúde

HealthConnectClient é um ponto de entrada para a API Health Connect. Ele permite que o app use o armazenamento de dados no app Conexão Saúde. Ele gerencia automaticamente a conexão com a camada de armazenamento e processa toda a IPC e a serialização das solicitações enviadas e das respostas recebidas.

Para receber uma instância do cliente, declare primeiro o nome do pacote da Conexão Saúde no manifesto do Android.

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

Em seguida, na sua atividade, verifique se o Conexão Saúde está instalado usando getSdkStatus. Se estiver, acesse uma instância 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

Etapa 4: solicitar permissões do usuário

Depois de criar uma instância de cliente, seu app precisa solicitar permissões do usuário. Os usuários precisam poder conceder ou negar permissões a qualquer momento.

Para isso, crie um conjunto de permissões para os tipos de dados necessários. Verifique se as permissões no conjunto foram declaradas primeiro no manifesto do 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)
)

Use getGrantedPermissions para verificar se o app já tem as permissões necessárias concedidas. Caso contrário, use createRequestPermissionResultContract para solicitar essas permissões. Isso mostra a tela de permissões da Conexão Saúde.

// 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 os usuários podem conceder ou revogar permissões a qualquer momento, seu app precisa verificar periodicamente as permissões concedidas e lidar com cenários em que a permissão é perdida.

Integrar usuários

Muitos apps têm um fluxo de integração personalizado, como instruções sobre recursos ou pedidos de consentimento do usuário. Para permitir que a Conexão Saúde inicie seu fluxo de integração, adicione o seguinte ao manifesto:

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

Os usuários podem iniciar a conexão com seu app diretamente no app Conexão Saúde, em vez de fazer isso no seu app. Se o app exigir alguma interação adicional além da permissão para ler ou gravar dados, forneça uma atividade de integração.

A atividade de integração pode ser iniciada mais de uma vez, por exemplo, se o usuário revogar as permissões do app e depois reconectar.

Etapa 5: realizar operações

Agora que tudo está configurado, faça operações de leitura e gravação no seu app.

Gravar dados

Estruture seus dados em um registro. Confira a lista de tipos de dados disponíveis no Conexão Saúde.

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

Em seguida, grave o registro usando insertRecords.

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(15))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            ),
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Ler dados

É possível ler seus dados individualmente usando readRecords.

Observação: para tipos cumulativos, como StepsRecord, use aggregate() em vez de readRecords() para evitar contagem dupla de várias fontes e melhorar a precisão. Consulte Ler dados agregados para mais informações.

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

Você também pode ler seus dados de maneira agregada usando 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: a Conexão Saúde pode ler dados registrados até 30 dias antes da permissão ser concedida. Se você quiser que o app leia registros além de 30 dias, use a permissão PERMISSION_READ_HEALTH_DATA_HISTORY. Consulte Restrições de leitura para mais informações.

Tutoriais em vídeo

Assista a estes vídeos que explicam mais sobre os recursos da Conexão Saúde e as diretrizes de práticas recomendadas para uma integração tranquila:

• Como gerenciar permissões na Conexão Saúde
• Como ler e gravar na Conexão Saúde
• Dicas para uma ótima integração com a Conexão Saúde

Recursos

Confira os seguintes recursos que ajudam no desenvolvimento mais tarde.

• SDK do Conexão Saúde (disponível no Jetpack): inclua este SDK no seu aplicativo para usar a API do Conexão Saúde.
• Referência da API:consulte a referência do Jetpack para a API Conexão Saúde.
• Declare o uso de tipos de dados:no Play Console, declare o acesso aos tipos de dados do Conexão Saúde que seu app lê e grava.
• Exemplo de código e codelab opcionais do GitHub:consulte o repositório de exemplo de código do GitHub e o exercício do codelab para começar.

Observação: se você estiver fazendo outra solicitação porque o app precisa de novos tipos de dados, inclua os tipos novos e os atuais e exclua os que não são mais necessários. Se você só precisar remover o acesso a determinados tipos de dados, inclua todos os tipos de dados atuais, mas exclua os que não são mais necessários.

Próximas etapas

Confira Fluxos de trabalho comuns para saber como realizar operações na Conexão Saúde, como:

• Gravar dados
• Ler dados brutos
• Ler dados agregados