Este guia é compatível com a versão 1.1.0-alpha12 do Health Connect.
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
A partir do Android 14 (nível 34 da API), 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. Para isso, 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 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
O app Conexão Saúde não aparece mais na tela inicial por padrão. Para abrir a Conexão Saúde, acesse Configurações > Apps > Conexão Saúde ou adicione a 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 no app fiquem protegidos contra partes mal-intencionadas enquanto o dispositivo estiver bloqueado. Para definir um bloqueio de tela, acesse Configurações > Segurança > Bloqueio de tela.
Etapa 2: adicionar o SDK do app Conexão Saúde ao seu app
O SDK da Conexão Saúde é responsável por usar a API Conexão Saúde 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.1.0-alpha11"
...
}
Consulte as versões da 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 o Health Connect.
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.
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 conferir 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
O manifesto do Android precisa ter uma atividade que mostre a Política de Privacidade do app, que é o motivo das 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
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>
...
Conseguir um cliente da Conexão Saúde
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 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.
<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 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 ao usuário
Depois de criar uma instância de cliente, o 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 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 conferir 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 da Conexão Saúde será exibida.
// 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 são constantes, porque os usuários podem conceder ou revogar elas a qualquer momento. O 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 tudo está pronto, realize operações de leitura e gravação no 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 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
.
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 forma 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 estes vídeos que explicam mais sobre os recursos da Conexão Saúde, além de 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 do Conexão Saúde (disponível no Jetpack): inclua esse SDK no app para usar a API do Conexão Saúde.
- Referência da API:confira a referência do Jetpack para a API Health Connect.
- Declarar o uso de tipos de dados:no Play Console, declare o acesso aos tipos de dados da Conexão Saúde que o 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 codelab para começar.
Próximas etapas
Confira os fluxos de trabalho comuns para aprender a realizar operações na Conexão Saúde, como: