# NGINX DeviceAtlas Connectivity Analyser #
The DeviceAtlas Connectivity Analyser is used to measure the round trip time when
sending a payload of a fixed size to a client. This measures a combination of
latency and bandwidth. The measured time is then used to categorize the
client's connection speed into low, medium or high quality categories.
## Usage ##
In order to use the Connectivity Analyser with Nginx, follow these steps:
1) Prepare the Connectivity Analyser (CA) module by compiling it along with the Nginx source.
```shell
./configure --add-module=/ngx_http_connectivity_analyser_filter \
--add-module=/ngx_http_connectivity_analyser_module \
--with-cc-opt='-g -O2 -fstack-protector-strong -Wformat -Werror=format-security -Wp,-D_FORTIFY_SOURCE=2' \
--with-ld-opt='-Wl,-z,relro -Wl,--as-needed'
Those modules are compatible with the NGINX dso mode
./configure --add-dynamic-module=/ngx_http_connectivity_analyser_filter \
--add-dynamic-module=/ngx_http_connectivity_analyser_module \
--with-cc-opt='-g -O2 -fstack-protector-strong -Wformat -Werror=format-security -Wp,-D_FORTIFY_SOURCE=2' \
--with-ld-opt='-Wl,-z,relro -Wl,--as-needed'
```
```shell
make
```
2) Update your configuration file (by default conf/nginx.conf) by using the following
directive. It must be inside the location section.
```shell
cacheck on;
```
### Results ###
When using the Connectivity Analyser, the information is returned by the
module as custom HTTP response headers with following names:
```shell
X-deviceatlas-analyse-duration (in ms)
X-deviceatlas-analyse-quality (low, mid or high).
```
### Optional parameters ###
#### 1. Cookie ####
By enabling this parameter the Connectivity Analyser results will be
returned via cookies instead of custom HTTP response headers. See the
"Step by step" section for instructions on extracting the cookies.
```shell
cacookie on;
```
** Cookie Expiry **
You can set the lifespan of the cookies. Defaults to 3600 seconds.
```shell
cacookie_expires = 3600;
```
#### 2. Payload ####
The amount of data to send to the client as part of the bandwidth
measurement. Defaults to 1KB.
```shell
capayload = 1024;
```
#### 3. Thresholds ####
The quality thresholds to define the low and mid tiers. The
threshold limits are defined in miliseconds. Everything
faster than the mid threshold is classified as high quality.
```shell
calowquality = 900;
camidquality = 400;
```
### Sample configuration ###
```shell
...
server {
listen 8080;
server_name localhost;
location /connectivity_analyser/ {
cacheck on;
cacookie on;
capcookieExpires = 86400;
fastcgi_pass_header X-deviceatlas-analyse-quality;
fastcgi_pass_header X-deviceatlas-analyse-duration;
fastcgi_param SERVER_NAME $server_name;
fastcgi_param SERVER_PROTOCOL http;
fastcgi_param SERVER_PORT 8480;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param QUERY_STRING $query_string;
fastcgi_param DA_ANALYSE_QUALITY $http_x_deviceatlas_analyse_quality;
fastcgi_param DA_ANALYSE_DURATION $http_x_deviceatlas_analyse_duration;
fastcgi_pass 127.0.0.1:8488;
}
...
```
## Step by step ##
```php
DeviceAtlas Connectivity Analyser
DeviceAtlas Connectivity Analyser
Duration: ms
Quality:
```
### Example ###
The Connectivity Analyser comes with an example application, which you can
find inside the ExampleAppConnectivityAnalyser directory. This example uses the
Connectivity Analyser to find out the quality of the user's network
and the example then returns a different photo version based on the network
performance. There are three photos with different sizes and jpeg
compression ratios, therefore different photo versions.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2021. All Rights Reserved.
https://deviceatlas.com _