Desenvolver experiências de etapas com a API Google Health

A API Google Health monitora os passos e os dados de atividade do usuário 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 do condicionamento físico, calcular o gasto de energia e criar resumos de atividades diárias voltados ao usuário.

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

Tipos de dados compatíveis

A API é compatível com o seguinte tipo de dado para monitorar a contagem de passos:

Tabela: tipos de dados de passos da API Google Health

Tipo de dado	Operações disponíveis	Escopo
Etapas dataType: steps parâmetro de filtro: steps Tipo de registro: Intervalo Resolução de armazenamento : 1 minuto Suporte a webhook Suporte a zeros verdadeiros Guia de etapas 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 monitoramento de passos ao seu 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 as contagens diárias de passos 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 as lacunas de dados físicos automaticamente usando os deslocamentos de UTC. O rollup retorna um StepsRollupValue que contém o campo countSum, que representa o total de passos acumulados no dia solicitado. Para mais detalhes, consulte Agregar em dias corridos no guia de dados agregados.

Como desenhar 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 os conflitos e mesclar os fluxos para retornar um único fluxo de dados reconciliado.

Para saber como lidar com intervalos sobrepostos de sincronizações de dispositivos conectados e mutabilidade de carimbos de data/hora, consulte o Guia de gerenciamento de dados.

Monitoramento e histogramas intradiários

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

• Histogramas de etapas por hora ou minuto:consulte o endpoint rollUp, especificando a duração (como 60s para 1 minuto ou 3600s para 1 hora) usando o parâmetro windowSize. Como os dados de passos são registrados em intervalos de 1 minuto (60s), defina windowSize como pelo menos 60s. As solicitações com tamanhos de janela inferiores a um minuto (como 10s ou 30s) não dividem os totais de minutos individuais, colocando a contagem total do minuto no primeiro sub-bucket correspondente. Para mais detalhes, consulte Janela de rollup e resolução de armazenamento.
• Todos os registros de passos:use o endpoint list para buscar os registros de passos mais granulares e brutos.

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 por família de fonte de dados do guia "Filtrar dados".

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 consultar 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.