Este guia é compatível com a versão 1.1.0-alpha12 do app Conexão Saúde.
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. Portanto, 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, o app Conexão Saúde não faz parte do framework do Android. Portanto, 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.
Abrir 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 dependendo da 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 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 da Conexão Saúde ao seu app
O SDK da Conexão Saúde é responsável por usar a API Health Connect para enviar solicitações na execução de operações no armazenamento de dados do app Conexão Saúde.
Adicione a dependência do SDK da Conexão Saúde no arquivo build.gradle do módulo:
dependencies {
...
implementation "androidx.health.connect:connect-client:1.2.0-alpha04"
...
}
Consulte as versões da Conexão Saúde para conferir a versão mais recente.
Usar recursos do canal de lançamento Canary
Para usar os recursos no canal de lançamento Canary, modifique a versão do compileSdk no arquivo build.gradle do módulo:
android {
compileSdkPreview = "CANARY"
}
Etapa 3: configurar seu app
As seções a seguir explicam como configurar seu app para integrar à 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 dela. A API Feature Availability é uma maneira de verificar se um recurso da 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(). Ela retorna constantes inteiras FEATURE_STATUS_AVAILABLE ou FEATURE_STATUS_UNAVAILABLE:
@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 ) } }
Declarar permissões
O acesso a dados de condicionamento físico e saúde é 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.
No seu app, declare 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 <uses-permission> tags. Aninhe-as 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 seu app
O manifesto do Android precisa ter uma atividade que mostre a Política de Privacidade do seu app, que é a justificativa do app para as 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, que é enviada ao app quando o usuário clica no link 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 do 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 acessar uma instância de 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 a Conexão Saúde está instalada
usando getSdkStatus. Se estiver, acesse uma instância 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 poder conceder ou negar permissões 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 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 solicitá-las. 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 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 o 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 dentro do seu app. Se o app exigir alguma interação adicional além de receber 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á definido, realize operações de leitura e gravação no seu app.
Seus usuários podem usar outros apps que sincronizam dados com a Conexão Saúde para que seu app acesse. Se o usuário ainda não configurou esses apps para gravar na Conexão Saúde, você pode usar a API Matchmaking para conectar esses apps aos usuários.
Gravar dados
Estruture seus dados em um registro. Confira a lista de tipos de dados disponíveis na 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( device = Device(type = Device.TYPE_WATCH), recordingMethod = Metadata.RECORDING_METHOD_AUTOMATICALLY_RECORDED ) ) 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( device = Device(type = Device.TYPE_WATCH), recordingMethod = Metadata.RECORDING_METHOD_AUTOMATICALLY_RECORDED ) ) healthConnectClient.insertRecords(listOf(stepsRecord))
Ler dados
Você pode ler seus dados individualmente usando readRecords.
val response = healthConnectClient.readRecords( ReadRecordsRequest( HeartRateRecord::class, timeRangeFilter = TimeRangeFilter.between(startTime, endTime) ) ) response.records.forEach { record -> /* Process records */ }
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 }
Tutoriais em vídeo
Assista a estes vídeos que explicam mais sobre os recursos da Conexão Saúde, bem como 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 da Conexão Saúde
Recursos
Confira os recursos a seguir que ajudam no desenvolvimento mais tarde.
- SDK da Conexão Saúde (disponível no Jetpack): inclua este SDK no seu app para usar a API do Conexão Saúde.
- Referência da API: confira a referência do Jetpack para a API do Conexão Saúde.
- Declarar o uso de tipos de dados: no Play Console, declare o acesso aos tipos de dados da 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.
Próximas etapas
Confira Fluxos de trabalho comuns para aprender a realizar operações na Conexão Saúde, como: