Software en API voor personentelling: integratiehandleiding voor ontwikkelaars

Software voor het tellen van personen zet ruwe sensorgegevens om in bezettings-, bezoekers- en verblijfsduurstatistieken, en de integratie tussen de twee vindt plaats via een gedocumenteerde HTTP JSON-interface in plaats van een eigen SDK.Een ontwikkelaar kan tellingen opvragen met een ondertekend POST-verzoek of ze ontvangen via een webhook, en de gegevens die worden verzonden zijn in beide gevallen hetzelfde.

De onderstaande handleiding voor de API voor het tellen van personen behandelt het datamodel, de twee integratiepatronen, authenticatie en een eerste werkend verzoek. De uitgewerkte voorbeelden volgen de interface van de Pyroglaux 3D stereotellers en de algemene structuur is van toepassing op de meeste moderne telhardware.

Wat ontvangt software voor het tellen van mensen nu eigenlijk?

In een modern personentelsysteem voert de sensor de telling uit op het apparaat zelf en zendt gestructureerde gebeurtenissen uit, waardoor de personentelsoftware nooit video verwerkt.Dieptebeelden worden op de sensor zelf geanalyseerd en eventueel verwijderd.

Een enkele overschrijdingsgebeurtenis bevat vier velden: een unieke index voor het gevolgde object, een UNIX-tijdstempel dat aangeeft wanneer het object de detectiezone verliet, een gebeurtenistypecode en een verblijfsduur in milliseconden.

Bron: Pyroglaux passagiersstroom HTTP-interface specificatie, V2.1.5.

De vier soorten gebeurtenissen zijn het onderdeel waar de meeste mensen die software voor het tellen van bezoekers integreren, de mist in gaan. Door elke gebeurtenis als een binnenkomst te behandelen, worden mensen die langs de deur lopen zonder naar binnen te gaan dubbel geteld, en wordt de herbetredingscode genegeerd die er juist is om te voorkomen dat een terugkerende klant als een nieuwe bezoeker wordt geteld.

Hoe werkt API-authenticatie voor het tellen van personen?

Verzoeken worden ondertekend in plaats van een token in de header te bevatten. Hiervoor wordt een MD5-hash gebruikt van de gesorteerde parameters, samengevoegd met een gedeeld servicegeheim.De resulterende samenvatting wordt in hoofdletters weergegeven en in een Sign-header verzonden.

De ondertekeningsstappen zijn vastgelegd. Sorteer elke verzoekparameter in ASCII-volgorde, voeg het met het apparaat overeengekomen servicegeheim toe, bereken de MD5-hexhash van die tekenreeks, converteer de hash naar hoofdletters en plaats het resultaat in de Sign-header naast het standaard JSON-contenttype.

Een ondertekend API-verzoek voor het tellen van personen voorkomt dat een langdurig geldig token op een apparaat in een winkel wordt opgeslagen. Een roulerend servicegeheim maakt elk eerder vastgelegd verzoek ongeldig zonder een tokenintrekkingslijst.

Trekken of duwen: welk integratiepatroon past het beste?

Pull is geschikt voor kleine vloten en vroege ontwikkelingsfasen; push is geschikt voor live dashboards en grotere systemen.Beide retourneren dezelfde JSON-body, dus de parser die voor het ene patroon is geschreven, werkt ongewijzigd met het andere.

Wanneer moeten mensen die telsoftware gebruiken het apparaat uitlezen?

Software voor het tellen van mensen moet eerst peilen, omdat peilen dan makkelijk te debuggen is.Een enkel curl-commando bewijst de connectiviteit, authenticatie en de structuur van de payload nog voordat er applicatiecode bestaat.

De kosten van het pollen bestaan ​​uit een bereikbaar apparaat. De server moet een inkomende verbinding met elke sensor kunnen openen, wat betekent dat er per apparaat een VPN, een vast IP-adres of een poorttoewijzing nodig is. Bij meer dan ongeveer 50 apparaten wordt die inventarisatie de belangrijkste onderhoudslast.

Wanneer moet de sensor dan juist een duwtje geven?

Door de push-configuratie wordt de sensor de client, waardoor het apparaat alleen nog maar uitgaande netwerktoegang nodig heeft.Er is geen inkomende firewallregel en geen adresboek per apparaat nodig.

Het apparaat krijgt via een configuratie-eindpunt een bestemmings-URL toegewezen, waarna gebeurtenissen die zich voordoen naar die URL worden verzonden. De latentie daalt van het polling-interval naar bijna realtime, wat van belang is voor bezettingslimieten en live weergave van wachtrijen.

Hoe doe je het eerste verzoek?

De API-eindpunten voor het tellen van personen met drie waarden dekken vrijwel elke integratie: live tellingen, historische totalen en de ruwe lijst met gebeurtenissen.Het apparaat luistert op een vaste poort en accepteert RESTful POST-verzoeken met een JSON-body.

Bron: Pyroglaux passagiersstroom HTTP-interface specificatie, V2.1.5. Raadpleeg de huidige apparaatdocumentatie voor de exacte paden, aangezien eindpuntnamen verschillen per firmwaregeneratie.

Mensen die software gebruiken om gegevens te tellen, moeten bij een eerste aanvraag een kleine batch gebeurtenissen opvragen in plaats van een hele dag. Het versturen van een startindex van nul met een aantal van 100 levert maximaal 100 records op, en het antwoord geeft aan hoeveel records er daadwerkelijk beschikbaar waren.

Elke API-respons voor het tellen van bezoekers bevat een resultaatobject met een foutvlag, een numerieke code en een leesbare boodschap. Door de foutvlag te controleren voordat de payload wordt verwerkt, wordt voorkomen dat een leeg resultaat onopgemerkt als nul bezoekers wordt geïnterpreteerd.

Welke beperkingen moet je kennen voordat je gaat bouwen?

Opslag op het apparaat zelf is een buffer, geen database.Een telapparaat bewaart doorgaans ongeveer drie dagen aan historische gegevens, wat voldoende is om een ​​netwerkstoring in het weekend te overbruggen, maar niet genoeg om als officieel registratiesysteem te dienen.

Drie gevolgen zijn van belang voor elk systeem voor het tellen van personen dat op deze apparaten is gebouwd. Bewaar gebeurtenissen in uw eigen database bij het ophalen ervan. Houd de laatst succesvol verwerkte index of tijdstempel bij, zodat een herstart het proces hervat in plaats van een nieuwe herstart te veroorzaken. Vergelijk de dagelijkse totalen met het historische eindpunt, omdat de geaggregeerde query en de gebeurtenissenlijst afzonderlijk op het apparaat worden berekend.

Klokafwijking verdient aandacht in elk systeem voor het tellen van personen op meerdere locaties. Tijdstempels zijn afkomstig van de klok van het apparaat, dus een niet-gesynchroniseerde sensor genereert gebeurtenissen die onjuist worden gesorteerd ten opzichte van POS-gegevens. Configureer een tijdserver tijdens de ingebruikname in plaats van na het eerste onjuiste rapport.

Hoe komen de gegevens bij een BI-tool terecht?

Bij de integratie van bezoekersgegevens moeten de gegevens ruw worden opgeslagen en bij het lezen worden geaggregeerd.Het is verleidelijk om vooraf geaggregeerde uurlijkse gegevens in het datawarehouse op te slaan, maar dit maakt latere vragen over verblijftijd of herbetreding onbeantwoordbaar.

Een werkbaar minimumschema voor de integratie van bezoekersaantallen bestaat uit één rij per evenement met apparaat-ID, zone-ID, tijdstempel, evenementtype en verblijfsduur. Het aantal bezoekers per uur, de omrekening naar kassagegevens en de verdeling van de verblijfsduur worden allemaal afgeleid van die ene tabel met behulp van standaard SQL.

Software voor het tellen van personen, die kassatransacties koppelt op basis van apparaat-ID en uur, berekent direct het conversiepercentage. Retailteams die deze meetmethode toepassen, dienen de volgende informatie te raadplegen:Woordenlijst met retailstatistiekenvoor de definities die het dashboard nodig heeft.

Verwerkt software voor het tellen van personen persoonsgegevens?

Een op diepte gebaseerde telpipeline die alleen tellingen verzendt, verwerkt geen persoonsgegevens, omdat er geen beeld en geen identificatiegegevens de sensor verlaten.De hierboven beschreven payload bevat een index die is gekoppeld aan een sessie, een tijdstempel en een duur.

Twee ontwerpkeuzes zorgen ervoor dat software voor het tellen van gebruikers in die positie blijft. De diepteverwerking moet op het apparaat zelf plaatsvinden in plaats van frames naar een server te streamen voor analyse. Het is ook belangrijk om de sessie-index niet te koppelen aan klant- of werknemersgegevens, aangezien een dergelijke koppeling persoonlijke gegevens zou creëren waar die er niet zijn.

Functies voor heridentificatie waarmee software voor het tellen van personen dezelfde bezoeker over een dag kan onderscheiden, zijn beschikbaar op sommige firmwareversies. Deze functies beïnvloeden de analyse. Beschouw elke mogelijkheid tot het verwijderen van duplicaten als een aparte privacybeoordeling en niet als een automatische update.

Veelgestelde vragen over software en API's voor het tellen van personen

Is een SDK vereist om een ​​API voor het tellen van personen te gebruiken?

Nee, een ondertekende HTTP POST met een JSON-body is voldoende voor de API voor het tellen van personen.Elke programmeertaal met een HTTP-client en een MD5-functie kan worden geïntegreerd. SDK's van leveranciers bieden dezelfde interface en zijn handig, maar niet noodzakelijk. Door geen SDK te gebruiken, blijft de integratie overdraagbaar tussen verschillende apparaatgeneraties.

Hoe vaak moeten mensen die telsoftware gebruiken een apparaat uitlezen?

Elke minuut tot vijf minuten is voldoende voor de meeste rapportagebehoeften.Sneller peilen helpt zelden, omdat het aantal voetgangers per oversteek wordt geregistreerd en vervolgens wordt samengevoegd. Live weergaven van de bezettingsgraad vormen hierop een uitzondering, en daarvoor is pushmeldingen beter dan sneller peilen.

Wat gebeurt er met de tellingen tijdens een netwerkstoring?

Het apparaat buffert gebeurtenissen lokaal en verwerkt de achterstand zodra de verbinding hersteld is.Een bewaartermijn van ongeveer drie dagen is gebruikelijk. Een dataverwerker die de laatst verwerkte index bijhoudt, herstelt de onderbreking automatisch; een dataverwerker die altijd de nieuwste records opvraagt, verliest de mogelijkheid tot onderbreking permanent.

Kunnen meerdere systemen dezelfde API voor het tellen van personen aanroepen?

Ja, de pull-interface is stateless en ondersteunt gelijktijdige lezers.Elke beller levert een startindex of een tijdsbereik aan, zodat zowel een BI-pipeline als een live dashboard hetzelfde apparaat kunnen bevragen. Het aantal pushbestemmingen is meestal beperkt, dus de verspreiding kan beter worden afgehandeld door een relay in uw eigen infrastructuur.

Hoe wordt de verblijftijd berekend?

De verblijfsduur wordt per gebeurtenis weergegeven als stayTime in milliseconden, gemeten vanaf het moment dat de detectiezone wordt betreden tot het moment dat deze wordt verlaten.De verblijfsduur in een zone is niet hetzelfde als de verblijfsduur in een winkel. Om te meten hoe lang een bezoeker in de winkel verblijft, is een binnenkomstgebeurtenis en een bijbehorende vertrekgebeurtenis nodig, of een heridentificatiefunctie die de twee koppelt.

Wat moet een integratietest van personentelsoftware als eerste controleren?

Loop een bekend aantal keren door de deuropening en vergelijk het aantal.Tien gecontroleerde passes in elke richting valideren de richtingstoewijzing, de toewijzing van gebeurtenistypen en de verwerking van tijdstempels in één oefening. Eventuele afwijkingen in dit stadium duiden op een configuratieprobleem, niet op een codeprobleem.

Volgende stappen

Begin met het integreren van bezoekersgegevens met één apparaat, een polling-script en tien gecontroleerde rondleidingen. Zodra de cijfers overeenkomen, bepaal je of de implementatie push-gebaseerd moet zijn en ontwerp je de event store voordat je verder gaat dan één locatie.

Pyroglaux publiceert de volledige HTTP-interface specificatie bij elk apparaat en stelt geen abonnement als toegangsbeperking. Bekijk de3D-telsensorbereikofVraag de API-documentatie en een ontwikkelaarsvoorbeeld aan..