<![CDATA[
# Apache 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 Apache 2.x or later,
follow these steps:
1) Prepare the Connectivity Analyser (CA) module by compiling it.
```shell
- cd <path to CA folder>/ConnectivityAnalyser
- sudo apxs/apxs2 -i -a -c mod_connectivity_analyser.c
or
- cmake .
```
2) Copy the mod_connectivity_analyser.so library file into your
Apache modules folder.
```shell
(For Debian/Ubuntu, it is /usr/lib/apache2/modules)
```
3) Include this line in your server config context.
```shell
LoadModule connectivity_analyser_module <path to modules folder>/mod_connectivity_analyser.so
(For Debian/Ubuntu, it is in
/etc/apache2/mods-available/<module configuration file>)
```
4) Update your VirtualHost configuration by using the following directive.
It must be inside the Directory or Location section.
```shell
Cacheck On
(For Debian/Ubuntu, it is in
/etc/apache2/sites-available/<your configuration file>)
```
### Results ###
When using the Conectivity 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 Conectivity 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
CacookieExpires 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
<VirtualHost:80>
...
<Directory />
Options FollowSymLinks
AllowOverride None
</Directory>
<Directory /var/www/>
Options Indexes FollowSymLinks MultiViews
Cacheck On
Cacookie On
CacookieExpires 86400
AllowOverride All
Order allow,deny
allow from all
</Directory>
```
## Step by step ###
```php
<?php
// Getting information through the HTTP response headers ...
$infos = apache_response_headers();
// Or through the 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 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><a href="README.ConnectivityAnalyser-Nginx.html">NGINX DeviceAtlas Connectivity Analyser</a></li><li class="disabled"><a href="README.ConnectivityAnalyser-Apache.html">Apache DeviceAtlas Connectivity Analyser</a></li><li><a href="ApiDocs/index.html">DeviceAtlas ApiDocs</a></li></ul></div>]]>