CloudTrax Presence Reporting API

Follow

Overview

The CloudTrax Presence Reporting API delivers real-time presence data from Open Mesh access points to customers, enabling applications like presence analytics, CRM tools and custom software.

The presence data is gathered from the probe request frames sent out by clients that the APs can see, and is sent to your server based on your configuration in CloudTrax.

This feature is disabled on all networks by default. Only enable it if you wish to use presence data for third-party solutions or your own custom software. Note that this feature will be part of a paid package of services in the future. 

Configuration

To configure the CloudTrax Presence Reporting API, you must have at least one or more access points running firmware version 6.1 or newer.

Navigate to Configuration > Advanced to enable and configure the CloudTrax Presence Reporting API.

You must set the following attributes:

Server Location: Where you would like the presence data to be forwarded. Must be accessible from the internet.
Key: 

This is the secret used to generate a SHA256 HMAC signature, over the payload (the JSON message). The signature is then added to a custom HTTP header (“Signature”) in the POST message.

Rate:  How often the data is sent to the server. 

Data Format

The data sent consists of the following elements:

node_mac  MAC address of the Access Point reporting the presence data. 
mac  MAC address of the end client device for which presence data is being reported.
count  Number of times the specific end client device was seen by the AP, within the time period specified by the “First seen” and “Last seen” timestamps.
min_signal Lowest RSSI reading on the AP for the specific client within the time period specified by the “First seen” and “Last seen” timestamps.
max_signal Highest RSSI reading on the AP for the specific client within the time period specified by the “First seen” and “Last seen” timestamps. 
avg_signal  Average RSSI reading on the AP for the specific client within the time period specified by the “First seen” and “Last seen” timestamps. 
last_seen_signal Reported RSSI reading on the AP for when this client was last seen.
first_seen Timestamp of the first time this client was seen, during the reporting period. Timezone is UTC.
last_seen Timestamp of the last time this client was seen, during the reporting period. Timezone is UTC.
associated Indication of whether the client is associated to the AP specified by node_mac.

The data is sent via a HTTP POST message to the server. No data is stored locally on the APs or on CloudTrax, so if the server specified in the configuration is down or otherwise unreachable, the HTTP POST will fail and cause the data to be lost. The CloudTrax UI will not provide any notification of such failure.

Sample data

{"network_id":221234,"node_mac":"AC:86:74:82:9A:30","version":1,"probe_requests":[{"mac":"00:9a:cd:e3:15:49","count":11,"min_signal":-77,"max_signal":-36,"avg_signal":-55,"last_seen_signal":-77,"first_seen":1475860695,"last_seen":1475860718,"associated":false},{"mac":"5c:dc:96:66:24:e3","count":1,"min_signal":-74,"max_signal":-74,"avg_signal":-74,"last_seen_signal":-74,"first_seen":1475860702,"last_seen":1475860702,"associated":false},{"mac":"70:ec:e4:16:75:71","count":1,"min_signal":-58,"max_signal":-58,"avg_signal":-58,"last_seen_signal":-58,"first_seen":1475860708,"last_seen":1475860708,"associated":false},{"mac":"8c:8b:83:d2:26:a5","count":1,"min_signal":-76,"max_signal":-76,"avg_signal":-76,"last_seen_signal":-76,"first_seen":1475860693,"last_seen":1475860693,"associated":false},{"mac":"98:01:a7:9e:47:7f","count":11,"min_signal":-60,"max_signal":-36,"avg_signal":-42,"last_seen_signal":-38,"first_seen":1475860712,"last_seen":1475860718,"associated":false},{"mac":"98:01:a7:a7:1d:d3","count":2,"min_signal":-84,"max_signal":-80,"avg_signal":-82,"last_seen_signal":-84,"first_seen":1475860689,"last_seen":1475860689,"associated":false},{"mac":"a8:86:dd:af:ac:0f","count":1,"min_signal":-68,"max_signal":-68,"avg_signal":-68,"last_seen_signal":-68,"first_seen":1475860708,"last_seen":1475860708,"associated":false},{"mac":"b0:fa:eb:30:4c:9e","count":10,"min_signal":-72,"max_signal":-62,"avg_signal":-67,"last_seen_signal":-67,"first_seen":1475860689,"last_seen":1475860715,"associated":false},{"mac":"e2:9f:fc:7f:1f:42","count":1,"min_signal":-65,"max_signal":-65,"avg_signal":-65,"last_seen_signal":-65,"first_seen":1475860714,"last_seen":1475860714,"associated":false}]}

Note for PHP users

PHP will not handle raw JSON POST data when processed using the $_POST
variable. To be able to access raw JSON data, you may have to use
"php://input" instead. Here is a sample script that shows you how:


<?php
// The code below uses php://input instead of $_POST as
// the data we are processing is not html form based post,
// but rather raw json that $_POST does not process.
$postdata = file_get_contents("php://input") . "\n\n";
print_r($postdata);
file_put_contents('mydata.txt', serialize($postdata), FILE_APPEND | LOCK_EX);
?>

Probe request frequency

Depending on the client device's state, the number of probe requests it sends will vary. If the device is in a power-save mode, it may reduce the number of probe requests to once per minute(or longer). If it's already associated with a WiFi network, it may not send any probe requests again until the user manually brings up the WiFi networks list on the device.

Presence reporting partners

The CloudTrax Presence Reporting API is currently being used by a number of Open Mesh partners to deliver analytics, marketing and enterprise reporting solutions. You can find a list of partners here

Have more questions? Submit a request!

Powered by Zendesk