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 inviate dalla tua applicazione 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 del framework Android. Questa versione di Health Connect è un modulo framework. In questo modo, non è necessaria alcuna configurazione.

Android 13 e versioni precedenti

Su Android 13 (livello API 33) e versioni precedenti, Health Connect non fa parte del framework Android. Per farlo, 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 Eseguire la migrazione da Android 13 ad Android 14.

Apri l'app Health Connect.

Health Connect non viene più visualizzato nella schermata Home per impostazione predefinita. Puoi aprire Health Connect tramite le 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 per la privacy > Health Connect o cerca Health Connect in Impostazioni.
  • Su Android 13 e versioni precedenti:vai a Impostazioni > App > Health Connect o aggiungi Health Connect al menu Impostazioni rapide.

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

L'SDK di Health Connect è responsabile dell'utilizzo dell'API Health Connect per inviare richieste durante l'esecuzione di operazioni sul datastore 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.

Utilizzare le funzionalità del canale di rilascio Canary

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

android {
  compileSdkPreview = "CANARY"
}

Passaggio 3: configura l'app

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

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

Dichiarare le autorizzazioni

L'accesso ai dati relativi a 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 Android. Assegna le autorizzazioni con i tag <uses-permission>. Nidificali all'interno dei tag <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>

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

Mostrare la finestra di dialogo delle norme sulla privacy dell'app

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

Dichiara questa attività per gestire l'intent ACTION_SHOW_PERMISSIONS_RATIONALE inviato all'app quando l'utente fa clic sul link all'informativa 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>
...

Ottenere un client Health Connect

HealthConnectClient è un punto di accesso 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 di 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 Activity, controlla se Health Connect è installata utilizzando getSdkStatus. In caso affermativo, ottieni un'istanza di 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 poter 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.

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

Utilizza getGrantedPermissions per verificare se alla tua app sono già state concesse le autorizzazioni richieste. In caso contrario, utilizza createRequestPermissionResultContract per richiedere queste autorizzazioni. Viene visualizzata la schermata delle autorizzazioni di Health Connect.

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

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

Eseguire l'onboarding degli utenti

Molte app hanno un flusso di onboarding personalizzato, ad esempio l'apprendimento delle 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 Connessione Salute, anziché dall'interno della tua app. Se la tua app richiede un'interazione aggiuntiva oltre all'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 per la tua app e poi la ricollega.

Passaggio 5: esegui le operazioni

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

I tuoi utenti potrebbero utilizzare altre app che sincronizzano i dati con Health Connect per consentire alla tua app di accedervi. Se l'utente non ha ancora configurato queste app per scrivere su Health Connect ancora, 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))

Quindi scrivi il tuo 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))

Lettura di dati

Puoi leggere i tuoi dati individualmente 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 e sulle linee guida per le best practice per ottenere un'integrazione ottimale:

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:consulta il riferimento Jetpack per l'API Health Connect.
  • Dichiarare 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 dell'esempio di codice GitHub e l'esercizio del codelab per iniziare.

Passaggi successivi

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