Desenvolver experiências de etapas com a API Google Health

A API Google Health rastreia os passos do usuário e os dados de atividade usando o tipo de dados de intervalo steps. A contagem de passos 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 passos no 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 passos:

Tabela: tipos de dados de passos da API Google Health

Tipo de dado	Operações disponíveis	Escopo
Passos dataType: steps parâmetro de filtro: steps Tipo de registro: Intervalo Suporte a webhook Suporte a zeros verdadeiros Guia de passos Dispositivos compatíveis 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

Diretrizes

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

Cálculo de velocidade e ritmo

A API Google Health usa fórmulas padrão para calcular a velocidade e o ritmo:

• Velocidade = distance / time(hour)
• Ritmo = time(seconds) / distance

O cabeçalho Accept-Language especificado na solicitação determina a unidade de distância.

Visão geral diária

Para agregar contagens de passos 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 passos acumulados para o dia solicitado.

Desenho de interfaces do usuário (reconciliação)

Ao criar elementos de interface do usuário para mostrar dados de passos, use o endpoint reconcile. Se várias fontes de dados (como um smartwatch e um smartphone) tiverem registrado passos ao mesmo tempo, o endpoint reconcile vai 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 passos 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 passos:use o endpoint list para buscar os registros de passos brutos mais granulares.

Os endpoints rollUp, dailyRollUp e reconcile aceitam o parâmetro dataSourceFamily, permitindo filtrar dados de grupos de origem específicos. Para mais detalhes e exemplos de uso, consulte a seção Filtrar e agregar por família de fonte de dados do guia de endpoints.

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 passos 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 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 usando um rastreador, mas não estiver caminhando durante um determinado período, a API vai retornar um registro para esse intervalo que contém a fonte de dados normal e os metadados de carimbo de data/hora, mas omite a propriedade count.

Isso permite distinguir entre:

• Períodos estacionários no pulso:o usuário está usando o dispositivo, mas não está caminhando. Isso retorna registros sem a propriedade count (interpretada como zero passos).
• Períodos fora do pulso:o usuário não está usando o dispositivo. Isso não retorna nenhum registro, resultando em grandes lacunas de dados.

Consulte o guia Presença de dados e zeros verdadeiros para mais detalhes.