Presence Analytics

Presence analytics, also known as location analytics or WiFi analytics, refers to the location data of WiFi clients detected by WiFi Access Points (APs) in the environment.

Whenever an active WiFi client enters a new location, it probes its surroundings for WiFi networks to connect to. These probe request packets containing its MAC address are then used by the AP to recognize the WiFi client. The location of a specific WiFi client is determined with high accuracy whenever many APs from the same network are deployed in the area.

This location data can be used by presence analytics service providers to provide further analysis, such as studying customer behavior in shopping malls for marketing purposes.

Kaiwoo is able to provide captured WiFi probe requests via the CMX Scanning API developed by Cisco-Meraki and to communicate them to presence analytics service providers.

CMX Scanning API

The CMX Scanning API is a Push API. It takes care of sending captured WiFi probe requests in JSON format from the Kaiwoo server to the Destination URL specified by the presence analytics service provider. This URL can be configured either in the Kaiwoo Console or via Provisioning API, and it must be a secure HTTPS receiver to ensure data is protected.

The following graphic gives an overview of the communication flow between Kaiwoo and the presence analytics service provider.

Security

The identity of both the sending and receiving server needs to be validated for security reasons. This is done in two ways:

The Kaiwoo server sends an HTTP GET request to the presence analytics service provider’s Destination URL and is returned a validator token. Thanks to this, Kaiwoo can confirm that the provided Destination URL is correct.
For every HTTP POST the Kaiwoo server sends to the Destination URL with captured WiFi probe requests, the HTTP secret is forwarded as well. This way the presence analytics service provider is able to easily verify the identity of the sender, making sure the data is actually coming from Kaiwoo.

Both HTTP secret and validator are random strings which can be configured on the Kaiwoo Console or via Provisioning API.

Examples

First, Kaiwoo confirms that the provided Destination URL is correct.

Validating Destination URL

The Kaiwoo server sends an HTTP GET request to validate the Destination URL.

Sample Request:

[GET] https://destination_url/

Response Parameters

The presence analytics service provider returns the validator string in the response body.

Name	Type	Sample Response
`validator`	string	91473297842319492749273285409854

If a matching validator string is returned, Kaiwoo starts posting JSON data.

Posting JSON Data

Kaiwoo sends an HTTP POST request to the validated Destination URL, including both the captured WiFi probe requests in JSON format and the provided HTTP secret.

Sample Request:

[POST] https://destination_url/

Response Parameters

The following parameters are posted by Kaiwoo:

Name	Format	Description
`secret`	string	The HTTP secret forwarded with every POST request. The presence analytics service provider uses it to easily verify the identity of the sender, making sure the data is actually coming from Kaiwoo.
`version`	string	The CMX Scanning API version; currently 2.0.
`type`	string	Always shows the string “DevicesSeen”.
`frequency`	integer	The WiFi channel converted to frequency. Sent only if triangulation is disabled.
`hash`	string	A checksum computed over the captured WiFi probe request which makes it easy to identify duplicates. Sent only if triangulation is disabled.
`rssi`	integer	The client RSSI as seen by AP.
`location`	location	The client geolocation; null if triangulation is disabled.
`lat`	decimal	The client latitude in degrees N of the equator; null if triangulation is disabled.
`lng`	decimal	The client longitude in degrees E of the prime meridian; null if triangulation is disabled.
`unc`	decimal	The client location uncertainty in meters; 0 if triangulation is disabled.
`x`	decimal	The JSON array of x offsets (in meters) from lower-left corner of each floorplan; 0.0 if triangulation is disabled.
`y`	decimal	The JSON array of y offsets (in meteres) from lower-left corner of each floorplan; 0.0 if triangulation is disabled.
`apMac`	string	The MAC address of the observing AP. Sent only if triangulation is disabled. Format: six hex bytes separated by colons (“:”).
`clientMac`	string	The MAC address of the WiFi client. Format: six hex bytes separated by colons (“:”). Please note: the API sends the raw client MAC address. It is up to the receiving service to hash or modify the data before storage if data privacy is desired.
`seenTime`	ISO 8601 date string	The observation time in UTC. Format: “1970-01-01T00:00:00Z”.
`seenEpoch`	integer	The observation time in seconds since the UNIX epoch.

Example JSON Data for WiFi Clients (triangulation disabled)

  {
  	"secret": "myhttpsecret",
  	"version": "2.0",
  	"type": "DevicesSeen",
  	"data": {
  		"observations": [{
  			"frequency": 2432,
  			"hash": "33c802cf84566b9e5e6bd03d7f8ce7345b60426271ed7a861bded06e4ea6a84c",
  			"rssi": 9,
  			"location": {
  				"lat": null,
  				"lng": null,
  				"unc": 0
                                        "x": 0 
                                        "y": 0 
  			},
  			"clientMac": "aa:a1:11:a1:1a:1a",
  			"seenTime": "2020-10-23T09:07:43Z",
  			"apMac": "11:22:33:44:55:66",
  		}, {
  			"frequency": 5220,
  			"hash": "047978ac41da2e738452acde33284826b44fcc86c629b0bcd5e7e1c4aed8fcbf",
  			"rssi": 5,
  			"location": {
  				"lat": null,
  				"lng": null,
  				"unc": 0
                                        "x": 0 
                                        "y": 0 
  			},
  			"clientMac": "0c:2c:22:22:2c:c2",
  			"seenTime": "2020-10-23T09:07:43Z",
  			"seenEpoch": 1600074463,
  			"apMac": "11:22:33:44:55:66",
  		}]
  	}
  }