Iniziare a usare Connessione Salute

Questa guida è compatibile con la versione 1.1.0-alpha12 di Health Connect.

Questa guida mostra come iniziare a utilizzare Health Connect nella tua app.

Passaggio 1: prepara l'app Health Connect

L'app Health Connect è responsabile della gestione di tutte le richieste che l'applicazione invia tramite l'SDK Health Connect. Queste richieste includono l'archiviazione dei dati e la gestione dell'accesso in lettura e scrittura.

L'accesso a Health Connect dipende dalla versione di Android installata sullo smartphone. Le sezioni seguenti descrivono come gestire diverse versioni recenti di Android.

Android 14

A partire da Android 14 (livello API 34), Health Connect fa parte di Android Framework. Questa versione di Health Connect è un modulo framework. Di conseguenza, non è necessaria alcuna configurazione.

Android 13 e versioni precedenti

Su Android 13 (livello API 33) e versioni precedenti, Health Connect non fa parte di Android Framework. Di conseguenza, devi installare l' app Health Connect dal Google Play Store.

Se hai integrato la tua app con Health Connect su Android 13 e versioni precedenti e vuoi eseguire la migrazione su Android 14, consulta la sezione Eseguire la migrazione da Android 13 ad Android 14.

Apri l'app Health Connect

Per impostazione predefinita, Health Connect non viene più visualizzato nella schermata Home. Puoi aprire Health Connect tramite Impostazioni, anche se il percorso varia a seconda della versione di Android:

  • Su Android 14 e versioni successive: vai a Impostazioni > Sicurezza e privacy > Controlli della privacy > Health Connect oppure cerca Health Connect in Impostazioni.
  • Su Android 13 e versioni precedenti: vai a Impostazioni > App > Health Connect oppure aggiungi Health Connect al menu Impostazioni rapide.

Passaggio 2: aggiungi l'SDK Health Connect alla tua app

L'SDK Health Connect è responsabile dell'utilizzo dell'API Health Connect per inviare richieste di esecuzione di operazioni sull'archivio dati nell'app Health Connect.

Aggiungi la dipendenza dell'SDK Health Connect nel file build.gradle a livello di modulo:

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

Per l'ultima versione, consulta le release di Health Connect.

Utilizza le funzionalità del canale di rilascio Canary

Per utilizzare le funzionalità del canale di rilascio Canary, modifica la versione di compileSdk nel file build.gradle a livello di modulo:

android {
  compileSdkPreview = "CANARY"
}

Passaggio 3: configura la tua app

Le sezioni seguenti spiegano come configurare la tua app per l'integrazione con Health Connect.

Verifica le funzionalità disponibili

Quando vengono aggiunte nuove funzionalità a Health Connect, gli utenti potrebbero non aggiornare sempre la propria versione di Health Connect. L'API Feature Availability è un modo per verificare se una funzionalità di Health Connect è disponibile sul dispositivo dell'utente e decidere quale azione intraprendere.

La funzione principale per verificare la disponibilità delle funzionalità è getFeatureStatus(). Restituisce le costanti intere FEATURE_STATUS_AVAILABLE o 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
        )
    }
}

Dichiara le autorizzazioni

L'accesso ai dati di salute e fitness è sensibile. Health Connect implementa un livello di sicurezza per le operazioni di lettura e scrittura, mantenendo la fiducia degli utenti.

Nella tua app, dichiara le autorizzazioni di lettura e scrittura nel file AndroidManifest.xml in base ai tipi di dati richiesti, che devono corrispondere a quelli per cui hai dichiarato l'accesso in Play Console.

Health Connect utilizza il formato standard di dichiarazione delle autorizzazioni di Android. Assegna le autorizzazioni con i tag <uses-permission>. Inseriscili all'interno dei <manifest> tag.

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

Per l'elenco completo delle autorizzazioni e dei tipi di dati corrispondenti, consulta l'elenco dei tipi di dati.

Mostra la finestra di dialogo relativa alle norme sulla privacy della tua app

Il manifest di Android deve avere un'attività che mostri le norme sulla privacy della tua app, ovvero la logica delle autorizzazioni richieste, che descriva come vengono utilizzati e gestiti i dati dell'utente.

Dichiara questa attività per gestire l'intent ACTION_SHOW_PERMISSIONS_RATIONALE quando viene inviato all'app quando l'utente fa clic sul link Norme sulla privacy nella schermata delle autorizzazioni di Health Connect.

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

Ottieni un client Health Connect

HealthConnectClient è un punto di ingresso all'API Health Connect. Consente all'app di utilizzare l'archivio dati nell'app Health Connect. Gestisce automaticamente la connessione al livello di archiviazione sottostante e gestisce tutti gli IPC e la serializzazione delle richieste in uscita e delle risposte in entrata.

Per ottenere un'istanza client, dichiara prima il nome del pacchetto Health Connect nel manifest di Android.

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

Poi, nella tua attività, controlla se Health Connect è installato utilizzando getSdkStatus. In caso affermativo, ottieni un'istanza 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
    }
}

Passaggio 4: richiedi le autorizzazioni all'utente

Dopo aver creato un'istanza client, la tua app deve richiedere le autorizzazioni all'utente. Gli utenti devono essere autorizzati a concedere o negare le autorizzazioni in qualsiasi momento. A questo scopo, crea un set di autorizzazioni per i tipi di dati richiesti. Assicurati che le autorizzazioni nel set siano dichiarate prima nel manifest di Android. 

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
 Utilizza getGrantedPermissions per verificare se la tua app ha già le autorizzazioni richieste. In caso contrario, utilizza createRequestPermissionResultContract per richiedere queste autorizzazioni. Viene visualizzata la schermata delle autorizzazioni di Health Connect. 
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.") }
    }
}
 Poiché gli utenti possono concedere o revocare le autorizzazioni in qualsiasi momento, la tua app deve controllare le autorizzazioni ogni volta prima di utilizzarle e gestire gli scenari in cui l'autorizzazione viene persa.

Onboarding degli utenti

Molte app hanno un flusso di onboarding personalizzato, ad esempio l'educazione alle funzionalità o la richiesta del consenso dell'utente. Per consentire a Health Connect di avviare il flusso di onboarding, aggiungi quanto segue al manifest:

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

Gli utenti possono avviare la connessione alla tua app direttamente dall'app Health Connect, anziché dall'interno dell'app. Se la tua app richiede un'interazione aggiuntiva oltre alla concessione dell'autorizzazione per leggere o scrivere dati, fornisci un'attività di onboarding.

Tieni presente che l'attività di onboarding potrebbe essere avviata più di una volta, ad esempio se l'utente revoca in un secondo momento le autorizzazioni alla tua app e poi la ricollega.

Passaggio 5: esegui le operazioni

Ora che è tutto pronto, esegui le operazioni di lettura e scrittura nella tua app.

I tuoi utenti potrebbero utilizzare altre app che sincronizzano i dati con Health Connect a cui la tua app può accedere. Se l'utente non ha ancora configurato queste app per la scrittura su Health Connect, puoi utilizzare l'API Matchmaking per connettere facilmente queste app per i tuoi utenti.

Scrivi dati

Struttura i dati in un record. Consulta l'elenco dei tipi di dati disponibili in Health Connect.

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

Poi scrivi il record utilizzando 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))

Leggi i dati

Puoi leggere i dati singolarmente utilizzando readRecords.

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

Puoi anche leggere i tuoi dati in modo aggregato utilizzando 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
}

Tutorial video

Guarda questi video che spiegano di più sulle funzionalità di Health Connect, nonché le linee guida sulle best practice per ottenere un'integrazione senza problemi:

Risorse

Consulta le seguenti risorse che ti aiuteranno nello sviluppo in un secondo momento.

  • SDK Health Connect (disponibile su Jetpack): includi questo SDK nella tua applicazione per utilizzare l'API Health Connect.
  • Riferimento API: dai un'occhiata al riferimento Jetpack per l' API Health Connect.
  • Dichiara l'utilizzo dei tipi di dati: in Play Console, dichiara l'accesso ai tipi di dati di Health Connect che la tua app legge e scrive.
  • Esempio di codice e codelab GitHub facoltativi: consulta il repository di esempi di codice GitHub e l'esercizio del codelab per iniziare.

Passaggi successivi

Consulta la sezione Flussi di lavoro comuni per scoprire come eseguire operazioni in Health Connect, ad esempio: