Desarrolla experiencias de Pasos con la API de Google Health

La API de Google Health hace un seguimiento de los pasos del usuario y los datos de actividad con el tipo de datos de intervalo steps. El recuento de pasos representa una medida fundamental de la actividad física diaria, que ayuda a los desarrolladores a hacer un seguimiento del progreso físico, calcular el consumo de energía y generar resúmenes de la actividad diaria para los usuarios.

Comprende cómo leer y estructurar las métricas de recuento de pasos en tu aplicación para brindar la mejor experiencia a los usuarios.

Tipos de datos admitidos

La API admite el siguiente tipo de datos para hacer un seguimiento del recuento de pasos:

Tabla: Tipos de datos de los pasos de la API de Google Health

Tipo de datos	Operaciones disponibles	Alcance
Pasos dataType: steps parámetro de filtro: steps Tipo de registro: Intervalo Resolución de almacenamiento: 1 minuto Compatibilidad con webhooks Compatibilidad con el valor de cero verdadero Guía de pasos Dispositivos compatibles 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

Lineamientos

Cuando integres el seguimiento de pasos en tu app, sigue estos lineamientos de diseño e implementación.

Cálculo de la velocidad y el ritmo

La API de Google Health usa fórmulas estándar para calcular la velocidad y el ritmo:

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

El encabezado Accept-Language especificado en la solicitud determina la unidad de distancia.

Resumen diario

Para agregar con precisión los recuentos de pasos diarios durante los viajes, los cambios de zona horaria o el horario de verano, no realices cálculos de duración del cliente. En su lugar, consulta el extremo dailyRollUp, que concilia las brechas de datos físicos automáticamente con los desfases de UTC. El resumen devuelve un StepsRollupValue que contiene el campo countSum, que representa el total de pasos acumulados para el día solicitado.

Dibujar interfaces de usuario (reconciliación)

Cuando compiles elementos de la interfaz de usuario para mostrar datos de pasos, usa el extremo reconcile. Si varias fuentes de datos (como un reloj inteligente y un teléfono celular) registraron pasos al mismo tiempo, el extremo reconcile resuelve los conflictos y combina los flujos para devolver un solo flujo de datos conciliado.

Para obtener información sobre el manejo de intervalos superpuestos de sincronizaciones de dispositivos conectados y la mutabilidad de las marcas de tiempo, consulta la Guía de administración de datos.

Histogramas y seguimiento intradía

Para mostrar la actividad detallada del usuario a lo largo del día (como gráficos):

• Histogramas de pasos por hora o por minuto: Consulta el extremo rollUp y especifica la duración (por ejemplo, 60s para 1 minuto o 3600s para 1 hora) con el parámetro windowSize. Dado que los datos de pasos se registran en intervalos de 1 minuto (60s), establece windowSize en al menos 60s. Las solicitudes con tamaños de ventana inferiores a un minuto (como 10s o 30s) no segmentan los totales de minutos individuales, sino que colocan el recuento del minuto completo en el primer subsegmento coincidente. Para obtener más información, consulta Tamaño de la ventana de acumulación y resolución de almacenamiento subyacente.
• Todos los registros de pasos: Usa el extremo list para recuperar los registros de pasos sin procesar más detallados.

Los extremos rollUp, dailyRollUp y reconcile aceptan el parámetro dataSourceFamily, lo que te permite filtrar datos de grupos de fuentes específicos. Para obtener más detalles y ejemplos de uso, consulta la sección Filtrar por familia de fuentes de datos de la guía de Filtrado de datos.

Sincronización en tiempo real con webhooks

Suscríbete a la colección del tipo de datos steps para recibir notificaciones en tiempo real cuando se importen o sincronicen nuevos datos de pasos. En lugar de sondear los extremos de la API de REST, actualiza los paneles del cliente de forma dinámica en respuesta a estas notificaciones de webhook. Para obtener detalles sobre cómo configurar suscripciones, consulta Suscripciones a Webhooks.

Cómo controlar los ceros reales

La API de Google Health implementa verdaderos ceros para resolver los intervalos sedentarios. Si un usuario usa un dispositivo de seguimiento, pero no camina durante un período determinado, la API devuelve un registro para ese intervalo que contiene los metadatos normales de la fuente de datos y la marca de tiempo, pero omite la propiedad count.

Esto te permite distinguir entre los siguientes tipos:

• Períodos de inactividad en la muñeca: El usuario lleva puesto el dispositivo, pero no camina. Esto devuelve registros sin la propiedad count (que se interpreta como cero pasos).
• Períodos sin el dispositivo en la muñeca: El usuario no está usando el dispositivo. Esto no devuelve ningún registro, lo que genera grandes brechas de datos.

Consulta la guía Presencia de datos y ceros reales para obtener más detalles.