Sviluppare esperienze di passi con l'API Google Health

L'API Google Health tiene traccia dei passi e dei dati delle attività dell'utente utilizzando il tipo di dati di intervallo 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 dell'attività quotidiana rivolti agli utenti.

Scopri come leggere e strutturare le metriche di 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   dataType   filter parametro	Tipo di record	Operazioni disponibili	Ambito	Supporto webhook	Supporto zeri effettivi
Passi   steps   steps	Intervallo	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly

Le sezioni seguenti forniscono dettagli tecnici per il tipo di dati steps, inclusi esempi di rappresentazione REST e linee guida per l'integrazione.

Ambiti obbligatori

Per accedere a questo tipo di dati, la tua app deve richiedere i seguenti ambiti OAuth:

• Lettura: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• Scrittura: https://www.googleapis.com/auth/googlehealth.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.

Panoramica giornaliera

Per aggregare con precisione i conteggi dei passi giornalieri durante i viaggi, le modifiche del 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 dei 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 e reconcile accettano il parametro di query dataSourceFamily, che ti consente di filtrare i dati di gruppi di origini specifici.

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 dei 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 è attivo o indossa un tracker ma non cammina, il tracker scrive intervalli di passi espliciti con un count di "0". In questo modo puoi distinguere i periodi in cui un utente non ha fatto passi mentre indossava il dispositivo da quelli in cui non lo indossava affatto. Per maggiori dettagli, consulta la guida Presenza dei dati e zeri effettivi per maggiori dettagli.