[3D Pro2 2025] FootfallCam People Counter Websocket Integration Guide

This guide helps you integrate with our people counter via WebSocket.. Please note that this guide is specific for the 3D Pro2 2025.

Setting Up Data Push via Websocket Connection

1. On device control panel, go to "Config" tab, under "Data Push", click on "New Data Push" button. See Figure 1.1

Figure 1.1: Add New Data Push

2. Configure the data push settings, choose "WebSocket" as the export mode, and select the time granularity for the level of data aggregation (i.e. every minute, every 15min, hourly, per event) and frequency for the data sending interval (i.e. every 15min, hourly, daily). Make sure the Active field is checked, so that the data pushing can take effect upon completing the configuration. See Figure 2.1 (Note: for "per event" time granularity, data will be pushed whenever there is In/Out count registered)

Figure 2.1: Configure WebSocket Data Push

3. Fill in the connection settings, namely the WebSocket server URL and the Auth token. Use the "Test Connection" button to verify whether the WebSocket server is reachable. The device will ping the WebSocket server and determine the connection status based on the reply from server side. (Note: we assume the WebSocket server is RFC-compliant, i.e. it will reply to a ping with a pong). Save the settings if the connection is working fine.

Footfall Data Payload Format

Time Granularity: Per Event

 {
  "UUID": "658a2443-72ba-422c-85dc-e4e10baa1288", #Unique for each message
  "DeviceSerial": "ecd5cc57d23c5c9f",
  "RoiId": 1, #Useful when there are multiple counting lines defined
  "MetricId": 1, #1 for IN, 2 for OUT
  "PeopleTypeId": 1,
  "CombineObjectTypeId": 11, #11 for visitor, 21 for staff
  "PeopleId": 1,
  "EventEndLocalTime": "2025-07-23 18:36:31",
  "EventEndTime": 1753266991,
  "EventEndUTCTime": "2025-07-23 10:36:31",
  "EventStartLocalTime": "2025-07-23 18:36:21",
  "EventStartTime": 1753266981,
  "EventStartUTCTime": "2025-07-23 10:36:21"
 }

Time Granularity: Every Minute, Frequency: every 15min

{
  "uuid": "658a2443-72ba-422c-85dc-e4e10baa1288", #Unique for each message
  "device_serial": "ecd5cc57d23c5c9f",
  "date_requested": "2025-07-23 10:15:00", #Local datetime
  "offset": "GMT +1",
  "output": [{
		"datetime": "2025-07-23 10:00:00", #Local datetime, forward-looking 
		"invalue": "4", #Aggregated IN count
		"outvalue": "5", #Aggregated OUT count
		"timestamp": 1753236000
	    },	
	    {	
		  ...
	    },
	    {
	      "datetime": "2025-07-23 10:14:00",
	      "invalue": "6",	
	      "outvalue": "3",
	      "timestamp": 1753236840
	    }]
} 

Time Granularity: Every 15 Minutes, Frequency: Hourly

{
  "uuid": "658a2443-72ba-422c-85dc-e4e10baa1288", #Unique for each message
  "device_serial": "ecd5cc57d23c5c9f",
  "date_requested": "2025-07-23 11:00:00", #Local datetime
  "offset": "GMT +1",
  "output": [{
 	"datetime": "2025-07-23 10:00:00", #Local datetime, forward-looking
 	"invalue": "23", #Aggregated IN count
 	"outvalue": "15", #Aggregated OUT count
 	"timestamp": 1753236000
 	},
 	{
 	...
 	},
 	{
 	"datetime": "2025-07-23 10:45:00",
 	"invalue": "16",
 	"outvalue": "31",
 	"timestamp": 1753238700
 	}]
 }

Time Granularity: Hourly, Frequency: Daily

{
  "uuid": "658a2443-72ba-422c-85dc-e4e10baa1288", #Unique for each message
  "device_serial": "ecd5cc57d23c5c9f",
  "date_requested": "2025-07-23 19:00:00", #Local datetime
  "offset": "GMT +1",
  "output": [{
 	"datetime": "2025-07-23 10:00:00", #Local datetime, forward-looking
 	"invalue": "203", #Aggregated IN count
 	"outvalue": "112", #Aggregated OUT count
 	"timestamp": 1753236000
 	},
 	{
 	...
 	},
 	{
 	"datetime": "2025-07-23 18:00:00",
 	"invalue": "45",
 	"outvalue": "345",
 	"timestamp": 1753238700
 	}]
 }

WebSocket Client Behaviours

1. Expected standard port 443 for WSS, and port 80 for WS
2. Detect and handle stale connection, support auto-reconnect with backoff.
3. Include keepalive messages every 30s
4. Expect ACK message for retry mechanism to work.
5. JSON format for push messages

WebSocket Server Requirement

1. Support Authorization: Bearer <token> header

2. RFC-compliant, i.e. reply to Ping frames (RFC 6455)

3. Send ACK message on data receival, like:
   { "status": "ack", "uuid": "74fd6a2e-..." }