A partire dal 2026, eseguiremo la transizione dalle API Google Fit. Per ulteriori informazioni sulla migrazione di Google Fit, consulta la guida alla migrazione.

Questa pagina è stata tradotta dall'API Cloud Translation.

Monitorare i passi

Connessione Salute fornisce un tipo di dati passi per registrare i conteggi dei passi utilizzando l'StepsRecord. I passi sono una misurazione fondamentale nel monitoraggio della salute e del fitness.

Lettura dei passi da dispositivo mobile

Con Android 14 (livello API 34) e l'estensione SDK versione 20 o successive, Connessione Salute fornisce il conteggio dei passi sul dispositivo. Se a un'app è stata concessa l'autorizzazione READ_STEPS, Connessione Salute inizia ad acquisire i passi dal dispositivo Android e gli utenti vedono i dati dei passi aggiunti automaticamente alle voci Passi di Connessione Salute.

Per verificare se il conteggio dei passi sul dispositivo è disponibile, devi verificare che il dispositivo esegua Android 14 (livello API 34) e abbia almeno l'estensione SDK versione 20. Puoi utilizzare il seguente codice:

val isStepTrackingAvailable =
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
        SdkExtensions.getExtensionVersion(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) >= 20

I passi da dispositivo mobile acquisiti da Connessione Salute hanno il valore DataOrigin impostato sul nome del pacchetto android. Se la tua app legge semplicemente i conteggi dei passi aggregati utilizzando aggregate e non filtra per DataOrigin, i passi sul dispositivo vengono inclusi automaticamente nel totale.

Se la tua app deve leggere i passi sul dispositivo o se mostra i dati dei passi suddivisi per applicazione o dispositivo di origine, puoi eseguire query per i record in cui DataOrigin è android. Se la tua app mostra l'attribuzione per i dati dei passi, devi attribuire i dati del pacchetto Android al dispositivo attuale. Puoi farlo utilizzando un'etichetta come"Il tuo smartphone", recuperando il nome del dispositivo con Settings.Global.getString(resolver, Settings.Global.DEVICE_NAME) o esaminando il campo Device nei metadati del record.

Il seguente esempio mostra come leggere i dati aggregati del conteggio dei passi da dispositivo mobile filtrando in base all'origine dati android:

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                dataOriginFilter = setOf(DataOrigin("android"))
            )
        )
        // 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
    }
}

Conteggio dei passi sul dispositivo

Approfondimento della funzionalità di conteggio dei passi sul dispositivo:

Utilizzo dei sensori: Connessione Salute utilizza il sensore TYPE_STEP_COUNTER di SensorManager. Questo sensore è ottimizzato per un basso consumo energetico, il che lo rende ideale per il monitoraggio continuo dei passi in background.
Granularità dei dati: per preservare la durata della batteria, i dati sui passi vengono in genere raggruppati e scritti nel database di Connessione Salute non più di una volta al minuto.
Attribuzione: come accennato in precedenza, tutti i passaggi registrati da questa funzionalità sul dispositivo vengono attribuiti al nome del pacchetto android in DataOrigin.
Attivazione: il meccanismo di conteggio dei passi sul dispositivo è attivo solo quando ad almeno un'applicazione sul dispositivo è stata concessa l'autorizzazione READ_STEPS in Connessione Salute.

Controllare la disponibilità di Connessione Salute

Prima di tentare di utilizzare Connessione Salute, la tua app deve verificare che Connessione Salute sia disponibile sul dispositivo dell'utente. Connessione Salute potrebbe non essere preinstallata su tutti i dispositivi o potrebbe essere disattivata. Puoi verificare la disponibilità utilizzando il metodo HealthConnectClient.getSdkStatus().

Come verificare la disponibilità di Connessione Salute

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata" // Or get from HealthConnectClient.DEFAULT_PROVIDER_PACKAGE_NAME
    val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)

    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
      // Health Connect is not available. Guide the user to install/enable it.
      // For example, show a dialog.
      return // early return as there is no viable integration
    }
    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
      // Health Connect is available but requires an update.
      // 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
    }
    // Health Connect is available, obtain a HealthConnectClient instance
    val healthConnectClient = HealthConnectClient.getOrCreate(context)
    // Issue operations with healthConnectClient
}

A seconda dello stato restituito da getSdkStatus(), puoi guidare l'utente a installare o aggiornare Connessione Salute dal Google Play Store, se necessario.

Autorizzazioni richieste

L'accesso ai passi è protetto dalle seguenti autorizzazioni:

android.permission.health.READ_STEPS
android.permission.health.WRITE_STEPS

Per aggiungere la funzionalità dei passi alla tua app, inizia richiedendo le autorizzazioni di scrittura per il tipo di dati Steps.

Ecco l'autorizzazione che devi dichiarare per poter scrivere i passi:

<application>
  <uses-permission
android:name="android.permission.health.WRITE_STEPS" />
...
</application>

Per leggere i passi, devi richiedere le seguenti autorizzazioni:

<application>
  <uses-permission
android:name="android.permission.health.READ_STEPS" />
...
</application>

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 insieme di autorizzazioni per i tipi di dati richiesti. Assicurati che le autorizzazioni nell'insieme siano dichiarate prima nel file manifest di Android.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  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)
  }
}

Poiché gli utenti possono concedere o revocare le autorizzazioni in qualsiasi momento, la tua app deve controllare periodicamente le autorizzazioni concesse e gestire gli scenari in cui l'autorizzazione viene revocata.

Informazioni incluse in un record Passi

Ogni StepsRecord contiene le seguenti informazioni:

count: il numero di passi effettuati nell'intervallo di tempo, come Long.
startTime: l'ora di inizio dell'intervallo di misurazione.
endTime: l'ora di fine dell'intervallo di misurazione.
startZoneOffset: l'offset della zona per l'ora di inizio.
endZoneOffset: l'offset della zona per l'ora di fine.

Aggregazioni supportate

Per StepsRecord sono disponibili i seguenti valori aggregati:

COUNT_TOTAL

Per StepsCadenceRecord sono disponibili i seguenti valori aggregati:

Esempio di utilizzo

Le sezioni riportate di seguito mostrano come leggere e scrivere i dati StepsRecord.

Scrittura dei dati sui passi

La tua app può scrivere i dati del conteggio dei passi inserendo istanze di StepsRecord. L'esempio seguente mostra come registrare 1000 passi effettuati da un utente:

suspend fun writeStepsData(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant,
    startZoneOffset: ZoneOffset,
    endZoneOffset: ZoneOffset
) {
    try {
        val stepsRecord = StepsRecord(
            startTime = startTime,
            startZoneOffset = startZoneOffset,
            endTime = endTime,
            endZoneOffset = endZoneOffset,
            count = 1000
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling
    }
}

Lettura dei dati aggregati

Il modo più comune per leggere i dati sui passi è aggregare il totale dei passi in un periodo di tempo. Il seguente esempio mostra come leggere il conteggio totale dei passi per un utente in un determinato intervallo di tempo:

suspend fun readStepsAggregate(
    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
    }
}

Lettura dei dati non elaborati

Il seguente esempio mostra come leggere i dati StepsRecord grezzi tra un'ora di inizio e di fine:

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