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 il tuo inviate dall'applicazione tramite l'SDK Connessione Salute. Queste richieste includono l'archiviazione 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 spiegano come gestire diverse versioni recenti di Android.

Android 14

A partire da Android 14 (livello API 34), Connessione Salute fa parte di Framework Android. Questa versione di Connessione Salute è un modulo framework. Con non serve 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 eseguire la migrazione su Android 14, consulta Eseguire la migrazione da Android 13 ad Android 14.

Apri l'app Connessione Salute

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

Inoltre, Connessione Salute richiede all'utente di attivare il blocco schermo con Un PIN, una sequenza o una password affinché i dati sanitari vengano memorizzati nell'app Salute Connect è protetto da soggetti malintenzionati mentre 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 invia richieste per l'esecuzione di operazioni sul datastore nell'Integrità Collega app.

Aggiungi la dipendenza dell'SDK Connessione Salute 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.

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 livello di sicurezza per le operazioni di lettura e scrittura, mantenendo la fiducia degli utenti.

Dichiara le autorizzazioni di lettura e scrittura sul file AndroidManifest.xml in base a i 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 Android deve avere un'attività che mostri i norme sulla privacy, che sono la motivazione della tua app in merito alle autorizzazioni richieste. che descrivono la modalità di utilizzo e trattamento dei dati dell'utente.

Dichiara questa attività per gestire ACTION_SHOW_PERMISSIONS_RATIONALE l'intenzione di inviare il messaggio all'app quando l'utente fa clic sul 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 il nome del pacchetto Health Connect nel tuo Prima il 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. 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 essere autorizzati a concedere o negare le autorizzazioni in qualsiasi momento.

Per farlo, crea un insieme di autorizzazioni per i tipi di dati richiesti. Assicurati che che le autorizzazioni nel set vengano dichiarate prima nel file 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)
)

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

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:

Risorse

Consulta le seguenti risorse che ti aiutano a più avanti.

  • SDK Connessione Salute (disponibile su Jetpack): includi questo SDK nel tuo per utilizzare l'API Health Connect.
  • Riferimento API: dai un'occhiata al riferimento Jetpack per il API Health Connect.
  • Dichiarare l'utilizzo dei tipi di dati: in Play Console, dichiarare l'accesso ai tipi di dati di Connessione Salute che i tuoi l'app legge e scrive.
  • Esempio di codice GitHub e codelab facoltativi: guarda l'esempio di codice di GitHub repository e l'esercizio codelab per aiutarti a ottenere a iniziare.
di Gemini Advanced.

Passaggi successivi

Consulta Flussi di lavoro comuni per scoprire come eseguire operazioni in Connessione Salute come: