API Health Platform

Nota: l'API Health Platform versione 1 è supportata e compatibile con Samsung Health e supporta solo alcuni dispositivi Samsung. L'API Health Platform versione 1 è deprecata dall'11 maggio 2022. È stato sostituito da Connessione Salute. Connessione Salute è un'API e una piattaforma che unifica i dati di più dispositivi e app, tra cui Samsung Health, in un unico ecosistema. Fornisce inoltre un'unica interfaccia per leggere e scrivere i dati relativi alla salute e all'attività fisica dell'utente. Per ulteriori informazioni sulla piattaforma, consulta la documentazione di Connessione Salute. Consulta la pagina Inizia per l'integrazione con l'API.

L'API Health Platform è un'API Android che fornisce agli sviluppatori un'unica interfaccia per leggere, scrivere e condividere i dati storici di salute, benessere e fitness di un utente. Con Health Platform, gli utenti hanno il controllo dei propri dati. Gli utenti controllano quali app hanno accesso in lettura o scrittura a diversi tipi di dati. I tipi di dati dell'API Health Platform includono altezza, frequenza cardiaca e altri ancora.

L'API Health Platform offre agli utenti un meccanismo di archiviazione e condivisione che consente loro di selezionare le app che possono accedere e visualizzare i dati personali relativi a salute, fitness e benessere. In questo modo, gli sviluppatori di app possono mostrare agli utenti una visione più completa dello stato di salute degli utenti e monitorare in modo più efficace i loro dati.

Il software Developer Kit dell'API Health Platform fornisce agli sviluppatori di app Android tutto il necessario per consentire l'accesso ai dati su salute e benessere di un utente su dispositivi Samsung selezionati e consente alle app di eseguire operazioni collettive, come l'inserimento, l'eliminazione e la lettura di dati.

Nota: vedi l'esempio di Health Platform su GitHub per un esempio completo di utilizzo dell'API Health Platform.

Inizia

Quando utilizzi Health Platform, tieni presente quanto segue:

• Le app client devono ottenere dall'utente autorizzazioni granulari per l'accesso in lettura o scrittura.
• L'utente può negare o revocare le autorizzazioni in qualsiasi momento.
• L'API Health Platform supporta solo dispositivi Samsung selezionati.
• HealthDataClient è il client di Health Platform e un punto di ingresso per questa piattaforma.

L'immagine seguente mostra i passaggi di integrazione necessari che gli sviluppatori devono seguire:

Rilascia file

La release Health Platform V1 contiene quanto segue:

• SDK client: includi questo SDK nell'applicazione per utilizzare l'API Health Platform. L'SDK è un repository Maven che puoi includere direttamente nei file di build Gradle della tua applicazione.

Installa Health Platform

Installa Health Platform seguendo questi passaggi:

Nel file build.gradle principale dell'app, aggiungi il repository, come mostrato nell'esempio seguente:

allprojects {
    ...
    repositories {
        ...
        google()
    }
}

Aggiungi una dipendenza all'SDK Health Platform nel file build.gradle del modulo, come mostrato nell'esempio seguente:

dependencies {
   …
  implementation 'com.google.android.libraries.healthdata:health-data-api:1.0.0-alpha01'
}

Dati

Health Platform archivia e struttura i dati relativi a salute e fitness. Prende inoltre in considerazione le differenze fondamentali tra il modo in cui vengono misurati i dati di tipi diversi. Ad esempio, la misurazione della frequenza cardiaca viene eseguita immediatamente, ma il conteggio dei passi viene rilevato in un determinato periodo di tempo.

Di seguito è riportata una panoramica degli elementi principali di Health Platform e delle rispettive differenze:

• RawData: un record di dati e misurazioni.
• DataType: uno specifico per i tipi comuni di dati relativi a salute e fitness, come frequenza cardiaca, grasso corporeo o temperatura corporea, e i relativi formati, ad esempio campi, di sola lettura o facoltativo.
• SampleData: un oggetto RawData che rappresenta una misurazione istantanea, come la frequenza cardiaca, la pressione sanguigna o la velocità di corsa.
• IntervalData: un oggetto RawData che è una misurazione cumulativa eseguita in un determinato periodo di tempo, ad esempio il numero di passi effettuati, la distanza percorsa o le calorie bruciate.
• SeriesData: un oggetto RawData che incapsula una sequenza di misurazioni in un periodo di tempo. SeriesData è particolarmente adatto per dati di sensori ad alta frequenza, come campioni continui di battito cardiaco durante una sessione di attività.

Ognuna delle tre classi RawData corrisponde a una specifica sottoclasse di DataType: SampleData, IntervalData e SeriesData corrispondono rispettivamente a SampleDataType, IntervalDataType e SeriesDataType.

A ogni oggetto RawData viene assegnato un identificatore univoco (UID) dalla piattaforma Salute quando viene inserito. Puoi utilizzare questo UID per fare riferimento a un oggetto RawData specifico nelle richieste di lettura, aggiornamento o eliminazione.

Tipi di dati

Health Platform include una vasta gamma di tipi di dati comunemente utilizzati nelle app per la salute e l'attività fisica. I dati archiviati con i tipi di dati disponibili forniscono agli utenti una visione completa dei loro dati storici su salute, fitness e benessere, fornendo informazioni sulle loro attività quotidiane.

Ogni tipo di dati viene definito dal relativo formato dei dati, che include quanto segue:

• Campi:campi specifici o generici associati al tipo di dati. Ad esempio, il tipo di dati di saturazione dell'ossigeno nel sangue (SpO2) include campi come Titolo, Note e Percentuale.
• Tipo: long, double, string o enum.
• Attributo: intervallo di sola lettura, obbligatorio, facoltativo o di convalida.

Elenco dei tipi di dati

Ottieni il massimo da Health Platform comprendendo i tipi di dati disponibili. Health Platform supporta i tipi di dati mostrati nella seguente tabella. I tipi di dati sono organizzati in base al loro formato: campione, intervallo o serie.

SampleData tipi:

DataType.BasalMetabolicRateDataType	BASAL_METABOLIC_RATE	Obbligatorio
DataType.BloodGlucoseDataType	BLOOD_GLUCOSE	Obbligatorio e facoltativo
DataType.BloodPressureDataType	BLOOD_PRESSURE	Obbligatorio e facoltativo
DataType.BodyFatDataType	BODY_FAT	Obbligatorio
DataType.BodyTemperatureDataType	BODY_TEMPERATURE	Obbligatorio e facoltativo
DataType.BoneMassDataType	BONE_MASS	Obbligatorio
DataType.CervicalMucusDataType	CERVICAL_MUCUS	Facoltativo
DataType.CervicalPositionDataType	CERVICAL_POSITION	Facoltativo
DataType.CyclingPedalingCadenceDataType	CYCLING_PEDALING_CADENCE	Obbligatorio
DataType.DateOfBirthDataType	DATE_OF_BIRTH	Solo lettura
DataType.GenderDataType	GENDER	Solo lettura
DataType.HeartRateDataType	HEART_RATE	Obbligatorio
DataType.HeightDataType	HEIGHT	Obbligatorio
DataType.HipCircumferenceDataType	HIP_CIRCUMFERENCE	Obbligatorio
DataType.HrvDifferentialIndexDataType	HRV_DIFFERENTIAL_INDEX	Obbligatorio
DataType.HrvRmssdDataType	HRV_RMSSD	Obbligatorio
DataType.HrvSDataType	HRV_S	Obbligatorio
DataType.HrvSd2DataType	HRV_SD2	Obbligatorio
DataType.HrvSdannDataType	HRV_SDANN	Obbligatorio
DataType.HrvSdnnDataType	HRV_SDNN	Obbligatorio
DataType.HrvSdnnIndexDataType	HRV_SDNN_INDEX	Obbligatorio
DataType.HrvSdnnIndexDataType	HRV_SDNN_INDEX	Obbligatorio
DataType.HrvSdsdDataType	HRV_SDSD	Obbligatorio
DataType.HrvTinnDataType	HRV_TINN	Obbligatorio
DataType.LeanBodyMassDataType	LEAN_BODY_MASS	Obbligatorio
DataType.LocationDataType	LOCATION	Obbligatorio
DataType.MenstruationDataType	MENSTRUATION	Facoltativo
DataType.OvulationTestDataType	OVULATION_TEST	Obbligatorio
DataType.OxygenSaturationDataType	OXYGEN_SATURATION	Obbligatorio
DataType.PaceDataType	PACE	Obbligatorio
DataType.PowerDataType	POWER	Obbligatorio
DataType.RespiratoryRateDataType	RESPIRATORY_RATE	Obbligatorio
DataType.RestingHeartRateDataType	RESTING_HEART_RATE	Obbligatorio
DataType.SexualActivityDataType	SEXUAL_ACTIVITY	Obbligatorio
DataType.SpeedDataType	SPEED	Obbligatorio
DataType.StepsCadenceDataType	STEPS_CADENCE	Obbligatorio
DataType.Vo2MaxDataType	VO2_MAX	Obbligatorio e facoltativo
DataType.WaistCircumferenceDataType	WAIST_CIRCUMFERENCE	Obbligatorio
DataType.WeightDataType	WEIGHT	Obbligatorio

IntervalData tipi:

DataType.ActiveEnergyDataType	ACTIVE_ENERGY_BURNED	Obbligatorio
DataType.ActiveTimeDataType	ACTIVE_TIME	Solo lettura
DataType.ActivityEventDataType	ACTIVITY_EVENT	Obbligatorio
DataType.ActivityLapDataType	ACTIVITY_LAP	Facoltativo
DataType.ActivitySessionDataType	ACTIVITY_SESSION	Obbligatorio
DataType.BasalEnergyDataType	BASAL_ENERGY_BURNED	Solo lettura
DataType.DistanceDataType	DISTANCE	Obbligatorio
DataType.ElevationGainedDataType	ELEVATION_GAINED	Obbligatorio
DataType.FloorsClimbedDataType	FLOORS_CLIMBED	Obbligatorio
DataType.HydrationDataType	HYDRATION	Obbligatorio
DataType.NutritionDataType	NUTRITION	Facoltativo
DataType.RepetitionsDataType	REPETITIONS	Obbligatorio
DataType.SleepSessionDataType	SLEEP_SESSION	Facoltativo
DataType.SleepStageDataType	SLEEP_STAGE	Obbligatorio
DataType.StepsDataType	STEPS	Obbligatorio
DataType.SwimmingStrokesDataType	SWIMMING_STROKES	Obbligatorio e facoltativo
DataType.TotalEnergyDataType	TOTAL_ENERGY_BURNED	Solo lettura

SeriesData tipi:

DataType.CyclingPedalingCadenceSeriesDataType	CYCLING_PEDALING_CADENCE	Obbligatorio
DataType.HeartRateSeriesDataType	HEART_RATE	Obbligatorio
DataType.LocationSeriesDataType	LOCATION	Obbligatorio
DataType.PaceSeriesDataType	PACE	Obbligatorio
DataType.PowerSeriesDataType	POWER	Obbligatorio
DataType.SpeedSeriesDataType	SPEED	Obbligatorio
DataType.StepsCadenceSeriesDataType	STEPS_CADENCE	Obbligatorio

Nota: i tipi SeriesData sono un sottoinsieme di SampleData. Questi tipi di dati possono essere scritti come SampleData o SeriesData. Per l'ottimizzazione delle prestazioni e dello spazio di archiviazione, consigliamo vivamente di scrivere dati ad alta frequenza, ad esempio un flusso continuo di sensori, utilizzando SeriesData.

Funzioni per sviluppatori

Di seguito viene descritto l'insieme di funzioni di dati standard disponibili in Health Platform. La piattaforma fornisce funzioni standard di inserimento, aggiornamento ed eliminazione per i dati non elaborati.

Lettura dati aggregati

La piattaforma consente ai client di applicare una funzione di aggregazione sui seguenti tipi di AggregatedData:

• StatisticalData: i valori medio, minimo o massimo in un insieme di SampleData o SeriesData, ad esempio il battito cardiaco minimo e massimo durante una sessione di attività.
• CumulativeData: la somma dei valori di IntervalData, ad esempio il numero di passi totale in un intervallo giornaliero.
• CountData: un semplice conteggio del numero di oggetti RawData sottostanti, ad esempio il numero di sessioni di attività in una determinata settimana. È possibile calcolare i dati di conteggio per i tipi di dati di esempio, intervallo e serie.

Connettersi all'API Health Platform

HealthDataClient è il punto di ingresso all'API Health Platform.

I passaggi seguenti spiegano come connettersi a Health Platform:

1. Utilizza HealthDataService.getClient per creare nuove istanze HealthDataClient.
2. L'app client deve quindi richiedere l'autorizzazione all'utente utilizzando il metodo requestPermissions (Set).

Nota: sono supportati solo i dispositivi Samsung con SDK Android versione 26 o successive.

HealthDataClient gestisce automaticamente la sua connessione al livello di archiviazione sottostante e gestisce tutte le comunicazioni tra processi (IPC) e la serializzazione delle richieste in uscita e delle risposte in arrivo.