<![CDATA[
# 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=<path to CA folder>/ngx_http_connectivity_analyser_filter \
--add-module=<path to CA folder>/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=<path to CA folder>/ngx_http_connectivity_analyser_filter \
--add-dynamic-module=<path to CA folder>/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
<?php
// Getting informations through Response Headers ...
$infos = $_SERVER;
// Or through cookies ...
//$infos = $_COOKIE;
$durationMs = $infos['X-deviceatlas-analyse-duration'];
$quality = $infos['X-deviceatlas-analyse-quality'];
#
# Additionally, you can also display the duration and quality from your app with
# a simple .php script file as follows.
#
?><!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>DeviceAtlas Connectivity Analyser</title>
</head>
<body>
<h2>DeviceAtlas Connectivity Analyser</h2>
<p>
<strong>Duration:</strong> <?php echo $durationMs; ?> ms<br/>
<strong>Quality:</strong> <?php echo $quality; ?><br/>
</p>
</body>
</html>
```
### 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 _
<!-- HTML+JS for document formatting when opened in browser -->
<div class="btn-group" id="main-menu" style="float:right"><a class="btn dropdown-toggle" data-toggle="dropdown" href="#">Menu<span class="caret"></span></a><ul class="dropdown-menu"><li><a href="README.html">Main</a></li><li class="divider"></li><li><a href="README.DeviceApi-Web.html">Device Detection for Web</a></li><li><a href="README.DeviceApi-Apps.html">Device Detection for Apps</a></li><li><a href="README.DeviceApi-Config.html">Device Detection API Config</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="divider"></li><li><a href="README.Unix.html">C API and Unix</a></li><li><a href="README.Windows.html">C API and Windows</a></li><li class="divider"></li><li><a href="README.Nginx.html">C API and NGINX Module Installation</a></li><li class="divider"></li><li><a href="README.JsonConverter.html">C API JSONConverter</a></li><li><a href="https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html" target="_blank">Client-side Component</a></li><li class="disabled"><a href="README.ConnectivityAnalyser-Nginx.html">NGINX DeviceAtlas Connectivity Analyser</a></li><li><a href="README.ConnectivityAnalyser-Apache.html">Apache DeviceAtlas Connectivity Analyser</a></li><li><a href="ApiDocs/index.html">DeviceAtlas ApiDocs</a></li></ul></div>]]>