Iniziare a usare Connessione Salute

Questa guida mostra come iniziare a utilizzare Connessione Salute nella tua app.

Passaggio 1: prepara l'app Connessione Salute

L'app Connessione Salute è responsabile della gestione di tutte le richieste inviate dalla tua applicazione tramite l'SDK Connessione Salute. Queste richieste includono l'archiviazione degli dati e la gestione del relativo accesso in lettura e scrittura.

L'accesso a Connessione Salute 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), Connessione Salute fa parte del framework Android. Questa versione di Connessione Salute è un modulo framework. Non c'è bisogno di nessuna configurazione.

Android 13 e versioni precedenti

Su Android 13 (livello API 33) e versioni precedenti, Connessione Salute non fa parte del framework Android. A questo punto, devi installare l'app Connessione Salute dal Google Play Store.

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

Apri l'app Connessione Salute

Connessione Salute non viene più visualizzata nella schermata Home per impostazione predefinita. Per aprire Connessione Salute, vai a Impostazioni > App > Connessione Salute o aggiungi Connessione Salute al menu Impostazioni rapide.

Inoltre, Connessione Salute richiede all'utente di attivare il blocco schermo con un PIN, una sequenza o una password in modo che i dati sanitari archiviati in Connessione Salute siano protetti da parti malintenzionate quando il dispositivo è bloccato. Per impostare un blocco schermo, vai a Impostazioni > Sicurezza > Blocco schermo.

Passaggio 2: aggiungi l'SDK Connessione Salute alla tua app

L'SDK Health Connect è responsabile dell'utilizzo dell'API Health Connect per inviare richieste relative all'esecuzione di operazioni con il datastore dell'app Connessione Salute.

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

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.1.0-alph10"
  ...
}

Per conoscere la versione più recente, consulta le release di Connessione Salute.

Passaggio 3: configura l'app

Le sezioni seguenti spiegano come configurare la tua app per l'integrazione con Connessione Salute.

Dichiara le autorizzazioni

L'accesso ai dati relativi a salute e fitness è sensibile. Connessione Salute implementa un livello di sicurezza per le operazioni di lettura e scrittura, garantendo la fiducia degli utenti.

In Play Console, dichiara l'accesso ai tipi di dati di Connessione Salute da cui la tua app legge e in cui scrive.

Nell'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 i quali hai dichiarato l'accesso in Play Console.

Connessione Salute utilizza il formato standard 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 file manifest Android deve avere un'attività che mostri le norme sulla privacy dell'app, ovvero la motivazione dell'app in merito alle autorizzazioni richieste, che descrive in che modo vengono utilizzati e gestiti i dati dell'utente.

Dichiara questa attività per gestire l'intent ACTION_SHOW_PERMISSIONS_RATIONALE in cui viene inviata all'app quando l'utente fa clic sul link Norme sulla privacy nella schermata delle autorizzazioni di Connessione Salute.

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

HealthConnectClient è un punto di accesso all'API Health Connect. Consente all'app di utilizzare il datastore nell'app Connessione Salute. Gestisce automaticamente la connessione al livello di archiviazione sottostante e gestisce tutte le 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 file manifest di Android.

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

Quindi, nella sezione Attività, controlla se Connessione Salute è installata 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, l'app deve richiedere le autorizzazioni all'utente. Gli utenti devono poter concedere o negare le autorizzazioni in qualsiasi momento.

Per farlo, crea un insieme di autorizzazioni per i tipi di dati richiesti. Assicurati innanzitutto che le autorizzazioni nell'insieme siano dichiarate nel file Android manifest.

// 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, usa createRequestPermissionResultContract per richiedere quelle autorizzazioni. Viene visualizzata la schermata delle autorizzazioni di Connessione Salute.

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

Non dare per scontato che le autorizzazioni siano costanti, perché gli utenti possono concederle o revocarle in qualsiasi momento. L'app deve controllare periodicamente le autorizzazioni concesse e gestire gli scenari in cui l'autorizzazione viene persa.

Passaggio 5: esegui le operazioni

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

Scrittura di dati

Struttura i dati in un record. Consulta l'elenco dei tipi di dati disponibili in Connessione Salute.

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET,
)

Quindi, scrivi il record utilizzando insertRecords.

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET,
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Lettura di dati

Puoi leggere i tuoi dati singolarmente utilizzando 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.
    }
}

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 Connessione Salute, nonché le linee guida sulle best practice per un'integrazione agevole:

Risorse

Consulta le seguenti risorse che ti saranno utili per lo sviluppo in un secondo momento.

Passaggi successivi

Consulta la sezione Fluidi di lavoro comuni per scoprire come eseguire operazioni in Connessione Salute, ad esempio: