<![CDATA[
# DeviceAtlas Cloud Client API Configuration #
This section deals with configuring the DeviceAtlas Cloud API.
### Caching ###
The API can cache the returned data after a call to the DeviceAtlas Cloud service,
this will speed up subsequent requests.
The API has a file caching mechanism. It is recommended to always use the file
cache if possible.
The file cache stores the returned properties on your server disk. The cache
location is typically the system temp directory but this can be overridden with
the "$client->setCacheDir('path/to/dir')" method. Items in the cache expire after a set time
period to ensure the data is up-to-date. This cache is enabled by default. It is
recommended to always have file caching enabled even when you are using cookie
cache.
Items in the cache expire after a set time period to ensure the data is up-to-date.
### DeviceAtlas Cloud Service End-points ###
The DeviceAtlas Cloud Service is powered by independent clusters of servers
spread around the world. This ensures optimum speed and reliability. The API is
able to automatically switch to a different end-point if the current end-point
becomes unavailable. It can also (optionally) auto-rank all of the service
end-points to choose the end-point with the lowest latency for your location.
The Cloud service end-points are defined in the $servers variable at the top of
the "Client.php" file.
```php
$SERVERS = array(
array('host' => 'server1-url', 'port' => server1-port),
array('host' => 'server2-url', 'port' => server2-port),
array('host' => 'server3-url', 'port' => server3-port),
);
```
By default the API will analyze the end-points from time to time to rank them by
their stability and response speed. The ranked list is then cached and used
whenever the Client API needs to query the DeviceAtlas Cloud Service. If an end-
point fails, the Client API will automatically switch to the next end-point on
the list.
There is no need to set the servers array if auto-ranking is turned on. If you
wish, you may re-order the array (`$client->setServers()`) and turn auto-ranking off (`$client->setAutoServerRanking(false)`).
In this case the API will respect your preferred order of end-points and only switch to a different
end-point should the primary one fail to resolve.
#### Notes ####
* With the default auto-ranking settings, the ranking is done every 24 hours.
The actual time may be more than 24 hours as the ranking is only triggered by
a request to the Client API and the cached server list is older than value
set to AUTO_SERVER_RANKING_LIFETIME.
* During end-point analysis a number of requests are made to each end-point.
Please note that these requests count towards your total hits to
the Cloud service.
e.g:
```php
if
Server list contains 3 servers
AUTO SERVER RANKING LIFETIME = 1440
AUTO SERVER RANKING NUM REQUESTS = 3
then
auto ranking will add 9 (3x3) hits per day
```
#### Methods ####
* Get the ranked server list:
```php
$rankedServerList = $client->getServers();
```
The first end-point in the list will be used to make a request to the cloud, if
it fails the next end-point will be take it's place.
* Get the end-point used for the last request:
```php
$server = $client->getCloudUrl();
```
Note that if the data comes from cache this method will return "null".
* Get end-point info. This is useful when you want to manually rank the server list:
```php
$server = $client->getServersLatencies();
```
Please see https://deviceatlas.com/resources/cloud-service-end-points for more
information.
#### Cloud Server end-point settings ####
##### AUTO SERVER RANKING (default enabled) #####
To turn auto ranking on/off. To manually rank the servers disable auto server ranking
(`$client->setAutoServerRanking(false)`) and provide an array of servers ($client->setServers()).
The API will not rank the servers and will use the provide servers list items
directly with the topmost server used first to get device data. On fail-
over the next end-point in the list will be used.
##### CLOUD SERVICE TIMEOUT (default 2 seconds) #####
Time in seconds. If an end-point fails to respond in this amount of time
the API will fail-over to the next end-point on the list.
`$client->setTimeoutSeconds()`
##### AUTO SERVER RANKING MAX FAILURE (default is one failure) #####
When auto ranking servers, if a server fails more than this number of
times it will not be included in the list.
`$client->setAutoServerRankingMaxFailures()`
##### AUTO SERVER RANKING NUM REQUESTS (default is 3 requests) #####
When auto ranking servers, number of requests to perform for service
speed calculation.
`$client->setAutoServerRankingNumRequests()`
##### AUTO SERVER RANKING LIFETIME (default is 1440 minutes) #####
Time in minutes. How often to auto rank servers.
0 = servers will be ranked and cached only once and this list will not be
updated automatically. You can update this list manually:
``$client->rankServers();`
Note: `$client->setAutoServerRanking()` must be set "true" so this cached server list
will be used by the API, even if `$client->setAutoServerRankingLifetimeMinutes()` is set to 0.
If `$client->setAutoServerRanking()` is false then the cached server list will be
totally ignored.
##### SERVER PHASEOUT LIFETIME (default is 1440 minutes) #####
Time in minutes. Used when auto ranking is OFF. Specifies how long to use the fail-over
endpoints before the preferred end-point is re-checked. If the preferred
end-point is available it will be added back into the list of end-points
and used for future requests.
`$client->setServerPhaseoutLifetimeMinutes`
### Extra Tools ###
This package comes with extra tools that can help you enhance your mobile websites.
#### Latency Checker ####
There are two command line tools included in this package to help you tweak the
DeviceAtlas Cloud API end-point selecting.
##### Check Server Latency #####
This tool can be used to get info about the DeviceAtlas Cloud Service end-points.
The info shown can be used for manually setting up the DeviceAtlas Clous service
end-points in the API. To access the cloud servers a valid DeviceAtlas licence
would be required.
Usage (command line):
```php
php /path/to/ExtraTools/LatencyChecker/CheckServerLatency.php
```
##### Update Server Ranking Cache #####
When AUTO_RANKING is set ON you can use this tool to re rank the DeviceAtlas Cloud
end-points. All you need to do is to run this script in regular intervals which
are smaller than the "AUTO_SERVER_RANKING_LIFETIME".
Usage (command line):
```php
php /path/to/ExtraTools/LatencyChecker/UpdateServerRankingCache.php
```
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Ltd 2023. 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">Cloud Client API</a></li><li class="disabled"><a href="README.Config.html">Cloud Client API Configuration</a></li><li class="divider"></li><li><a href="./ApiDocs/index.html">DeviceAtlas Cloud Client API docs</a></li></ul></div>]]>