<![CDATA[
# DeviceAtlas Cloud Client API Configuration #
This section deals with configuring the DeviceAtlas Cloud API.
The DeviceAtlas Cloud Client API is configured via setter methods at runtime.
The only required setting is your DeviceAtlas licence key.
The API provides a number of cache providers and each has a configuration file
located in the Api/config directory. The configuration file for the selected
cache provider must be available on the classpath.
### Caching ###
The API can cache the returned data after a call to the DeviceAtlas Cloud service,
this speeds up subsequent requests as it avoid a network request round trip.
The client API provides several cache solutions. It is recommended to always
use the cache if possible.
### Cloud Server end-point settings ###
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.
Cloud service provider endpoints are defined as an array of "EndPoint" objects.
Class "Server" exists in the "com.deviceatlas.cloud.deviceidentification" package.
A default Server array is built in the API but you can manually set:
```java
EndPoint[] endpoints = {
new EndPoint("SERVER-HOST-ADDRESS", SERVER-PORT),
new EndPoint("SERVER-HOST-ADDRESS", SERVER-PORT)
};
client = Client.getInstance();
client.setEndPoints(endpoints);
```
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 and turn auto-ranking off. 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
by client.setAutoServerRankListLifetime(1440).
* 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:
```java
if
EndPoint list contains 3 endpoints
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:
```java
EndPoint[] rankedServerList = client.getEndPoints();
```
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:
```java
EndPoint endpoint = 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:
```java
EndPoint[] endpoints = client.getServersLatencies();
```
Please see https://deviceatlas.com/resources/cloud-service-end-points for more
information.
#### client.setAutoServerRanking(true) ####
To turn auto ranking on/off. To manually rank the servers set to "false"
and edit the SERVERS list to set your preferred order of end-points.
The API will not rank the servers and will use the 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.
#### client.setCloudServiceTimeout(2) ####
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.setAutoServerRankingMaxFailures(1) ####
When auto ranking servers, if a server fails more than this number of
times it will not be included in the list.
#### client.setAutoServerRankingNumRequests(3) ####
When auto ranking servers, number of requests to perform for service
speed calculation.
#### client.setServerRankingLifetime(1440) ####
In the case of auto ranking, it is the time in minutes of 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:
DeviceAtlasCloudClient.rankServers();
In the case of manual ranking, 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.
### Usage with Client Side Component ###
This script gathers the properties and
creates a cookie containing them. This cookie is sent to the server on the next
request. Both client side and server side properties are merged and additional
logic is used to determine other properties such iPhone and iPad models which
are normally not detectable.
By default, if the cookie exists it will be used by the API. To disable using
the client side cookie:
```java
client.setUseClientCookie(false);
```
### Proxy usage ###
The API May also route via a proxy by configuring the API with a `java.net.Proxy`
object. The following code example shows how to pass a Proxy instance to the API.
```java
try {
/* get the API instance (singleton) */
Client client = Client.getInstance();
/* set your licence key */
client.setLicenceKey(LICENCE_KEY);
/* set your Proxy instance */
client.setProxy(proxy);
} catch (ClientException ex) {
/* handle the errors */
} catch (CacheException ex) {
/* handle the errors */
}
```
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 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><a href="README.Installation.html">Cloud Client API Installation</a></li><li class="disabled"><a href="README.Config.html">Cloud Client API Configuration</a></li><li><a href="./Javadoc/index.html">DeviceAtlas Cloud Client API doc</a></li></ul></div>]]>