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 la tua 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 del framework. Pertanto, 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. Pertanto, 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ù visualizzata nella schermata Home. 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 oppure cerca Health Connect nelle 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:

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
  ...
} else {
  // Feature is not available
  ...
}

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 il datastore 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 Connessione Salute 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 è installato utilizzando getSdkStatus. In caso affermativo, ottieni un'istanza 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

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

// 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 verificare 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 Connessione Salute, anziché dall'interno della tua 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 scrivere su Health Connect puoi utilizzare l'API Matchmaking per collegare 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 stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET,
)

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

Leggi i dati

Puoi leggere i dati singolarmente utilizzando readRecords.

suspend fun readHeartRateByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (record in response.records) {
            // Process each record
        }
    } catch (e: Exception) {
        // Run error handling here
    }
}

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

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.

Passaggi successivi

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