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

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

Este guia mostra como começar a usar o 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 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, o app 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 configurar nada.

Android 13 e versões anteriores

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

Se você integrou seu app à Conexão Saúde no Android 13 e 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 em "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 Conexão Saúde ao app

O SDK do Conexão Saúde é responsável por usar a API Health Connect 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 no arquivo build.gradle do módulo:

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

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

A versão 1.1.0 e mais recentes do connect-client exigem o compileSdk = 36 e o Plug-in do Android para Gradle (AGP) versão 8.9.1 ou mais recente. Atualize o compileSdk no arquivo build.gradle do módulo:

android {
  compileSdk = 36
}

Usar recursos do canal de lançamento Canary

Para usar recursos no canal de lançamento Canário, modifique a versão do compileSdk no arquivo build.gradle do módulo:

android {
  compileSdkPreview = "CANARY"
}

Etapa 3: configurar o app

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

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

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

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

Declarar permissões

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

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

O manifesto do Android precisa ter uma atividade que mostre a Política de Privacidade do app, que é a justificativa para 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, que é enviada ao app quando o usuário clica no link da Política de Privacidade na tela de permissões da 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 Conexão Saúde. 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 de cliente, declare o nome do pacote da Conexão Saúde no manifesto do Android primeiro.

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

Em seguida, na atividade, verifique se o Conexão Saúde está instalado usando getSdkStatus. Se estiver, acesse uma instância do HealthConnectClient.

val availabilityStatus = HealthConnectClient.getSdkStatus(context)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
    Box(modifier = modifier.padding(16.dp), contentAlignment = Alignment.Center) {
        Text(
            text = "Health Connect is not available on this device. Please ensure it is installed and updated.",
            style = MaterialTheme.typography.bodyLarge,
            textAlign = TextAlign.Center
        )
    }
    return
}

val healthConnectClient = remember {
    if (availabilityStatus == HealthConnectClient.SDK_AVAILABLE) {
        HealthConnectClient.getOrCreate(context)
    } else {
        null
    }
}

Etapa 4: solicitar permissões do usuário

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(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 solicitá-las. Isso mostra a tela de permissões da Conexão Saúde. 
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.") }
    }
}
 Como os usuários podem conceder ou revogar permissões a qualquer momento, seu app precisa verificar as permissões sempre antes de usá-las e lidar com situações em que elas são perdidas.

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 do 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, ofereç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, realize operações de leitura e gravação no app.

Seus usuários podem usar outros apps que sincronizam dados com a Conexão Saúde para que seu app os acesse. Se o usuário ainda não tiver configurado esses apps para gravar na Conexão Saúde, use a API Matchmaking para conectar esses apps de forma integrada para os usuários.

Gravar dados

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

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

Em seguida, grave o registro usando insertRecords.

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

Ler dados

É possível ler seus dados individualmente usando readRecords.

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

Também é possível ler seus dados de forma 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
}

Tutoriais em vídeo

Assista a estes vídeos que explicam mais sobre os recursos do Conexão Saúde, além de diretrizes de práticas recomendadas para uma integração tranquila:

Recursos

Confira os recursos a seguir que ajudam no desenvolvimento posterior.

Próximas etapas

Confira os fluxos de trabalho comuns para saber como realizar operações no Conexão Saúde, como: