Personenzählsoftware & API: Integrationsleitfaden für Entwickler

Die Personenzählsoftware wandelt Rohdaten von Sensoren in Kennzahlen für Belegung, Besucherfrequenz und Verweildauer um, und die Integration zwischen den beiden erfolgt über eine dokumentierte HTTP-JSON-Schnittstelle anstelle eines proprietären SDKs.Ein Entwickler kann Zählergebnisse mit einer signierten POST-Anfrage abrufen oder sie über einen Webhook empfangen, die Nutzdaten sind in beiden Fällen gleich.

Die folgende API-Anleitung zur Personenzählung beschreibt das Datenmodell, die beiden Integrationsmuster, die Authentifizierung und eine erste funktionierende Anfrage. Die Beispiele orientieren sich an der Schnittstelle der Pyroglaux 3D-Stereozähler, und die allgemeine Struktur ist auf die meisten modernen Zählgeräte übertragbar.

Was empfängt Personenzählsoftware eigentlich?

In einem modernen Personenzählsystem führt der Sensor die Zählung auf dem Gerät durch und sendet strukturierte Ereignisse, sodass die Personenzählsoftware niemals Videomaterial verarbeitet.Tiefenbilder werden direkt auf dem Sensor analysiert und verworfen.

Ein einzelnes Überquerungsereignis enthält vier Felder: einen eindeutigen Index für das verfolgte Subjekt, einen UNIX-Zeitstempel, der angibt, wann das Subjekt die Erfassungszone verlassen hat, einen Ereignistypcode und eine Verweildauer in Millisekunden.

Quelle: Pyroglaux Passenger Flow HTTP-Schnittstellenspezifikation, V2.1.5.

Die vier Ereignistypen sind der Punkt, an dem die meisten Softwareintegrationen zur Personenzählung Fehler machen. Wird jedes Ereignis als Eintritt behandelt, werden Personen, die an der Tür vorbeigehen, ohne einzutreten, doppelt gezählt. Außerdem wird der Wiedereintrittscode ignoriert, der genau dafür da ist, zu verhindern, dass ein wiederkehrender Kunde als neuer Besucher gezählt wird.

Wie funktioniert die API-Authentifizierung für die Personenzählung?

Anfragen werden signiert, anstatt ein Token im Header zu enthalten. Dabei wird ein MD5-Digest der sortierten Parameter mit einem gemeinsamen Dienstgeheimnis verkettet.Der resultierende Digest wird in Großbuchstaben umgewandelt und in einem Sign-Header gesendet.

Die Signierungsschritte sind festgelegt. Sortieren Sie jeden Anfrageparameter in ASCII-Reihenfolge, hängen Sie das mit dem Gerät vereinbarte Dienstgeheimnis an, berechnen Sie den MD5-Hexadezimalwert dieser Zeichenkette, wandeln Sie den Wert in Großbuchstaben um und fügen Sie das Ergebnis zusammen mit dem Standard-JSON-Inhaltstyp in den Sign-Header ein.

Eine signierte API-Anfrage zur Personenzählung vermeidet die Speicherung eines langlebigen Bearer-Tokens auf einem Gerät im Verkaufsraum. Ein regelmäßig geändertes Service-Secret macht alle zuvor erfassten Anfragen ohne Token-Sperrliste ungültig.

Ziehen oder Drücken: Welches Integrationsmuster passt?

Pull eignet sich für kleine Flotten und frühe Entwicklungsphasen; Push eignet sich für Live-Dashboards und größere Anlagen.Beide liefern denselben JSON-Body zurück, daher funktioniert der für das eine Muster geschriebene Parser unverändert auch mit dem anderen.

Wann sollte die Personenzählsoftware das Gerät abfragen?

Personenzählsoftware sollte zunächst eine Abfrage durchführen, da Abfragen trivial zu debuggen sind.Ein einziger curl-Befehl beweist Konnektivität, Authentifizierung und die Struktur der Nutzdaten, bevor überhaupt Anwendungscode existiert.

Die Kosten für das Polling hängen von der Erreichbarkeit der Geräte ab. Der Server muss zu jedem Sensor eine Verbindung herstellen können, was ein VPN, eine feste IP-Adresse oder eine Portweiterleitung pro Gerät erfordert. Ab etwa 50 Geräten wird die Bestandsverwaltung zum größten Wartungsaufwand.

Wann soll der Sensor stattdessen drücken?

Durch die Push-Konfiguration wird der Sensor zum Client, sodass das Gerät nur noch ausgehenden Netzwerkzugriff benötigt.Es werden weder eine Firewall-Regel für eingehende Nachrichten noch ein gerätespezifisches Adressbuch benötigt.

Dem Gerät wird über einen Konfigurationsendpunkt eine Ziel-URL zugewiesen. Anschließend werden alle auftretenden Ereignisse an diese URL gesendet. Die Latenz sinkt vom Abfrageintervall auf nahezu Echtzeit, was für Belegungsgrenzen und die Anzeige von Warteschlangen in Echtzeit von Bedeutung ist.

Wie stellt man die erste Anfrage?

Drei API-Endpunkte zur Personenzählung decken nahezu jede Integration ab: Live-Zählungen, historische Gesamtsummen und die Rohdaten der Ereignisse.Das Gerät lauscht an einem festen Port und akzeptiert RESTful POST-Anfragen mit einem JSON-Body.

Quelle: Pyroglaux Passenger Flow HTTP-Schnittstellenspezifikation, V2.1.5. Konsultieren Sie die aktuelle Gerätedokumentation für genaue Pfade, da sich die Endpunktnamen je nach Firmware-Generation unterscheiden.

Personenzählsoftware sollte bei ihrer ersten Anfrage eine kleine Anzahl von Ereignissen anfordern, anstatt die Daten eines ganzen Tages. Die Anfrage mit einem Startindex von null und einer Anzahl von 100 liefert maximal 100 Datensätze. Die Antwort gibt an, wie viele Datensätze tatsächlich verfügbar waren.

Jede Antwort der Besucherzähler-API enthält ein Ergebnisobjekt mit einem Fehlerflag, einem numerischen Code und einer lesbaren Fehlermeldung. Die Prüfung des Fehlerflags vor der Verarbeitung der Nutzdaten verhindert, dass ein leeres Ergebnis fälschlicherweise als null Besucher interpretiert wird.

Welche Grenzen sollte man vor dem Bau kennen?

Der Speicher auf dem Gerät ist ein Puffer, keine Datenbank.Ein Zählgerät speichert typischerweise Daten von etwa drei Tagen, was ausreicht, um einen Netzwerkausfall am Wochenende zu überstehen, aber nicht ausreicht, um als Aufzeichnungssystem zu dienen.

Für jedes Personenzählsystem, das auf diesen Geräten basiert, ergeben sich drei Konsequenzen: Ereignisse müssen beim Abruf im eigenen Speicher abgelegt werden. Der zuletzt erfolgreich erfasste Index oder Zeitstempel muss verfolgt werden, damit ein Neustart fortgesetzt und nicht wiederholt wird. Die Tagessummen müssen mit dem historischen Endpunkt abgeglichen werden, da die aggregierte Abfrage und die Ereignisliste auf dem Gerät separat berechnet werden.

Die Taktabweichung muss in jedem Personenzählsystem mit mehreren Standorten beachtet werden. Da die Zeitstempel von der Geräteuhr stammen, erzeugt ein nicht synchronisierter Sensor Ereignisse, die nicht korrekt mit den Kassendaten abgeglichen werden. Konfigurieren Sie einen Zeitserver daher bereits bei der Inbetriebnahme und nicht erst nach dem ersten fehlerhaften Bericht.

Wie gelangen die Daten in ein BI-Tool?

Die Integration von Besucherfrequenzdaten sollte Ereignisse roh speichern und beim Lesen aggregieren.Das Schreiben voraggregierter stündlicher Buckets in das Data Warehouse ist zwar verlockend, macht aber spätere Fragen zur Verweildauer oder zum Wiedereintritt unbeantwortbar.

Ein praktikables Minimalschema für die Integration von Besucherfrequenzdaten besteht aus einer Zeile pro Ereignis mit Geräte-ID, Zonen-ID, Zeitstempel, Ereignistyp und Verweildauer. Die stündliche Besucherfrequenz, die Umrechnung mit Kassendaten und die Verweildauerverteilung werden alle aus dieser einen Tabelle mittels normalem SQL abgeleitet.

Software zur Personenzählung, die Kassentransaktionen anhand der Geräte-ID und der Uhrzeit verknüpft, ermittelt direkt die Konversionsrate. Einzelhandelsteams, die diese Kennzahl anwenden, sollten die folgenden Informationen lesen:Glossar der Einzelhandelskennzahlenfür die Definitionen, die das Dashboard benötigt.

Verarbeitet Personenzählsoftware personenbezogene Daten?

Eine tiefenbasierte Zählpipeline, die nur Zählwerte überträgt, verarbeitet keine personenbezogenen Daten, da weder Bilder noch Kennungen den Sensor verlassen.Die oben beschriebene Nutzlast enthält einen auf eine Sitzung beschränkten Index, einen Zeitstempel und eine Dauer.

Zwei Designentscheidungen sorgen dafür, dass Personenzählsoftware diese Position einnimmt. Die Tiefenverarbeitung erfolgt auf dem Gerät, anstatt Frames zur Analyse an einen Server zu streamen. Es wird vermieden, den Sitzungsindex mit Kunden- oder Mitarbeiterdatensätzen zu verknüpfen, da dies personenbezogene Daten erzeugen würde, wo keine vorhanden sind.

Einige Firmware-Versionen bieten Funktionen zur erneuten Identifizierung, mit denen Personenzählsoftware doppelt erfasste Besucher über einen Tag hinweg erkennen kann. Diese Funktionen verändern die Analyse. Behandeln Sie jede Deduplizierungsfunktion als separate Datenschutzprüfung und nicht als automatisches Upgrade.

Häufig gestellte Fragen zu Personenzählsoftware und APIs

Ist ein SDK erforderlich, um eine Personenzähl-API zu nutzen?

Nein, für die Personenzählungs-API ist ein signierter HTTP-POST-Request mit einem JSON-Body ausreichend.Jede Programmiersprache mit einem HTTP-Client und einer MD5-Funktion ist integrierbar. Hersteller-SDKs bieten dieselbe Schnittstelle und sind zwar praktisch, aber nicht zwingend erforderlich. Der Verzicht auf ein SDK gewährleistet die Portabilität der Integration über verschiedene Gerätegenerationen hinweg.

Wie oft sollte eine Personenzählsoftware ein Gerät abfragen?

Eine Zeitspanne von ein bis fünf Minuten deckt die meisten Berichtsanforderungen ab.Schnellere Abfragen sind selten hilfreich, da die Fußgängerzahlen pro Überquerung erfasst und anschließend aggregiert werden. Live-Belegungsanzeigen bilden die Ausnahme; diese sollten Push-Benachrichtigungen anstelle schnellerer Abfragen nutzen.

Was geschieht mit den Zählerständen bei einem Netzwerkausfall?

Das Gerät speichert Ereignisse lokal zwischen und verarbeitet den Rückstand, sobald die Verbindung wiederhergestellt ist.Eine Aufbewahrungsdauer von etwa drei Tagen ist üblich. Ein Ingester, der den zuletzt verarbeiteten Index verfolgt, schließt die Lücke automatisch; ein Ingester, der stets die neuesten Datensätze anfordert, verliert das Ausfallfenster dauerhaft.

Können mehrere Systeme dieselbe Personenzähler-API aufrufen?

Ja, die Pull-Schnittstelle ist zustandslos und unterstützt gleichzeitige Leser.Jeder Aufrufer gibt einen Startindex oder einen Zeitbereich an, sodass sowohl eine BI-Pipeline als auch ein Live-Dashboard dasselbe Gerät abfragen können. Push-Ziele sind üblicherweise auf eine geringe Anzahl beschränkt, daher lässt sich die Verteilung besser über einen Relay-Server in Ihrer eigenen Infrastruktur realisieren.

Wie wird die Verweilzeit berechnet?

Die Verweildauer wird pro Ereignis als stayTime in Millisekunden angegeben und vom Eintritt in den Erfassungsbereich bis zum Verlassen des Erfassungsbereichs gemessen.Die Verweildauer in einer Zone ist nicht dasselbe wie die Verweildauer im Geschäft. Um zu messen, wie lange ein Besucher im Geschäft verweilt, sind ein Eintritts- und ein entsprechendes Austrittsereignis oder eine Wiedererkennungsfunktion erforderlich, die beide verknüpft.

Was sollte ein Integrationstest für eine Personenzählsoftware als Erstes überprüfen?

Gehen Sie eine bekannte Anzahl Male durch den Türrahmen und vergleichen Sie die Anzahl.Zehn kontrollierte Durchläufe in jeder Richtung validieren die Richtungszuordnung, die Ereignistypzuordnung und die Zeitstempelverarbeitung in einer einzigen Übung. Jede Abweichung in dieser Phase ist ein Konfigurationsproblem, kein Codefehler.

Nächste Schritte

Beginnen Sie die Integration von Besucherfrequenzdaten mit einem einzelnen Gerät, einem Abfrageskript und zehn kontrollierten Durchgängen. Sobald die Zahlen übereinstimmen, entscheiden Sie, ob eine Push-Bereitstellung erforderlich ist, und entwerfen Sie den Ereignisspeicher, bevor Sie die Skalierung auf mehr als einen Standort ausweiten.

Pyroglaux veröffentlicht die vollständige HTTP-Schnittstellenspezifikation mit jedem Gerät und sperrt die Integration nicht hinter einem Abonnement. Durchsuchen Sie die3D-ZählsensorbereichoderFordern Sie die API-Dokumentation und eine Entwicklerbeispieleinheit an.Die