Sviluppare esperienze di passi con l'API Google Health

L'API Google Health monitora i passi e i dati sull'attività dell'utente utilizzando il tipo di dati intervallo steps. Il conteggio dei passi rappresenta una misura fondamentale dell'attività fisica giornaliera, aiutando gli sviluppatori a monitorare i progressi di fitness, calcolare il dispendio energetico e creare riepiloghi dell'attività giornaliera rivolti agli utenti.

Scopri come leggere e strutturare le metriche del conteggio dei passi nella tua applicazione per offrire la migliore esperienza ai tuoi utenti.

Tipi di dati supportati

L'API supporta il seguente tipo di dati per il monitoraggio del conteggio dei passi:

Tabella: tipi di dati dei passi dell'API Google Health

Tipo di dati	Operazioni disponibili	Ambito
Passaggi dataType: steps filter parameter: steps Tipo di record: Intervallo Risoluzione dell'archiviazione: 1 minuto Supporto webhook Supporto di valori pari a zero Guida passo passo Dispositivi compatibili Fitbit Air Fitbit Alta Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Flex 2 Fitbit Inspire Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Fitbit MobileTrack Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4 Fitbit Versa Lite	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly

Linee guida

Quando integri il monitoraggio dei passi nella tua app, segui queste linee guida per la progettazione e l'implementazione.

Calcolo di velocità e andatura

L'API Google Health utilizza formule standard per calcolare velocità e andatura:

• Velocità = distance / time(hour)
• Andatura = time(seconds) / distance

L'intestazione Accept-Language specificata nella richiesta determina l'unità di misura della distanza.

Panoramica giornaliera

Per aggregare con precisione i conteggi giornalieri dei passi durante i viaggi, i cambi di fuso orario o l'ora legale, non eseguire calcoli della durata lato client. In alternativa, esegui una query sull'endpoint dailyRollUp che riconcilia automaticamente le lacune nei dati fisici utilizzando gli offset UTC. Il rollup restituisce un StepsRollupValue contenente il campo countSum, che rappresenta il totale dei passi accumulati per il giorno richiesto.

Interfacce utente di disegno (riconciliazione)

Quando crei elementi dell'interfaccia utente per visualizzare i dati dei passi, utilizza l'endpoint reconcile. Se più origini dati (ad esempio uno smartwatch e un cellulare) hanno registrato i passi contemporaneamente, l'endpoint reconcile risolve i conflitti e unisce gli stream per restituire un unico stream di dati riconciliato.

Per informazioni sulla gestione degli intervalli sovrapposti dalle sincronizzazioni dei dispositivi connessi e sulla modificabilità dei timestamp, consulta la guida alla gestione dei dati.

Monitoraggio e istogrammi infragiornalieri

Per visualizzare l'attività utente dettagliata durante il giorno (ad esempio grafici):

• Istogrammi a intervalli di minuti o ore:esegui una query sull'endpoint rollUp, specificando la durata (ad esempio 60s per 1 minuto o 3600s per 1 ora) utilizzando il parametro windowSize. Poiché i dati dei passi vengono registrati a intervalli di 1 minuto (60s), imposta windowSize su almeno 60s. Le richieste con dimensioni della finestra inferiori al minuto (ad esempio 10s o 30s) non suddividono i totali dei singoli minuti, ma inseriscono il conteggio dell'intero minuto nel primo sotto-bucket corrispondente. Per maggiori dettagli, vedi Dimensioni della finestra di rollup e risoluzione dello spazio di archiviazione sottostante.
• Tutti i record dei passi: utilizza l'endpoint list per recuperare i record dei passi grezzi più granulari.

Gli endpoint rollUp, dailyRollUp e reconcile accettano il parametro dataSourceFamily, che consente di filtrare i dati di gruppi di origini specifici. Per maggiori dettagli ed esempi di utilizzo, consulta la sezione Filtrare per famiglia di origini dati della guida Filtrare i dati.

Sincronizzazione in tempo reale tramite webhook

Iscriviti alla raccolta di tipi di dati steps per ricevere notifiche in tempo reale quando vengono importati o sincronizzati nuovi dati sui passi. Anziché eseguire il polling degli endpoint REST, aggiorna dinamicamente le dashboard lato client in risposta a queste notifiche webhook. Per informazioni dettagliate su come configurare gli abbonamenti, vedi Abbonamenti webhook.

Gestire gli zeri effettivi

L'API Google Health implementa zeri effettivi per risolvere gli intervalli sedentari. Se un utente indossa un tracker ma non cammina durante un determinato periodo, l'API restituisce un record per quell'intervallo che contiene l'origine dati normale e i metadati del timestamp, ma omette la proprietà count.

In questo modo, puoi distinguere tra:

• Periodi di stazionamento al polso:l'utente indossa il dispositivo ma non cammina. Vengono restituiti i record senza la proprietà count (interpretata come zero passaggi).
• Periodi in cui il dispositivo non è indossato:l'utente non indossa il dispositivo. In questo modo non viene restituito alcun record, il che comporta grandi lacune nei dati.

Per maggiori dettagli, consulta la guida Presenza di dati e zeri effettivi.