Iniziare a usare Connessione Salute

Questa guida ti 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 che invia tramite l'SDK Connessione Salute. Queste richieste includono l'archiviazione dei dati e la gestione del relativo accesso in lettura e scrittura.

L'accesso a Connessione Salute dipende dalla versione di Android installata sullo smartphone. Nelle sezioni che seguono viene spiegato 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. In questo modo, non è necessaria alcuna configurazione.

Android 13 e versioni precedenti

Su Android 13 (livello API 33) e versioni precedenti, Connessione Salute non fa parte del framework Android. 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 su Android 14, consulta l'articolo Eseguire la migrazione da Android 13 a 14.

Apri l'app Connessione Salute

Per impostazione predefinita, Connessione Salute non viene più visualizzata nella schermata Home. Per aprire Connessione Salute, vai a Impostazioni > App > Connessione Salute oppure 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 per proteggere i dati sanitari archiviati in Connessione Salute da soggetti malintenzionati mentre il dispositivo è bloccato. Per impostare un blocco schermo, vai a Impostazioni > Sicurezza > Blocco schermo.

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

L'SDK Health Connect è responsabile dell'utilizzo dell'API Health Connect per inviare richieste nell'esecuzione delle operazioni sul datastore nell'app Connessione Salute.

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

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

Consulta le release di Connessione Salute per avere la versione più recente.

Nota: l'SDK Health Connect supporta Android 8 (livello API 26) o versioni successive, mentre l'app Connessione Salute è compatibile solo con Android 9 (livello API 28) o versioni successive. Ciò significa che le app di terze parti possono supportare gli utenti con Android 8, ma solo gli utenti con Android 9 o versioni successive possono utilizzare Connessione Salute.

Passaggio 3: configura l'app

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

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

Dichiara le autorizzazioni di lettura e scrittura per il file AndroidManifest.xml in base ai tipi di dati richiesti. Assicurati di utilizzare l'insieme di autorizzazioni per le quali hai richiesto l'accesso dopo aver compilato il modulo.

Connessione Salute utilizza il formato standard Dichiarazione delle autorizzazioni Android. Assegna le autorizzazioni con i tag <uses-permission>. Nidificare i tag 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 tipi di dati corrispondenti, consulta Elenco dei tipi di dati.

Mostra 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 per le autorizzazioni richieste, che descrive come vengono utilizzati e gestiti i dati dell'utente.

Dichiara questa attività per gestire l'intent ACTION_SHOW_PERMISSIONS_RATIONALE a cui viene inviata all'app quando l'utente fa clic sul link delle 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>
...

Ottieni un client Connessione Salute

HealthConnectClient è un punto di ingresso 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 di Connessione Salute nel file manifest 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

Nota: alcuni dispositivi potrebbero non supportare Connessione Salute. Ad esempio, al momento sono supportati solo i dispositivi con Android 9 o versioni successive. Usa HealthConnectClient.isApiSupported per verificare se il dispositivo dell'utente è compatibile con Connessione Salute. Se restituisce false, l'app non deve chiedere all'utente di installare Connessione Salute.

Passaggio 4: richiedi le autorizzazioni all'utente

Dopo aver creato un'istanza client, l'app deve richiedere le autorizzazioni all'utente. Gli utenti devono essere autorizzati a concedere o negare le autorizzazioni in qualsiasi momento.

Per farlo, crea una serie di autorizzazioni per i tipi di dati richiesti. Assicurati prima che le autorizzazioni del set siano dichiarate nel file manifest 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 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 verificare periodicamente la presenza delle autorizzazioni concesse e gestire gli scenari in cui l'autorizzazione viene persa.

Passaggio 5: esegui le operazioni

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

Scrittura di dati

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

Importante: Connessione Salute può leggere i dati fino a 30 giorni prima della prima concessione dell'autorizzazione. Tuttavia, se un utente elimina la tua app, la cronologia delle autorizzazioni andrà persa. Se l'utente reinstalla l'app e concede di nuovo l'autorizzazione, Connessione Salute può leggere i dati fino a 30 giorni prima della nuova data in cui sono stati concessi.

Tutorial video

Guarda questi video che spiegano in modo più approfondito le funzionalità di Connessione Salute e linee guida sulle best practice per ottenere un'integrazione senza problemi:

• Gestire le autorizzazioni in Connessione Salute
• Leggere e scrivere in Connessione Salute
• Suggerimenti per una perfetta integrazione di Connessione Salute

Risorse

Consulta le seguenti risorse che ti aiuteranno con lo sviluppo più avanti.

• 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.
• Modulo Dichiarazione dello sviluppatore per le richieste API:utilizza questo modulo per richiedere l'accesso in lettura e scrittura ai tipi di dati. Per ulteriori dettagli, consulta Richiedere l'accesso ai tipi di dati di Connessione Salute.
• Esempio di codice e codelab GitHub facoltativo: consulta l'esempio di codice repository di GitHub e l'esercizio codelab per iniziare.

Nota: se richiedi un'altra richiesta nel caso in cui la tua app richieda nuovi tipi di dati, devi includere entrambi i tipi di dati ed escludere quelli che non ti servono più. Se devi solo rimuovere l'accesso a determinati tipi di dati, includi tutti quelli esistenti, ma escludi quelli che non ti servono più.

Passaggi successivi

Dai un'occhiata ai Flussi di lavoro comuni per scoprire come eseguire operazioni in Connessione Salute, tra cui:

• Scrivere dati
• Leggere dati non elaborati
• Leggere dati aggregati