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

Este guia mostra como você pode começar a usar o app Conexão Saúde no seu app.

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

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

O acesso ao Conexão Saúde depende da versão do Android instalada no smartphone. As seções a seguir 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. Esta versão da Conexão Saúde é um módulo de framework. Com isso, não é necessário configurar.

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. Com isso, é necessário instalar o app Conexão Saúde pela Google Play Store.

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

Abra o app Conexão Saúde.

O app Conexão Saúde não aparece mais na tela inicial por padrão. Para abrir o app Conexão Saúde, acesse Configurações > Apps > Conexão Saúde ou adicione o Conexão Saúde ao menu Configurações rápidas.

Além disso, o app Conexão Saúde exige que o usuário ative o bloqueio de tela com um PIN, padrão ou senha para que os dados de saúde armazenados na Conexão Saúde fiquem protegidos contra partes maliciosas enquanto o dispositivo estiver bloqueado. Para definir um bloqueio de tela, acesse Configurações > Segurança > Bloqueio de tela.

Etapa 2: adicionar o SDK da Conexão Saúde ao seu app

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

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

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

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

Etapa 3: configurar o app

As seções a seguir explicam como configurar seu app para integração com a Conexão Saúde.

Declarar permissões

O acesso a dados de saúde e condicionamento físico é sensível. A 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.

Declare permissões de leitura e gravação no arquivo AndroidManifest.xml com base nos tipos de dados necessários. Use o conjunto de permissões que você solicitou depois de preencher o formulário.

A plataforma 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-os 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 ver a lista completa de permissões e os tipos de dados correspondentes, consulte a Lista de tipos de dados.

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

O manifesto do Android precisa ter uma atividade que mostre a Política de Privacidade, que é a lógica do app sobre as permissões solicitadas, descrevendo como os dados do usuário são usados e processados.

Declare essa atividade para processar a intent ACTION_SHOW_PERMISSIONS_RATIONALE, em que ela é enviada ao app quando o usuário clica no link da 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

O HealthConnectClient é um ponto de entrada para a API Health Connect. Ele permite que o app use o repositório 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 de solicitações enviadas e respostas recebidas.

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

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

Em seguida, na atividade, confira se o Conexão Saúde está instalado usando getSdkStatus. Se estiver, consiga uma instância 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 do cliente, seu app precisa solicitar permissões ao usuário. Os usuários precisam ter permissão para conceder ou negar permissões a qualquer momento.

Para isso, crie um conjunto de permissões para os tipos de dados necessários. Primeiro, verifique se as permissões no conjunto foram declaradas 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 ver se o app já tem as permissões necessárias. Caso contrário, use createRequestPermissionResultContract para solicitar essas permissões. A tela de permissões do app Conexão Saúde vai aparecer.

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

Não presuma que as permissões sejam constantes, porque os usuários podem concedê-las ou revogá-las a qualquer momento. Seu app precisa verificar periodicamente as permissões concedidas e lidar com cenários em que a permissão é perdida.

Etapa 5: realizar operações

Agora que está tudo configurado, execute 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 na 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 seu 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
    }
}

Ler dados

É possível ler seus dados individualmente usando o 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.
    }
}

Também é possível 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
    }
}

Tutoriais em vídeo

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

Recursos

Confira os seguintes recursos que ajudarão no desenvolvimento mais tarde.

Próximas etapas

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