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 dell'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. Pertanto, non è necessaria alcuna configurazione.

Android 13 e versioni precedenti

Su Android 13 (livello API 33) e versioni precedenti, Connessione Salute non fa parte di il 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 Health Connect alla tua app

L'SDK Connessione Salute è responsabile dell'utilizzo dell'API Connessione Salute per inviare richieste durante l'esecuzione di operazioni sul datastore nell'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-alpha02"
  ...
}

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

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

Passaggio 3: configura l'app

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

Dichiara le autorizzazioni

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

Dichiara le autorizzazioni di lettura e scrittura sul file AndroidManifest.xml in base ai tipi di dati richiesti. Assicurati di utilizzare l'insieme di autorizzazioni ha richiesto l'accesso dopo che hai compilato il [modulo]{:.external}.

Connessione Salute utilizza il formato standard Dichiarazione delle autorizzazioni Android. Assegna le autorizzazioni con i tag <uses-permission>. Nidificarli all'interno <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 Elenco dei tipi di dati.

Mostra la finestra di dialogo delle norme sulla privacy della tua app

Il file manifest di Android deve contenere un'attività che mostri le norme sulla privacy della tua app, ovvero la motivazione alla base delle autorizzazioni richieste, descrivendo 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 alle 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 accesso all'API Health Connect. Consente all'app di utilizzare il datastore nell'app Connessione Salute. it 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 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. Se lo è, richiedi un HealthConnectClient istanza.

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 al utente. Gli utenti devono poter concedere o negare le autorizzazioni in qualsiasi momento.

A tale scopo, 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)
)

Usa getGrantedPermissions per verificare se la tua app dispone già sono 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 concedere o revocare in qualsiasi momento. La tua app deve verificare periodicamente le autorizzazioni concesse e gestire scenari in cui viene persa l'autorizzazione.

Passaggio 5: esegui le operazioni

Ora che è tutto impostato, esegui operazioni di lettura e scrittura nell'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 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
    }
}

Importante :Connessione Salute può leggere i dati fino a 30 giorni prima dell'ora in questione è stata concessa per la prima volta. Tuttavia, se un utente elimina la tua app, la cronologia delle autorizzazioni viene persa. Se l'utente reinstalla la tua app e concede di nuovo l'autorizzazione, Connessione Salute può leggere i dati fino a 30 giorni prima della nuova data di concessione.

Tutorial video

Inoltre, guarda questi video che spiegano in modo più approfondito le funzionalità di Connessione Salute. come best practice per ottenere un'integrazione senza problemi:

• Gestire le autorizzazioni in Connessione Salute
• Leggere e scrivere in Connessione Salute
• Suggerimenti per un'ottima integrazione di Connessione Salute

Risorse

Consulta le seguenti risorse che ti aiuteranno con lo 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 il API Health Connect.
• Dichiara l'utilizzo dei tipi di dati: in Play Console, dichiara l'accesso ai tipi di dati di Connessione Salute su cui la tua app legge e scrive.
• (Facoltativo) Esempio di codice e codelab di GitHub: consulta il repository di esempi di codice di GitHub e l'esercizio del codelab per iniziare.

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

Passaggi successivi

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

• Scrivere dati
• Leggi i dati non elaborati
• Leggere dati aggregati