Gestione dei dati del sonno con Samsung Health e Health Connect

Per ulteriori informazioni su Samsung Health e Health Connect, vedere Accesso ai dati Samsung Health tramite Health Connect..

Sincronizzazione dei dati del sonno con Health Connect

La piattaforma Health Connect raccoglie dati relativi alla salute e li sincronizza con Samsung Health, consentendoti di utilizzarli nelle tue applicazioni.

I dati sul sonno vengono creati su uno smartwatch quando l’utente si sveglia. I dati devono essere trasferiti a un dispositivo mobile accoppiato per l’elaborazione. Il trasferimento dei dati viene avviato quando il dispositivo mobile è connesso. I dati elaborati creano un registro del sonno, che Samsung Health sincronizza con Health Connect. Le attività di trasferimento e sincronizzazione possono essere ritardate, a seconda della disponibilità del processore.

Prerequisiti

L’implementazione di funzionalità che utilizzano dati sanitari in un’applicazione richiede la libreria Health Connect, HealthConnectionCliente autorizzazioni.

Aggiungi le dipendenze della libreria API Health Connect

Per utilizzare le funzionalità dell’API Health Connect nella tua applicazione:

dependencies {
    // Add Health Connect library
    implementation "androidx.health.connect:connect-client:1.1.0-alpha06"
}

Configura il file “AndroidManifest.xml”.

• Dichiarare le autorizzazioni richieste:

<uses-permission android:name="android.permission.health.WRITE_SLEEP"/>
<uses-permission android:name="android.permission.health.READ_SLEEP" />

• Aggiungere <intent-filter> nel <activity> sezione:

<intent-filter>
	<action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
</intent-filter>

• Aggiungi il <activity-alias> elemento richiesto in Android 14:

<activity-alias
	android:name="ViewPermissionUsageActivity"
    android:exported="true"
    android:targetActivity=".MainMenuActivity"
    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>

• Aggiungere <uses-permission> elementi:

<uses-permission android:name="android.permission.health.WRITE_SLEEP"/>
<uses-permission android:name="android.permission.health.READ_SLEEP" />

• Aggiungi il <queries> elemento:

<queries>
	<package android:name="com.google.android.apps.healthdata" />
</queries>

Tieni presente che in questa applicazione utilizziamo anche:

  <package android:name="com.sec.android.app.shealth" />

L’aggiunta di questo elemento è necessaria poiché apriremo l’app Samsung Health. Tuttavia, se sei interessato a utilizzare solo l’API Health Connect, la parte precedente non è obbligatoria.

Ottieni un client HealthConnect

IL HealthConnectClient La classe è un punto di ingresso all’API Health Connect. 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.

È buona norma assicurarsi che il dispositivo che esegue l’applicazione supporti effettivamente la libreria API Health Connect. La libreria è disponibile solo quando sul dispositivo è installata l’applicazione Health Connect.

NotaAndroid 14 Health Connect fa parte del sistema ed è installato per impostazione predefinita. Tuttavia nelle versioni precedenti è necessario verificare se Health Connect è presente sul dispositivo.

Verifica la disponibilità di Health Connect. Se manca, visualizza un errore e reindirizza l’utente all’app store se è possibile l’installazione dell’app:

when (HealthConnectClient.getSdkStatus(this)) {
  HealthConnectClient.SDK_UNAVAILABLE -> {
  // Error message
  }
  HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED -> {
  // Error message
  try {
  	startActivity(
      	Intent(
          	Intent.ACTION_VIEW,
          	Uri.parse("market://details?id=com.google.android.apps.healthdata"),
      	),
  	)
  } catch (e: ActivityNotFoundException) {
  	startActivity(
      	Intent(
          	Intent.ACTION_VIEW,
          	Uri.parse("https://play.google.com/store/apps/details?id=com.google.android.apps.healthdata"),
      	),
  	)
  }
}

Se Health Connect è disponibile, ottieni un HealthConnectClient istanza di classe:

private val healthConnectClient by lazy { HealthConnectClient.getOrCreate(context) }

Richiedi i permessi utente

L’applicazione deve richiedere l’autorizzazione dell’utente per utilizzare i propri dati sanitari.

• Crea un set di autorizzazioni per i tipi di dati richiesti. Le autorizzazioni devono corrispondere a quelle definite nel file AndroidManifest.xml file.

  val permissions = setOf(
    HealthPermission.getWritePermission(SleepSessionRecord::class),
    HealthPermission.getReadPermission(SleepSessionRecord::class),
)

• Controlla se l’utente ha concesso le autorizzazioni richieste:

suspend fun hasAllPermissions(): Boolean {
	if (HealthConnectClient.sdkStatus(context) != HealthConnectClient.SDK_AVAILABLE) {
    	return false
    }
    return healthConnectClient.permissionController.getGrantedPermissions()
		.containsAll(permissions)
}

• In caso contrario, avvia la richiesta di autorizzazione:

if (!healthConnectManager.hasAllPermissions()) {
	requestPermissions.launch(healthConnectManager.permissions)
}

• Crea la richiesta di autorizzazione:

private fun createRequestPermissionsObject() {
	requestPermissions =
		registerForActivityResult(healthConnectManager.requestPermissionActivityContract) { granted ->
  			lifecycleScope.launch {
  				if (granted.isNotEmpty() && healthConnectManager.hasAllPermissions()) {
  					runOnUiThread {
						Toast.makeText(
                        	this@MainMenuActivity,
                         	R.string.permission_granted,
                            Toast.LENGTH_SHORT,
                          ) .show()
					}
				} else {
                	runOnUiThread {
                    	AlertDialog.Builder(this@MainMenuActivity)
                    	.setMessage(R.string.permissions_not_granted)
                  		.setPositiveButton(R.string.ok, null)
                		.show()
           		}
  			}
    	}
	}
}

Recupera i dati del sonno da Health Connect

Nell’applicazione di esempio, per visualizzare i dati sul sonno, selezionare una data e toccare LEGGI I DATI. Viene visualizzato un elenco delle sessioni di sonno per quel giorno. Quando selezioni una sessione, l’applicazione recupera e visualizza le informazioni sulla fase del sonno da Health Connect.

Per recuperare e visualizzare i dati della sessione di sonno:

• Definisci l’intervallo di tempo desiderato e invialo a Health Connect Manager. Poiché una sessione di sonno può iniziare il giorno prima della data selezionata, assicurati che l’applicazione recuperi anche le sessioni di sonno del giorno precedente e successivamente ignori le sessioni che non corrispondono all’intervallo di tempo desiderato.

val startTime = chosenDay.minusDays(1).atStartOfDay(ZoneId.systemDefault()).toInstant()
val endTime = startTime.plus(2, ChronoUnit.DAYS).minus(1, ChronoUnit.MILLIS)
val sleepSessions = healthConnectManager.readSleepSessionRecords(
	startTime,
    endTime,
)

• Recupera l’elenco dei record delle sessioni di sonno in Health Connect Manager. Crea un oggetto ReadRecordsRequest e invialo a Health Connect:

val request = ReadRecordsRequest(
	recordType = SleepSessionRecord::class,
    timeRangeFilter = TimeRangeFilter.between(start, end),
)
val response = healthConnectClient.readRecords(request)
return response.records

• Visualizza i record in un ListView nella schermata dell’applicazione:

for (session in sleepSessions) {
	sleepSessionRanges.add(TimeRange.between(session.startTime, session.endTime))
    val sessionStart = session.startTime.atZone(ZoneId.systemDefault()).format(
    	DateTimeFormatter.ISO_LOCAL_TIME,
  	)
    val sessionEnd = session.endTime.atZone(ZoneId.systemDefault()).format(
    	DateTimeFormatter.ISO_LOCAL_TIME,
    )
    sleepStagesLists.add(session.stages)
    sleepSessionsAdapter.add("Start: $sessionStart\t\tEnd: $sessionEnd GMT ${session.startZoneOffset}")
}

• Quando viene selezionata una sessione, vengono visualizzati i dettagli della fase del sonno:

for (stage in sleepStagesLists[sleepSessionIndex]) {
	val stageStart = stage.startTime.atZone(ZoneId.systemDefault()).format(
    	DateTimeFormatter.ISO_LOCAL_TIME,
    )
    val stageEnd = stage.endTime.atZone(ZoneId.systemDefault()).format(
    	DateTimeFormatter.ISO_LOCAL_TIME,
    )
    val stageName = HealthConnectManager.enumToStageMap.getValue(stage.stage)
    sleepStagesAdapter.add("$stageStart\t-\t$stageEnd\t\t$stageName")
}

NotaSebbene i dati vengano inseriti e archiviati in Health Connect nell’ora UTC con differenza di fuso orario, i dati recuperati da Health Connect vengono visualizzati nell’ora locale.

Puoi estrarre i dati sul sonno di Health Connect da qualsiasi fonte, inclusi i dati di Galaxy Watch. La figura seguente mostra una sessione di sonno in Samsung Health e gli stessi dati presentati nell’applicazione di esempio.

Dati sul sonno in Samsung Health e applicazione di esempio

Crea e inserisci i dati della sessione di sonno

Health Connect non solo consente di leggere i dati del sonno raccolti tramite Samsung Health, ma consente anche di inserire manualmente i dati del sonno che possono essere sincronizzati con Samsung Health.

Per inserire manualmente i dati del sonno in Health Connect, è necessario preparare sia una sessione di sonno che i dati sulle fasi del sonno.
Una sessione è un intervallo di tempo durante il quale un utente esegue un’attività, ad esempio il sonno. Per preparare una sessione, è necessario conoscerne l’ora di inizio e di fine. Nell’applicazione di esempio viene implementata anche una differenza di fuso orario facoltativa, poiché i dati nel database Health Connect sono archiviati in UTC.

Se l’ora e il minuto di inizio della sessione sono successivi all’ora e al minuto di fine, la sessione viene interpretata come iniziata il giorno precedente. Nella figura seguente, si interpreta che la sessione è iniziata alle 22:00 del 10-12-2023 e terminata alle 06:00 del 11-12-2023.

Durata della sessione di sonno

Nella parte successiva dell’applicazione è possibile aggiungere fasi del sonno all’interno della sessione di sonno. Per aggiungere una fase del sonno, definirne l’ora di inizio, l’ora di fine e il nome. Per compatibilità con Samsung Health, utilizzare i nomi delle fasi del sonno Sveglio, Leggero, REME Profondo. Ogni fase del sonno definita è visibile nell’elenco. Idealmente, le fasi del sonno coprono l’intera sessione di sonno, ma questo non è un requisito per la sincronizzazione con Samsung Health.

Creazione delle fasi del sonno

Per creare e aggiungere una sessione di sonno a Connessione Salute:

• Verifica che l’utente abbia concesso le autorizzazioni necessarie:

if (!healthConnectManager.hasAllPermissions()) {
	showDialogInfo(R.string.permissions_not_granted_api_call)
    return@launch
}

• Definire l’ora di inizio e di fine della sessione di sonno:

val startTime = sleepSessionTimeRange.startDateTimeMillis
val endTime = sleepSessionTimeRange.endDateTimeMillis
val timezoneOffset = dateOfSleepEnd.offset

• Per aggiungere dati sulle fasi del sonno alla sessione, crea un record SleepStage per ciascuna fase

var sleepStagesList: ArrayList<SleepSessionRecord.Stage>

val sleepStage = SleepSessionRecord.Stage(
startTime = sleepStageStart,
                endTime = sleepStageEnd,
                stage = HealthConnectManager.stageToEnumMap.getValue(
                    activitySleepStagesBinding.spinStage.selectedItem.toString(),
                ),
)
sleepStagesList.add(sleepStage)

• Nel gestore Health Connect, crea un record della sessione di sonno e includi l’elenco delle fasi del sonno:

suspend fun insertSleepSessionRecord(
	sleepStartTime: Instant,
    sleepEndTime: Instant,
    timezoneOffset: ZoneOffset,
    stages: ArrayList<SleepSessionRecord.Stage>,
): Boolean {
	var wasInsertSuccessful = false
    try {
    	val sleepSessionRecord = SleepSessionRecord(
        	sleepStartTime,
            timezoneOffset,
            sleepEndTime,
            timezoneOffset,
            "Sleep Record sample",
            "This is a sleep record sample recorded by SleepRecorder app",
            stages,
        )

• Inserisci il record della sessione di sonno in Health Connect:

var wasInsertSuccessful = false
try {
    wasInsertSuccessful =
        healthConnectClient.insertRecords(listOf(sleepSessionRecord)).recordIdsList.isNotEmpty()
} catch (e: Exception) {
    Log.i(APP_TAG, "Error inserting record: " + e.message)
}

La sessione di sonno è ora in Health Connect e visibile in Samsung Health dopo la sincronizzazione dei dati. In Samsung Health, vai alla schermata “Sospensione”. La sessione di sonno inserita può essere rivista lì con visualizzazioni e analisi proprio come qualsiasi altra sessione di sonno, come quelle monitorate su un Galaxy Watch. Di seguito è riportata una sessione di sonno dall’applicazione di esempio:

Sessione di sonno

Conclusione

Questo blog ha dimostrato come sviluppare un’applicazione che recupera dati e inserisce dati in Health Connect, rendendoli visibili nell’applicazione Samsung Health dopo la sincronizzazione dei dati.