# DeviceAtlas Cloud Client API details # DeviceAtlas Cloud Client API requires several dependencies. ### DeviceAtlas Cloud Client API Dependencies ### #### Cache providers #### DeviceAtlas Cloud Client API requires a cache provider to cache device data and cloud end-point lists. The API also comes with two cache providers: FileCacheProvider (file based) SimpleCacheProvider (memory based). The API includes a cache provider interface to allow for custom caching solutions. #### Java Requirements #### The API requires at least Java 6. The methods `getResult(HttpServletRequest request)` and `getDeviceData(HttpServletRequest request)` must only be used inside a servlet container. The other getResult / getDeviceData methods may be used outside a servlet container and do not require the JavaEE libraries on the classpath. ### Installation ### The DeviceAtlas Cloud API can be added as a dependency to a project using either Maven or Gradle. #### Gradle #### The following configuration should be added to the build.gradle file in the project: ``` dependencies { implementation(group: "com.deviceatlas", name: "deviceatlas-cloud-java-client", version: '2.0.0') implementation(group: "ch.qos.logback", name: "logback-core", version: '1.1.3') implementation(group: "ch.qos.logback", name: "logback-classic", version: '1.1.3') } ``` #### Maven #### The following configuration should be added to the pom.xml file in the project: ```xml <dependencies> <dependency> <groupId>com.deviceatlas</groupId> <artifactId>deviceatlas-cloud-java-client</artifactId> <version>2.0.0</version> </dependency> <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-core</artifactId> <version>1.1.3</version> </dependency> <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-classic</artifactId> <version>1.1.3</version> </dependency> </dependencies> ``` ### Client Side Component ### In addition to the properties from the Cloud API, properties can be gathered from the client's browser and used both on the client side and on the server side. It is strongly recommended to use the Client-side component when using the DeviceAtlas Cloud API within a web application in order to correctly identify iOS devices. The client side resource `<script type="text/javascript" src="https://cs-cdn.deviceatlas.com/dacs.js"></script>` must be included on your webpage in order for it to detect the client side properties. The contents of this cookie are automatically detected by the API. Please click [here](https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html) for more information. By default, if the cookie exists it will be used by the API. To disable using the client side cookie: ```java client.setUseClientCookie(false); ``` ### Configuration ### 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. ### Basic Usage ### The DeviceAtlas Cloud Client API can be used as follows: * Import: ```java import com.deviceatlas.cloud.deviceidentification.client.Client; import com.deviceatlas.cloud.deviceidentification.client.Result; import com.deviceatlas.cloud.deviceidentification.client.Properties; import com.deviceatlas.cloud.deviceidentification.client.ClientException; import com.deviceatlas.cloud.deviceidentification.cacheprovider.CacheException; import com.deviceatlas.cloud.deviceidentification.cacheprovider.CacheProvider; import com.deviceatlas.cloud.deviceidentification.cacheprovider.FileCacheProvider; import java.util.HashMap; import java.util.Map; ``` * Get an instance of the API (singleton), set your DeviceAtlas licence key and request properties from DeviceAtlas Cloud. In a servlet container with a HttpServletRequest object: ```java try { /* First time usage, the cache provider needs to be set */ Client client = Client.getInstance(new FileCacheProvider()); /* for further use get the API instance (singleton) */ Client client = Client.getInstance(); /* set your licence key */ client.setLicenceKey(licenceKey); /* get the device properties - by request object */ Result result = client.getResult(request); Map<String, String> headers = result.getHeaders(); Properties properties = result.getProperties(); } catch (ClientException ex) { /* handle the errors */ } catch (CacheException ex) { /* handle the errors */ } ``` Detecting based on a set of HTTP headers: ```java Map<String, String> headers = new HashMap<String, String>(); headers.put("user-agent", "THE USER AGENT ..."); /* add more headers .*/ try { /* get the API instance (singleton) */ Client client = Client.getInstance(new FileCacheProvider()); /* set your licence key */ client.setLicenceKey(licenceKey); /* get device properties - by passing HTTP headers */ Result result = client.getResultByHeaders(headers); Properties properties = result.getProperties(); } catch (ClientException ex) { /* handle the errors */ } catch (CacheException ex) { /* handle the errors */ } ``` Detecting based on a User-Agent string: ```java String userAgent = "THE USER AGENT ..."; try { /* get the API instance (singleton) */ Client client = Client.getInstance(new FileCacheProvider()); /* set your licence key */ client.setLicenceKey(licenceKey); /* get device properties - by passing a user agent string */ Result result = client.getResultByUserAgent(userAgent); Properties properties = result.getProperties(); } catch (ClientException ex) { /* handle the errors */ } catch (CacheException ex) { /* handle the errors */ } ``` * Use the device properties: ```java if (properties.containsKey("mobileDevice") && properties.get("mobileDevice").asBoolean()) { /* example 1: Get the screen width for image optimization */ int displayWidth = properties.containsKey("displayWidth")? properties.get("displayWidth").asInteger(): 100; /* example 2: Get the device vendor name */ String vendor = properties.containsKey("vendor")? properties.get("vendor").asString(): ""; /* example 3: Touch screen optimization */ boolean useBiggerIcons = properties.containsKey("touchScreen")? properties.get("touchScreen").asBoolean(): false; /* example 4: Send Geo Location JS to client? */ boolean supportsGeoLocation = properties.containsKey("js.geoLocation")? properties.get("js.geoLocation").asBoolean(): false; } ``` See the list of all property names here: https://deviceatlas.com/resources/available-properties The availability of a property depends on the device and your licence, before accessing a property always check if it exists in the set or not. ### 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(licenceKey); /* set your Proxy instance */ client.setProxy(proxy); } catch (ClientException ex) { /* handle the errors */ } catch (CacheException ex) { /* handle the errors */ } ``` ### Examples ### The package contains a number of examples to demonstrate the API features, usage and some possible use cases. They are split into sample command line and web applications. 1. Basic command line example to show basic usage. 2. A Spring Boot application to show more complete examples of sample use cases. The examples can be compiled with either Maven (3.x version) and Gradle. #### Command line example #### The command line example shows basic usage of the API and can be e found at `./Examples/CommandLine`. Please see the `README.md` file in the folder for usage instructions. #### Web application example #### The Web application example uses the Spring Boot framework and embeds a web server in the final Jar to allow for easy execution on the command line and avoids the need to deploy within an application server. The web example can be found at `./Examples/WebApp`. Please see the `README.md` file in the folder for usage instructions. ### 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. 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. #### Cloud Server end-point settings #### ##### 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. ### Support ### Please contact <support@deviceatlas.com> . - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _Copyright (c) 2021 by DeviceAtlas Limited. 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.CloudApi.html">Cloud Client API details</a></li><li class="divider"></li><li><a href="Javadoc/index.html">DeviceAtlas Cloud Client API docs</a></li></ul></div>