Software y API para el conteo de personas: Guía de integración para desarrolladores

El software de conteo de personas transforma los datos brutos de los sensores en métricas de ocupación, afluencia de personas y tiempo de permanencia, y la integración entre ambos se realiza a través de una interfaz HTTP JSON documentada en lugar de un SDK propietario.Un desarrollador puede obtener los recuentos mediante una solicitud POST firmada o recibirlos a través de un webhook, y la carga útil es la misma en ambos casos.

La guía de la API para el conteo de personas que se presenta a continuación abarca el modelo de datos, los dos patrones de integración, la autenticación y una primera solicitud funcional. Los ejemplos prácticos siguen la interfaz que ofrecen los contadores estéreo 3D de Pyroglaux, y su estructura general es compatible con la mayoría de los dispositivos de conteo modernos.

¿Qué información recibe realmente el software de conteo de personas?

En un sistema moderno de conteo de personas, el sensor realiza el conteo en el dispositivo y emite eventos estructurados, por lo que el software de conteo de personas nunca procesa video.Los fotogramas de profundidad se analizan y se descartan en el propio sensor.

Un único evento de cruce contiene cuatro campos: un índice único para el sujeto rastreado, una marca de tiempo UNIX que indica cuándo el sujeto abandonó la zona de detección, un código de tipo de evento y una duración de permanencia en milisegundos.

Fuente: Especificación de la interfaz HTTP de flujo de pasajeros de Pyroglaux, V2.1.5.

Los cuatro tipos de eventos son el aspecto en el que la mayoría de las personas que integran software de conteo suelen equivocarse. Tratar cada evento como una entrada duplica el conteo de cualquier persona que pase por delante de la puerta sin entrar, e ignora el código de reingreso que existe precisamente para evitar que un cliente recurrente sea contado como un nuevo visitante.

¿Cómo funciona la autenticación de la API de conteo de personas?

Las solicitudes se firman en lugar de llevar un token en la cabecera, utilizando un resumen MD5 de los parámetros ordenados concatenados con un secreto de servicio compartido.El resumen resultante se escribe en mayúsculas y se envía en una cabecera Sign.

Los pasos de firma son fijos. Ordena cada parámetro de la solicitud en orden ASCII, agrega el secreto de servicio acordado con el dispositivo, calcula el resumen hexadecimal MD5 de esa cadena, convierte el resumen a mayúsculas y coloca el resultado en el encabezado Sign junto con el tipo de contenido JSON estándar.

Una solicitud firmada a la API de conteo de personas evita almacenar un token de portador de larga duración en un dispositivo ubicado en la planta de producción. Un secreto de servicio rotativo invalida todas las solicitudes capturadas previamente sin una lista de revocación de tokens.

¿Arrastrar o empujar? ¿Qué patrón de integración se ajusta mejor?

El enfoque de "tirar" es adecuado para flotas pequeñas y fases iniciales de desarrollo; el enfoque de "empujar" es adecuado para paneles de control en tiempo real y entornos empresariales más grandes.Ambos devuelven el mismo cuerpo JSON, por lo que el analizador escrito para un patrón funciona sin cambios con el otro.

¿Cuándo debería el software de conteo de personas consultar el dispositivo?

El software de conteo de personas debería realizar primero un sondeo, ya que el sondeo es muy fácil de depurar.Un solo comando curl demuestra la conectividad, la autenticación y la estructura de la carga útil antes de que exista cualquier código de aplicación.

El costo del sondeo radica en la accesibilidad del dispositivo. El servidor debe poder establecer una conexión con cada sensor, lo que implica una VPN, una dirección IP fija o la asignación de puertos por dispositivo. A partir de aproximadamente 50 dispositivos, este inventario se convierte en la principal carga de mantenimiento.

¿Cuándo debería el sensor presionar en su lugar?

La configuración push convierte el sensor en cliente, por lo que el dispositivo solo necesita acceso a la red saliente.No se requiere ninguna regla de firewall de entrada ni una libreta de direcciones por dispositivo.

El dispositivo recibe una URL de destino a través de un punto final de configuración, tras lo cual los eventos de cruce se envían a esa URL a medida que ocurren. La latencia se reduce del intervalo de sondeo a prácticamente tiempo real, lo cual es importante para los límites de ocupación y la visualización de colas en tiempo real.

¿Cómo se realiza la primera solicitud?

Tres puntos finales de la API de conteo de personas cubren casi todas las integraciones: recuentos en tiempo real, totales históricos y la lista de eventos sin procesar.El dispositivo escucha en un puerto fijo y acepta solicitudes POST RESTful con un cuerpo JSON.

Fuente: Especificación de la interfaz HTTP de flujo de pasajeros de Pyroglaux, V2.1.5. Consulte la documentación actual del dispositivo para conocer las rutas exactas, ya que los nombres de los puntos finales varían entre las distintas versiones de firmware.

Los programas de conteo de personas que realizan una primera solicitud deben pedir un pequeño lote de eventos en lugar de un día completo. Enviar un índice inicial de cero con una cantidad de 100 devuelve como máximo 100 registros, y la respuesta informa cuántos registros estaban realmente disponibles.

Cada respuesta de la API de conteo de personas incluye un objeto de resultado con un indicador de error, un código numérico y un mensaje legible. Comprobar el indicador de error antes de analizar la carga útil evita que un resultado vacío se interprete automáticamente como cero visitantes.

¿Cuáles son los límites que conviene conocer antes de construir?

El almacenamiento en el dispositivo es un búfer, no una base de datos.Un dispositivo de conteo normalmente conserva unos tres días de historial, lo cual es suficiente para sobrevivir a una interrupción de la red durante el fin de semana, pero no suficiente para servir como sistema de registro.

Se derivan tres consecuencias para cualquier sistema de conteo de personas basado en estos dispositivos. Al recuperar los eventos, guárdelos en su propio repositorio. Registre el último índice o marca de tiempo procesado correctamente para que, al reiniciar, se reanuden los procesos en lugar de reiniciarse por completo. Concilie los totales diarios con el punto final histórico, ya que la consulta agregada y la lista de eventos se calculan por separado en el dispositivo.

La desincronización horaria es un factor importante a considerar en cualquier sistema de conteo de personas en múltiples ubicaciones. Las marcas de tiempo provienen del reloj del dispositivo, por lo que un sensor no sincronizado genera eventos que no coinciden con los datos del punto de venta. Configure un servidor de tiempo durante la puesta en marcha, en lugar de hacerlo después del primer informe con discrepancias.

¿Cómo llegan los datos a una herramienta de inteligencia empresarial?

La integración de datos de afluencia de público debe almacenar los eventos en bruto y agregarlos al leerlos.Introducir intervalos horarios preagregados en el almacén de datos resulta tentador y hace que las preguntas posteriores sobre el tiempo de permanencia o la reentrada sean imposibles de responder.

Un esquema mínimo viable para la integración de datos de afluencia consiste en una fila por evento con ID de dispositivo, ID de zona, marca de tiempo, tipo de evento y tiempo de permanencia. La afluencia horaria, la conversión a datos de caja y la distribución del tiempo de permanencia se derivan de esa única tabla mediante SQL estándar.

El software de conteo de personas que une las transacciones de caja por ID de dispositivo y hora produce directamente la tasa de conversión. Los equipos minoristas que aplican la métrica deben leer elglosario de métricas de venta minoristapara las definiciones que necesitará el panel de control.

¿El software de conteo de personas maneja datos personales?

Un sistema de conteo basado en la profundidad que solo transmite conteos no procesa datos personales, ya que ni la imagen ni el identificador salen del sensor.La carga útil descrita anteriormente contiene un índice asociado a una sesión, una marca de tiempo y una duración.

Dos decisiones de diseño mantienen al software de conteo de personas en esa posición. Mantener el procesamiento de profundidad en el dispositivo en lugar de transmitir fotogramas a un servidor para su análisis. Evitar vincular el índice de sesión con cualquier registro de cliente o empleado, ya que dicha vinculación crearía datos personales donde no existen.

Algunas versiones de firmware incluyen funciones de reidentificación que permiten al software de conteo de personas eliminar duplicados del mismo visitante a lo largo del día. Estas funciones modifican el análisis. Considere cualquier capacidad de eliminación de duplicados como una revisión de privacidad independiente, en lugar de una actualización automática.

Preguntas frecuentes sobre software y API para el conteo de personas

¿Se requiere un SDK para usar una API de conteo de personas?

No, una solicitud HTTP POST firmada con un cuerpo JSON es suficiente para la API de conteo de personas.Cualquier lenguaje con un cliente HTTP y una función MD5 puede integrarse. Los SDK de los proveedores encapsulan la misma interfaz y resultan convenientes, aunque no imprescindibles. Además, evitar un SDK garantiza la portabilidad de la integración entre diferentes generaciones de dispositivos.

¿Con qué frecuencia debería el software de conteo de personas consultar un dispositivo?

Entre uno y cinco minutos son suficientes para cubrir la mayoría de las necesidades de información.Realizar sondeos más rápidos rara vez resulta útil, ya que el flujo de peatones se registra por cada evento de cruce y se agrega posteriormente. Los indicadores de ocupación en tiempo real son la excepción, y en estos casos se debería utilizar la notificación push en lugar de un sondeo más rápido.

¿Qué ocurre con los recuentos durante una interrupción de la red?

El dispositivo almacena los eventos localmente y procesa la cola de eventos pendientes una vez que se restablece la conectividad.Lo habitual es un periodo de retención de aproximadamente tres días. Un sistema de ingesta que realiza un seguimiento del último índice procesado recupera automáticamente el tiempo perdido; un sistema de ingesta que siempre solicita los registros más recientes pierde permanentemente la ventana de tiempo de inactividad.

¿Pueden varios sistemas llamar a la misma API de contador de personas?

Sí, la interfaz de extracción no tiene estado y admite lectores concurrentes.Cada emisor proporciona un índice de inicio o un rango de tiempo, de modo que tanto una canalización de BI como un panel de control en tiempo real pueden consultar el mismo dispositivo. Los destinos de envío suelen estar limitados a un número reducido, por lo que la distribución se gestiona mejor mediante un relé en su propia infraestructura.

¿Cómo se calcula el tiempo de permanencia?

El tiempo de permanencia se registra por evento como stayTime en milisegundos, medido desde que se entra hasta que se sale de la zona de detección.El tiempo de permanencia en una zona no es lo mismo que el tiempo de permanencia en la tienda. Para medir cuánto tiempo permanece un visitante en la tienda, se requiere un evento de entrada y un evento de salida correspondiente, o una función de reidentificación que vincule ambos.

¿Qué debería verificar primero una prueba de integración de software de conteo de personas?

Atraviesa la puerta un número determinado de veces y compara el número de veces que la has recorrido.Diez pasadas controladas en cada dirección validan la asignación de dirección, la asignación de tipos de eventos y el manejo de marcas de tiempo en un solo ejercicio. Cualquier discrepancia en esta etapa es un problema de configuración, no de código.

Próximos pasos

Comience la integración de datos de afluencia con un solo dispositivo, un script de sondeo y diez recorridos controlados. Una vez que los datos coincidan, decida si es necesario ampliar la implementación y diseñe el repositorio de eventos antes de escalar a más de un sitio.

Pyroglaux publica la especificación completa de la interfaz HTTP con cada dispositivo y no restringe la integración a una suscripción. Explore laRango del sensor de conteo 3DoSolicite la documentación de la API y una unidad de ejemplo para desarrolladores..