Desenvolver experiências de etapas com a API Google Health

A API Google Health rastreia as etapas do usuário e os dados de atividade usando o tipo de dados de intervalo steps. A contagem de etapas representa uma medida fundamental da atividade física diária, ajudando os desenvolvedores a acompanhar o progresso da forma física, calcular o gasto de energia e criar resumos de atividades diárias para o usuário.

Entenda como ler e estruturar as métricas de contagem de etapas no seu aplicativo para oferecer a melhor experiência aos usuários.

Tipos de dados compatíveis

A API oferece suporte ao seguinte tipo de dados para rastrear a contagem de etapas:

Tabela: tipos de dados de etapas da API Google Health

Tipo de dados   dataType   filter parâmetro	Tipo de registro	Operações disponíveis	Escopo	Suporte a webhook	Suporte a zeros verdadeiros
Etapas   steps   steps	Intervalo	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly

As seções a seguir fornecem detalhes técnicos para o tipo de dados steps, incluindo exemplos de representação REST e diretrizes de integração.

Escopos obrigatórios

Para acessar esse tipo de dados, seu app precisa solicitar os seguintes escopos do OAuth:

• Leitura: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• Gravação: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly

Diretrizes

Ao integrar o rastreamento de etapas ao seu app, siga estas diretrizes de design e implementação.

Visão geral diária

Para agregar contagens de etapas diárias com precisão em viagens, mudanças de fuso horário ou horário de verão, não faça cálculos de duração do lado do cliente. Em vez disso, consulte o endpoint dailyRollUp, que reconcilia automaticamente as lacunas de dados físicos usando os deslocamentos de UTC. O rollup retorna um StepsRollupValue que contém o campo countSum, representando o total de etapas acumuladas para o dia solicitado.

Desenhar interfaces do usuário (reconciliação)

Ao criar elementos de interface do usuário para mostrar dados de etapas, use o endpoint reconcile. Se várias fontes de dados (como um smartwatch e um smartphone) tiverem registrado etapas ao mesmo tempo, o endpoint reconcile resolverá conflitos e mesclará os fluxos para retornar um único fluxo de dados reconciliado.

Rastreamento e histogramas intradiários

Para mostrar a atividade detalhada do usuário ao longo do dia (como gráficos e tabelas):

• Histogramas de etapas por hora:consulte o endpoint rollUp, especificando a duração (por exemplo, 3600s para 1 hora) usando o parâmetro windowSize.
• Todos os registros de etapas:use o endpoint list para buscar os registros de etapas brutos mais granulares.

Os endpoints rollUp e reconcile aceitam o parâmetro de consulta dataSourceFamily, permitindo filtrar dados de grupos de origem específicos.

Sincronização em tempo real usando webhooks

Inscreva-se na coleção de tipos de dados steps para receber notificações em tempo real quando novos dados de etapas forem importados ou sincronizados. Em vez de fazer a pesquisa de endpoints REST, atualize os painéis do lado do cliente de forma dinâmica em resposta a essas notificações de webhook. Para mais detalhes sobre como configurar assinaturas, consulte Assinaturas de webhook.

Processar zeros verdadeiros

A API Google Health implementa zeros verdadeiros para resolver intervalos sedentários. Se um usuário estiver ativo ou usando um rastreador, mas não estiver caminhando, o rastreador gravará intervalos de etapas explícitos com uma count de "0". Isso permite distinguir entre períodos em que um usuário não deu nenhum passo enquanto usava o dispositivo e quando não o usava. Consulte o guia Presença de dados e zeros verdadeiros para mais detalhes.