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 do condicionamento físico, calcular o gasto de energia e criar resumos de atividades diárias para os usuários.

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 dados para contagem de passos:

Tabela: tipos de dados de etapas da API Google Health

Tipo de dado	Operações disponíveis	Escopo
Etapas dataType:steps filter parameter:steps Tipo de registro : Intervalo Resolução de armazenamento : 1 minuto Suporte a webhook Suporte a zeros reais 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 acompanhamento 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 velocidade e 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 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 automaticamente as lacunas de dados físicos usando os ajustes de UTC. A consolidação retorna um StepsRollupValue contendo o campo countSum, que representa o total de etapas acumuladas para o dia solicitado.

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

Ao criar elementos da 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 passos ao mesmo tempo, o endpoint reconcile vai resolver conflitos e mesclar os fluxos para retornar um único fluxo de dados conciliado.

Para informações sobre 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.

Acompanhamento e histogramas intradiários

Para mostrar a atividade detalhada do usuário 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 do minuto inteiro no primeiro subagrupamento correspondente. Para mais detalhes, consulte Tamanho da janela de rollup e resolução de armazenamento subjacente.
• Todos os registros de passos:use o endpoint list para buscar os registros de passos brutos e 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 por família de fonte de dados do guia "Filtrar dados".

Sincronização em tempo real usando webhooks

Inscreva-se na coleta do tipo de dados steps para receber notificações em tempo real quando novos dados de etapas forem importados ou sincronizados. Em vez de fazer polling 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 metadados de carimbo de data/hora, mas omite a propriedade count.

Isso permite distinguir entre:

• Períodos de imobilidade no pulso:o usuário está usando o dispositivo, mas não está caminhando. Isso retorna registros sem a propriedade count (interpretada como zero etapas).
• Períodos sem uso no 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 reais para mais detalhes.