Logiciel de comptage de personnes et API : Guide d’intégration pour les développeurs

Les logiciels de comptage de personnes transforment les données brutes des capteurs en mesures d'occupation, de fréquentation et de temps de présence, et l'intégration entre les deux se fait via une interface HTTP JSON documentée plutôt que via un SDK propriétaire.Un développeur peut récupérer les décomptes via une requête POST signée ou les recevoir via un webhook, et la charge utile est la même dans les deux cas.

Le guide de l'API de comptage de personnes ci-dessous aborde le modèle de données, les deux modes d'intégration, l'authentification et une première requête fonctionnelle. Les exemples pratiques suivent l'interface des compteurs stéréo 3D Pyroglaux, et la structure générale est compatible avec la plupart des matériels de comptage modernes.

Que reçoivent réellement les logiciels de comptage de personnes ?

Dans un système moderne de comptage de personnes, le capteur effectue le comptage sur l'appareil et émet des événements structurés ; le logiciel de comptage de personnes ne traite donc jamais la vidéo.Les images de profondeur sont analysées et éliminées directement sur le capteur.

Un seul événement de franchissement comporte quatre champs : un index unique pour le sujet suivi, un horodatage UNIX marquant le moment où le sujet a quitté la zone de détection, un code de type d’événement et une durée de maintien en millisecondes.

Source : Spécification de l'interface HTTP de flux de passagers Pyroglaux, V2.1.5.

Les quatre types d'événements constituent l'erreur la plus fréquente lors de l'intégration de logiciels de comptage. Considérer chaque événement comme une entrée revient à compter deux fois toute personne passant devant la porte sans entrer, et ignore le code de réentrée, pourtant conçu précisément pour éviter qu'un client de retour ne soit comptabilisé comme un nouveau visiteur.

Comment fonctionne l'authentification de l'API de comptage de personnes ?

Les requêtes sont signées au lieu de comporter un jeton dans l'en-tête, en utilisant un condensé MD5 des paramètres triés concaténés avec un secret de service partagé.Le condensé résultant est mis en majuscules et envoyé dans un en-tête Sign.

Les étapes de signature sont fixes. Triez chaque paramètre de requête par ordre ASCII, ajoutez le secret de service convenu avec l'appareil, calculez le condensé hexadécimal MD5 de cette chaîne, convertissez le condensé en majuscules et placez le résultat dans l'en-tête Sign à côté du type de contenu JSON standard.

Une requête API de comptage de personnes signée évite le stockage d'un jeton porteur à longue durée de vie sur un appareil installé en magasin. Un secret de service renouvelé régulièrement invalide toute requête précédemment enregistrée sans liste de révocation de jeton.

Pull ou Push : quel modèle d’intégration convient le mieux ?

La fonction « pull » convient aux petites flottes et aux phases de développement initiales ; la fonction « push » convient aux tableaux de bord en temps réel et aux parcs automobiles plus importants.Les deux renvoient le même corps JSON, donc l'analyseur syntaxique écrit pour un modèle fonctionne sans modification avec l'autre.

À quel moment le logiciel de comptage de personnes doit-il interroger l'appareil ?

Les logiciels de comptage de personnes devraient d'abord effectuer un sondage, car le débogage par sondage est très simple.Une simple commande curl permet de prouver la connectivité, l'authentification et la structure de la charge utile avant même l'existence du moindre code applicatif.

Le coût de l'interrogation est lié à la disponibilité de chaque appareil. Le serveur doit pouvoir établir une connexion entrante avec chaque capteur, ce qui implique un VPN, une adresse IP fixe ou une redirection de port par appareil. Au-delà d'une cinquantaine d'appareils, cet inventaire représente la principale charge de maintenance.

Quand le capteur devrait-il pousser à la place ?

La configuration push transforme le capteur en client, de sorte que l'appareil n'a besoin que d'un accès réseau sortant.Aucune règle de pare-feu entrante ni aucun carnet d'adresses par appareil ne sont requis.

L'appareil reçoit une URL de destination via un point de terminaison de configuration, puis les événements de passage y sont publiés au fur et à mesure de leur survenue. La latence passe ainsi de l'intervalle d'interrogation au quasi-temps réel, ce qui est crucial pour la gestion des limites d'occupation et l'affichage en temps réel des files d'attente.

Comment effectuer la première demande ?

Les trois points de terminaison de l'API de comptage des personnes couvrent presque toutes les intégrations : les décomptes en direct, les totaux historiques et la liste brute des événements.L'appareil écoute sur un port fixe et accepte les requêtes RESTful POST avec un corps JSON.

Source : Spécification de l’interface HTTP de flux passagers Pyroglaux, V2.1.5. Consultez la documentation actuelle de l’appareil pour connaître les chemins exacts, car les noms des points de terminaison diffèrent selon les générations de micrologiciels.

Lors de sa première requête, un logiciel de comptage de personnes devrait demander un petit lot d'événements plutôt qu'une journée entière. Envoyer un index de départ de zéro avec une quantité de 100 renverra au maximum 100 enregistrements, et la réponse indiquera le nombre d'enregistrements réellement disponibles.

Chaque réponse de l'API de comptage de visiteurs contient un objet résultat incluant un indicateur d'erreur, un code numérique et un message explicite. Vérifier l'indicateur d'erreur avant d'analyser la charge utile permet d'éviter qu'un résultat vide ne soit interprété comme l'absence de visiteurs.

Quelles sont les limites à connaître avant de construire ?

Le stockage interne est une mémoire tampon, pas une base de données.Un dispositif de comptage conserve généralement environ trois jours d'historique, ce qui est suffisant pour survivre à une panne de réseau de week-end, mais insuffisant pour servir de système d'enregistrement.

Trois conséquences découlent de tout système de comptage de personnes construit sur ces appareils : il faut conserver les événements dans votre propre base de données lors de leur récupération ; il faut suivre le dernier index ou horodatage ingéré avec succès afin qu’un redémarrage permette une reprise et non un nouveau redémarrage ; il faut rapprocher les totaux quotidiens avec le point de terminaison historique, car la requête d’agrégation et la liste des événements sont calculées séparément sur l’appareil.

Dans tout système de comptage de personnes multisite, la dérive d'horloge mérite une attention particulière. Les horodatages proviennent de l'horloge de l'appareil ; un capteur non synchronisé génère donc des événements qui ne correspondent pas aux données du point de vente. Il est recommandé de configurer un serveur de temps lors de la mise en service, et non après le premier rapport d'erreur.

Comment les données parviennent-elles à un outil de BI ?

L'intégration des données de fréquentation doit stocker les événements bruts et les agréger à la lecture.Il est tentant d'inscrire des données horaires pré-agrégées dans l'entrepôt, mais cela rend impossible de répondre ultérieurement aux questions concernant le temps de présence ou la réentrée.

Un schéma minimal fonctionnel pour l'intégration des données de fréquentation consiste en une ligne par événement, contenant l'identifiant du périphérique, l'identifiant de la zone, l'horodatage, le type d'événement et la durée de présence. La fréquentation horaire, la conversion avec les données de caisse et la distribution des durées de présence sont toutes issues de cette unique table, via une requête SQL classique.

Un logiciel de comptage de personnes qui associe les transactions en caisse à l'identifiant de l'appareil et à l'heure calcule directement le taux de conversion. Les équipes de vente au détail qui utilisent cet indicateur devraient consulter les informations suivantes :Glossaire des indicateurs de performance du commerce de détailpour les définitions dont le tableau de bord aura besoin.

Les logiciels de comptage de personnes traitent-ils des données personnelles ?

Un système de comptage basé sur la profondeur qui ne transmet que des comptes ne traite pas de données personnelles, car aucune image ni aucun identifiant ne quitte le capteur.La charge utile décrite ci-dessus contient un index limité à une session, un horodatage et une durée.

Deux choix de conception expliquent la position actuelle des logiciels de comptage de personnes : privilégier le traitement en profondeur sur l’appareil plutôt que l’envoi des images vers un serveur pour analyse ; et éviter de lier l’index de session à un enregistrement client ou employé, car cette liaison créerait des données personnelles inexistantes.

Certains micrologiciels proposent des fonctionnalités de réidentification permettant aux logiciels de comptage de personnes de dédupliquer le nombre de visiteurs enregistrés plusieurs fois dans la journée. Ces fonctionnalités modifient l'analyse. Il est recommandé de considérer toute fonction de déduplication comme un examen de confidentialité distinct et non comme une mise à jour automatique.

FAQ sur les logiciels et API de comptage de personnes

Un kit de développement logiciel (SDK) est-il nécessaire pour utiliser une API de comptage de personnes ?

Non, une requête HTTP POST signée avec un corps JSON est suffisante pour l'API de comptage de personnes.Tout langage disposant d'un client HTTP et d'une fonction MD5 peut s'intégrer. Les kits de développement logiciel (SDK) des fournisseurs offrent la même interface et sont pratiques sans être indispensables ; en évitant leur utilisation, l'intégration reste portable d'une génération d'appareils à l'autre.

À quelle fréquence un logiciel de comptage de personnes doit-il interroger un appareil ?

Un intervalle de une à cinq minutes suffit généralement pour répondre aux besoins en matière de rapports.Accélérer l'interrogation est rarement utile car le trafic piétonnier est enregistré à chaque passage et agrégé a posteriori. Les affichages d'occupation en temps réel constituent l'exception et devraient privilégier la mise à jour continue plutôt qu'une interrogation plus rapide.

Que deviennent les comptages lors d'une panne de réseau ?

L'appareil met les événements en mémoire tampon localement et traite le flux d'événements en attente une fois la connexion rétablie.Une durée de conservation d'environ trois jours est courante. Un module d'ingestion qui suit le dernier index traité récupère automatiquement le délai ; un module d'ingestion qui demande systématiquement les enregistrements les plus récents perd définitivement la fenêtre de récupération en cas d'interruption de service.

Plusieurs systèmes peuvent-ils appeler la même API de comptage de personnes ?

Oui, l'interface de récupération est sans état et prend en charge les lecteurs simultanés.Chaque appelant fournit un index de début ou une plage horaire, permettant ainsi à un pipeline BI et à un tableau de bord en temps réel d'interroger le même appareil. Le nombre de destinations push étant généralement limité, la diffusion est mieux gérée par un relais au sein de votre infrastructure.

Comment le temps de séjour est-il calculé ?

La durée de séjour (stayTime) est mesurée en millisecondes, de l'entrée à la sortie de la zone de détection.Le temps passé dans une zone ne correspond pas au temps passé dans le magasin. Mesurer la durée de présence d'un visiteur dans le magasin nécessite un événement d'entrée et un événement de sortie correspondant, ou un système de réidentification reliant les deux.

Que doit vérifier en premier un test d'intégration de logiciel de comptage de personnes ?

Passez devant la porte un nombre connu de fois et comparez le nombre de fois.Dix passages contrôlés dans chaque direction permettent de valider l'affectation des directions, le mappage des types d'événements et la gestion des horodatages en un seul exercice. Tout décalage à ce stade relève d'un problème de configuration, et non d'un problème de code.

Prochaines étapes

Pour intégrer les données de fréquentation, commencez par un seul appareil, un script d'interrogation et dix visites contrôlées. Une fois les chiffres concordants, déterminez si le déploiement nécessite une diffusion en temps réel et concevez le système de gestion des événements avant d'étendre le système à plusieurs sites.

Pyroglaux publie la spécification complète de l'interface HTTP avec chaque appareil et n'impose aucune condition d'intégration (abonnement non requis). Consultez la documentation.Plage de mesure du capteur de comptage 3Doudemander la documentation de l'API et un exemple d'unité de développement.