Sviluppare esperienze di passi con l'API Google Health

L'API Google Health tiene traccia dei passi e dei dati sulle attività degli utenti utilizzando il tipo di dati a intervalli steps. Il conteggio dei passi rappresenta una misura fondamentale dell'attività fisica quotidiana, che aiuta gli sviluppatori a monitorare i progressi di fitness, calcolare il dispendio energetico e creare riepiloghi delle attività quotidiane 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
Passi dataType: steps filter parameter: steps Tipo di record: Intervallo Supporto webhook Supporto zeri effettivi Guida ai passi 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 distanza.

Riepilogo giornaliero

Per aggregare con precisione i conteggi dei passi giornalieri durante i viaggi, i cambi di fuso orario o l'ora legale, non eseguire calcoli della durata lato client. Esegui invece 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.

Disegno delle interfacce utente (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 singolo stream di dati riconciliato.

Monitoraggio e istogrammi intraday

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

• Istogrammi dei passi orari: esegui una query sull'endpoint rollUp, specificando la durata (ad es. 3600s per 1 ora) utilizzando il parametro windowSize.
• Tutti i record dei passi: utilizza l'endpoint list per recuperare i record dei passi non elaborati 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 e aggregare per famiglia di origini dati della guida agli endpoint.

Sincronizzazione in tempo reale tramite webhook

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

Gestire gli zeri effettivi

L'API Google Health implementa gli 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 i metadati normali dell'origine dati e 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 record senza la proprietà count (interpretata come zero passi).
• Periodi senza dispositivo: l'utente non indossa il dispositivo. Non viene restituito alcun record, il che comporta grandi lacune nei dati.

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