API Health Platform

Nota: l'API Health Platform versione 1 è ritirata a partire 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 a salute e attività fisica di un utente. Consulta la documentazione di Connessione Salute per scoprire di più sulla piattaforma. Consulta la sezione Inizia per l'integrazione con l'API.

L'API Health Platform è un'API Android che fornisce agli sviluppatori una singola interfaccia per leggere, scrivere e condividere i dati storici relativi a salute, benessere e attività fisica di un utente. Con la piattaforma per la salute, 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 altro 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 loro dati personali relativi a salute, attività fisica e benessere. In questo modo, gli sviluppatori di app possono mostrare agli utenti una visione più completa della loro salute e consentire loro di monitorare i propri dati in modo più efficace.

Il kit di sviluppo software dell'API Health Platform offre agli sviluppatori di app per Android tutto ciò di cui hanno bisogno per fornire l'accesso ai dati di salute e benessere di un utente su determinati dispositivi Samsung e consente alle app di eseguire operazioni collettive come l'inserimento, l'eliminazione e la lettura dei dati.

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

Inizia

Quando utilizzi la piattaforma per la salute, 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 successivo.
• L'API Health Platform supporta solo alcuni dispositivi Samsung.
• HealthDataClient è il client per la piattaforma per la salute e un punto di accesso alla piattaforma per la salute.

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

Figura 1. Passaggi per l'integrazione della piattaforma per la salute.

File di rilascio

La release V1 di Health Platform contiene quanto segue:

• SDK client: includi questo SDK nella tua 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 questa procedura:

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

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

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

Kotlin

dependencies { . . . implementation("com.google.android.libraries.healthdata:health-data-api:1.0.0-alpha01") }

Trendy

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

Dati

Health Platform memorizza e struttura i dati relativi a salute e fitness. Inoltre, tiene conto delle differenze fondamentali tra il modo in cui vengono misurati i dati di diversi tipi. Ad esempio, una misurazione della frequenza cardiaca viene eseguita immediatamente, mentre il conteggio dei passi viene eseguito in un determinato periodo di tempo.

Ecco uno sguardo agli oggetti centrali di Health Platform e alle loro differenze:

• RawData:una misurazione e un record di dati.
• DataType: uno specificatore per i tipi comuni di dati su salute e fitness, come frequenza cardiaca, grasso corporeo o temperatura corporea, e i relativi formati, come campi, di sola lettura o facoltativi.
• SampleData: un oggetto RawData che è una misurazione istantanea, come la frequenza cardiaca, la pressione sanguigna o la velocità di corsa.
• IntervalData: un oggetto RawData che è una misurazione cumulativa effettuata in un 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 dei sensori ad alta frequenza, come i campioni continui del battito cardiaco durante una sessione di attività.

Ciascuna delle tre classi RawData corrisponde a una sottoclasse specifica 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 Health 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

La piattaforma per la salute include un'ampia gamma di tipi di dati comunemente utilizzati nelle app per la salute e l'attività fisica. I dati memorizzati con i tipi di dati disponibili forniscono agli utenti una visione completa dei loro dati storici su salute, fitness e benessere, offrendo informazioni sulle loro attività quotidiane.

Ogni tipo di dati è definito dal suo formato, che include quanto segue:

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

Elenco dei tipi di dati

Sfrutta al meglio la piattaforma per la salute comprendendo i tipi di dati disponibili. La piattaforma per la salute supporta i tipi di dati mostrati nella tabella seguente. I tipi di dati sono organizzati in base al formato: campione, intervallo o serie.

SampleData tipi:

Tabella 1: tipi di SampleDatapiattaforma sanitaria

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:

Tabella 3: tipi di SeriesDatapiattaforma sanitaria

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 dei tipi SampleData. Questi tipi di dati possono essere scritti come SampleData o SeriesData. Per l'ottimizzazione delle prestazioni e dello spazio di archiviazione, ti consigliamo vivamente di scrivere i dati ad alta frequenza, come uno stream di sensori continuo, utilizzando SeriesData.

Funzioni per sviluppatori

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

Read AggregatedData

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

• StatisticalData:i valori medi, minimi o massimi in un insieme di SampleData o SeriesData, ad esempio la frequenza cardiaca minima e massima durante una sessione di attività.
• CumulativeData:la somma dei valori IntervalData, ad esempio il numero totale di passi 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. I dati di conteggio possono essere calcolati per i tipi di dati campione, intervallo e serie.

Connettersi all'API Health Platform

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

I passaggi seguenti descrivono 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 versione SDK Android 26 o successive.

HealthDataClient gestisce automaticamente la connessione al livello di archiviazione sottostante e gestisce tutta la comunicazione interprocesso (IPC) e la serializzazione delle richieste in uscita e delle risposte in entrata.